Use Case: Direct Debit

Problem

Insurers already use Direct Debit to collect recurring payments from their customers. However, having large customer bases across the globe requires insurers to use different Direct Debit payment schemes and for this, insurers need to integrate with multiple providers and deal with decentralized direct debit reports. IT integrations with payment providers are long, complex, and expensive, leaving insurers struggling to offer a seamless payment collection experience to their customers. Additionally, paper mandates are still being widely used, which hinders the day-to-day operations of mandate storage and management.

Solution

Duck Creek Payments Orchestrator offers connectivity to the entire payments ecosystem. Through a single connection, insurers can execute SEPA, Bacs, BECS or ACH Direct Debit, and provide their policyholders with a frictionless payment experience. Our platform enables integrations with any payment provider or method available in any market. Moreover, the Payments Orchestrator application provides an automated Direct Debit scheduler along with a paperless mandate management tool that allow you to easily store, update and manage Direct Debit mandates.

Prerequisites

In order to work with Direct Debit, ensure the following.

You have access to the Tenant Portal
You have generated valid API Keys.
You have installed and configured the Marketplace Apps with the relevant credentials.
You have created and configured a Collect Scheme.
You have a Creditor Profile and a Mandate Provider configured in the Tenant Portal

Supported Apps and Payment Methods

Bank of America ACH Direct - ACH Debit
BNZ File Transfer - BECS Direct Debit
Bottomline - Bacs Direct Debit
Citi Group - SEPA Direct Debit
GoCardless - SEPA and Bacs Direct Debit
NAB Direct Link - BECS Direct Debit
Worldpay VAP - ACH Debit

Available Direct Debit Options

Options are available to work with Direct Debit using the following methods:

Working with Direct Debit Using the Whitelabel Solution
Working with Direct Debit Using the Mandate API

Working with Direct Debit Using the Whitelabel Solution

Step 1: Authenticate

The first step to using the Payments Orchestrator API is to authenticate yourself by generating an Access Token. See Authenticate your API Requests for more information.

Step 2: Define your Payment Intention

For every collection, you need to set the value of the direction property to Debit.

Create your Order and Instruction and make a call to the create-order endpoint. See Define Your Payment Intention for more information.

POST URL OrderRequest Header SampleRequest Body Sample

Copy

Copied

https://sandbox-api.imbursepayments.com/v2/order-management

Copy

Copied

Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json

Copy

Copied

{
	"orderRef": "order_direct_debit",
	"instructions": [
		{
			"instructionRef": "direct_debit_payment ",
			"customerRef": "DEEPAK_004",
			"direction": "DEBIT",
			"financialInstrumentId": "",
			"amount": "110.00",
			"currency": "GBP",
			"country": "GB",
			"schemeId": "4E1E8D9F022E7A6A09FAEB71992E7F2F",
             		"settledByDate": "2022-12-01",
			"metadata": {}
		}
	]
}

Step 3: Generate Checkout Session Token

The billing details of the customer are optional. However, it is strongly recommended that you set the values for the billing details properties. The values of the orderRef and instructionRef properties should be the the same as in Step 2: Define Your Payment Intention.

Copy the value of orderRef and instructionRef properties from Step 2: Define Your Payment Intention and use them to create the request body of the Create session token endpoint.

POST URL OrderRequest Header SampleRequest Body SampleResponse Body Sample

Copy

Copied

https://sandbox-api.imbursepayments.com/v2/whitelabel-customer/session/checkout

Copy

Copied

Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json

Copy

Copied

{
    "orderRef": "order_direct_debit", 
    "instructionRef": "direct_debit_payment",
    "expirySeconds": "6000",
    "billingStreet1": "45 Braemar Rd",
    "billingStreet2": "", 
    "billingCity": "Ballater", 
    "billingState": "Aberdeenshire", 
    "billingCountry": "UK", 
    "billingPostCode": "AB35 5RQ", 
    "customerEmail": "deepak.chopra@mymail.com", 
    "cardholderName": "Deepak Chopra"
}

Copy

Copied

{
    "sessionToken": "73GMJdRQdkyselgaZ8z…………………….CMc0KBpMtY",
    "expires": 1660701819
}

When you make a successful call to the Payments Checkout token endpoint, you will receive a response with two properties: expires and sessionToken. The value shown next to the expires property is the date and time that the token will expire. This value is a Unix (Epoch) timestamp. Use this form to convert the Unix timestamp to a human-readable date.

Epoch

Step 4: Embed the Checkout Token

