Use Case: Mail Order/Telephone Order Card Collections

Problem

Carriers need a method of handling Mail Order/Telephone Order (MO/TO) transactions when a customer makes a card payment over the phone or through the mail, for example via a back-office operative or with the help of an underwriter.

Solution

Duck Creek Payments Orchestrator supports the ability to collect premium payments via MO/TO. This enhances the card tokenization feature by allowing carriers to tokenize cards without needing to charge the policyholder immediately.

Prerequisites

In order to work with MO/TO card collections, 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 enabled MO/TO Payments in the App that is relevant to your use case.
You have created and configured a Collect Scheme that supports MO/TO card payments.

Supported Apps and Payment Methods

Stripe - Cards

Working with MO/TO Card Collections

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_card_payment",
	"instructions": [
		{
			"instructionRef": "inst_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 make create the request body of the Create session token endpoint.

The Authorization Source attribute will identify the flow for how payments should be initiated. For a complete explanation, see the concept page.

Your Financial Instruments will always have an Authorization Source (authorizationSource) attribute. It has a default of WEB unless you have specified a different value.

For Collections, the Authorization Source value will default to 'WEB' for the B2C customer type. For the B2B customer type, this will default to PAPER.

For Payouts, the Authorization Source value will default to PAPER.

Authorization Source	Description
`WEB` (SCA)	Scenario where the customer is manually inputting their payment details into the payment solution.
`PAPER` (MO/TO)	Scenario where the customer has provided their payment details to an employee in writing and signed, or similarly authenticated.
`TEL` (MO/TO)	Scenario where the customer has provided their payment details verbally to an employee over the telephone.

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_card_payment", 
    "instructionRef": "inst_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",
    "authorizationSource": "PAPER"
}

Copy

Copied

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

When you make a successful call to the Payments Orchestrator's 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

To create a session that is intended to trigger a Strong Customer Authorization (SCA) flow, the value of authorizationSource must be WEB, depending on the customer journey being followed.

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 has 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",
      ...
    },
    "isMoto": "true",
    "failed": null,
    "cancelled": null
}