Use Case: Payout

Problem

Payouts are a crucial moment for any insurer. There could be cases where insurers also need to propose a wide variety of reimbursement methods while offering immediate compensation. However, this flexibility requires integrating and leveraging multiple providers, which is often a stumbling block for enterprises because it is costly, time-intensive, and resource-draining to create and manage so many integrations.

Solution

Duck Creek Payments acts as your single access point to the payments ecosystem. Payments does all of the heavy lifting, providing quick access to relevant payment providers and methods. The application can easily integrate with core insurance IT systems to support any payout mechanism. It is efficient enough not to cause disruption to your day-to-day operations and quick enough to process payout.

Prerequisites

In order to work with Payout, 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 Payout Scheme.

Supported Apps and Payment Methods

Bank of America ACH Direct - ACH Credit
BNZ File Transfer - BECS Direct Credit
Bottomline - Bacs Direct Credit
Citi Group - SEPA Credit Transfer, SEPA Instant Credit, Faster Payments UK
NAB Direct Link - BECS Direct Credit
Tango - Rewards

Available Payout Options

Options are available to handle the following scenarios:

Direct Payment into Bank Account
Rewards

Working with Payouts - Direct Payment into Bank Account

These steps can be used when you are making a claim payout or a payout to third party brokers directly into the recipient's bank account.

Step 1: Authenticate

The first step to using the Payments 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 payout, you need to set the value of the direction property to Credit.

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_credit",
	"instructions": [
		{
			"instructionRef": "direct_credit_payment ",
			"customerRef": "DEEPAK_004",
			"direction": "CREDIT",
			"financialInstrumentId": "",
			"amount": "110.00",
			"currency": "GBP",
			"country": "GB",
			"schemeId": "4E1E8D9F022E7A6A09FAEB71992E7F2F",
             		"settledByDate": "2022-12-01",
			"metadata": {}
		}
	]
}

Step 3: Generate Checkout Session Token

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_credit", 
    "instructionRef": "direct_credit_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, 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": "CREDIT",
    "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 Bank Account financial instrument without the payment intention, you can make a request to the create a financial instrument session token endpoint first, then create the payment intention (order and instruction) afterwards.

Working with Payouts - Rewards

These steps can be used when you have a reward being provided to a claimant via a gift card.

Step 1: Authenticate

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

Step 2: Get Payout Options

To find out what reward options can be accessed, consult the Payouts API documentation.

Step 3: Define your Payment Intention

For every payout, you need to set the value of the direction property to CREDIT.

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

Request example:

Copy

Copied

{
    "orderRef": "order_Payout_01",
    "instructions": [
        {
            "instructionRef": "PAYMENT-01",
            "customerRef": "customer_01",
            "direction": "CREDIT",
            "financialInstrumentId": "9cb4aab7-5cbe-012c-c345-00c118e66696",
            "amount": "10.00",
            "currency": "GBP",
            "country": "GB",
            "schemeId": "62518C8474D3C5472DDCAF51C2136412",
            "settledByDate": "2022-09-01",
            "metadata": {
            }
        }
    ]
}

Note: To learn the status of the payment, Payments provides a webhook notification at each status change and the possibility to poll the status through the GET instruction endpoint.

Step 4: Claim Reward

To Claim a reward, all you need is to point to the order and instruction created previously and the reward ID that was obtained earlier when getting the Payout Options. Consult the Payouts API documentation for more information.

Request example:

Copy

Copied

{
    "rewardId": "{{rewardId}}"
}

Included in the response of the request on the end of the location header will be the transactionId, which is unique to claiming this reward. Each claim will have a different transactionId. The {transactionId} placeholder will be a GUID and will look something like this: 8f482020-965f-4e9b-afb2-1e6e4336e6da. This value will be used in the next step.

Step 5: Get Reward

To learn the status of the payment, Payments provides a webhook notification at each changing status and the possibility to poll the status through the GET instruction endpoint. See the Payouts API documentation for more information.