The checkout session token can be used with a Pay-By-Link object or with the Checkout web component that can be placed on your checkout page using an iFrame. To learn how to embed the checkout token into an iFrame, see Embed Checkout Token.

To use the token as Pay-By-Link object, set the value of the sessionToken property as the value of the token query string in your URL.

URL Syntax - https://sandbox-checkout.imbursepayments.com/?token=(sessionToken)
URL Example - https://sandbox-checkout.imbursepayments.com/?token=%2ff3kKKK...V6FmE

Step 5: Check the Payment Status

After the Financial Instrument details of your customer have been submitted to Payments Orchestrator, the application will communicate with the Payment Service Provider (PSP) to handle the transaction. You can check the status of the transaction by polling the APIs. Alternatively, you can also set up a Webhook to notify you every time the transaction status changes.

URL to GET SampleRequest Header SampleResponse Body Sample

Copy

Copied

https://sandbox-api.imbursepayments.com/v1/order-management/order_xnv6h1n/instruction/inst_xnv6h1n

Copy

Copied

Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json

Copy

Copied

{
    ...
    "direction": "DEBIT",
    "status": "INCOMPLETE",
    "customerRef": "DEEPAK_004",
    "amount": 110.00,
    "currency": "GBP",
    "country": "GB",
    "settledByDate": "2022-12-01",
    "forecastedSettlementDate": null,
    "actualSettlementDate": null,
    ...    
    "transaction": {
      ...
      "status": "PROCESSING",
      ...
    },
    "failed": null,
    "cancelled": null
}

Steps 2 and 3 can be performed in reverse order if necessary. If you wish to set up the financial instrument (the Direct Debit Mandate) without the payment intention, you can make a request to create a financial instrument session token endpoint first, then create the payment intention (order and instruction) afterwards.

Working with Direct Debit Using the Mandate API

Step 1: Authenticate

The first step to using the Mandate API is to authenticate yourself by generating an Access Token. See Authenticate your API Requests for more information.

Step 2: Capture the Mandate

For every collection, you need to set the value of the direction property to Debit.

Make a call to the mandates endpoint.

POST URL MandatesRequest Body Sample

Copy

Copied

https://sandbox-api.imbursepayments.com/v2/mandates

Copy

Copied

{
   "customerRef":"customer1",
   "creditorProfileRef":"fb39d6eb3ac44d6597f0f7221da5e663",
   "mandateType":"AchB2C",
   "authorizationSource":"WEB",
   "debtor":{
      "firstName":"John",
      "lastName":"Smith",
      "email":"JohnDangerSmith@imbursepayments.com",
      "phoneNumber":"2024561111",
      "address":{
         "houseNumberOrName":"The White House",
         "streetAddress":"1600 Pennsylvania Avenue NW",
         "postcode":"20500",
         "city":"Washington",
         "state":"DC",
         "country":"US"
      },
      "accountHolderName":"MR J SMITH",
      "accountNumber":"123113000386900",
      "accountType":"Checking",
      "routingNumber":"020190231"
   }
}

Step 3: Create an Instruction

The financial instrument ID created in Step 2 must be associated with the instruction.

Copy

Copied

{
	"orderRef": "order_direct_debit",
	"instructions": [
		{
			"instructionRef": "direct_debit_payment ",
			"customerRef": "DEEPAK_004",
			"direction": "DEBIT",
			"financialInstrumentId": "6308586e-73b0-cb6a-1091-804261cd0752",
			"amount": "110.00",
			"currency": "GBP",
			"country": "GB",
			"schemeId": "4E1E8D9F022E7A6A09FAEB71992E7F2F",
             		"settledByDate": "2022-12-01",
			"metadata": {}
		}
	]
}

Step 4: Check the Payment Status

URL to GET SampleRequest Header SampleResponse Body Sample

Copy

Copied

https://sandbox-api.imbursepayments.com/v1/order-management/order_xnv6h1n/instruction/inst_xnv6h1n

Copy

Copied

Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json

Copy

Copied

{
    ...
    "direction": "DEBIT",
    "status": "INCOMPLETE",
    "customerRef": "DEEPAK_004",
    "amount": 110.00,
    "currency": "GBP",
    "country": "GB",
    "settledByDate": "2022-12-01",
    "forecastedSettlementDate": null,
    "actualSettlementDate": null,
    ...    
    "transaction": {
      ...
      "status": "PROCESSING",
      ...
    },
    "failed": null,
    "cancelled": null
}