Create Order and Instructions

We recommend that you use the sandbox environment for accessing the APIs, if you are trying to create Orders and Instructions for the first time.

This document outlines the generic process associated with Orders and Instructions. For specific use case, visit the Use Case section of this site.

Order and Instructions sit at the very heart of Duck Creek Payments. They inform the application about your intention to collect or issue payouts to your customers.

Payments lets you leverage the flexibility of JSON-based objects to create Orders and Instructions. You can then pass the JSON objects through the Order Management APIs to start making payments or collections.

Follow this guide to learn all about how Orders and Instructions are used in Payments.

Before you Start

Before you start following this guide, you should understand the concepts related to the Payments application. You should have already created the Scheme you want to use.

How it works?

After you have constructed the JSON object for Orders and Instructions and have made a call to the Order Management APIs, Payments creates Orders and Instructions.
Then, you request a checkout token (or a Pay-By-Link object) through the White-Label service APIs.
You will have to embed the token to your checkout UI component or send the the link to your customers.
The user will then submit their Financial Instrument details through the UI components and Payments will communicate with the Payment Service Provider (PSP) to handle the transaction.
Once the transaction is complete, a notification will be sent through the Webhook. If you haven't setup a Webhook, you can poll the APIs to check if the transaction has been completed.

How to Process Order and Instructions?

If you are trying to create Orders and Instructions for Payout using the Payments APIs, you must create a relevant Financial Instrument before proceeding with the steps below.

Step 1: Authenticate yourself

The first step in creating Order and Instructions start by authenticating yourself. See Authenticate your API Requests for more information.

Step 2: Define your payment intention

You can define your payment intention by constructing request body for the create-order endpoint and making a call to the endpoint. This endpoint is a part of the Order Management APIs. Follow the API documentation to learn more about the properties associated with the endpoint.

You can find the schemId from the Tenant portal by clicking on the Scheme you want to use with payment intention.

You must set the value of the financialInstrumentId property in the request body, if you are constructing payment instruction for Payout. You must also set the value of the direction property to Credit.

Request Body SyntaxRequest Body Example CollectionRequest Body Example Payout

Copy

Copied

{
  "orderRef": "<string>",
  "instructions": [
    {
      "instructionRef": "<string>",
      "customerRef": "<string>",
      "direction": "<string>",
      "FinancialInstrumentId": "<string>",
      "amount": "<currency>",
      "currency": "<string>",
      "country": "<string>",
      "schemeId": "<string>",
      "settledByDate": "<Date in ISO 8601 format>",
      "metadata": {
        "<customField>" : "<string>"
        ...
      }
    }
  ]
}

Copy

Copied

{
  "orderRef": "order_Collect_01",
  "instructions": [
    {
      "instructionRef": "PAYMENT-01",
      "customerRef": "customer_01",
      "direction": "DEBIT",
      "FinancialInstrumentId": "",
      "amount": "10.00",
      "currency": "GBP",
      "country": "UK",
      "schemeId": "4E1E8D9F022E7A6A09FAEB71992E7F2F",
      "settledByDate": "2022-12-01",
      "metadata": {
      }
    }
  ]
}

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": "UK",
      "schemeId": "62518C8474D3C5472DDCAF51C2136412",
      "settledByDate": "2022-12-06",
      "metadata": {
      }
    }
  ]
}

Step 3: Call the Payments White-label Service API

If you are trying to create Orders and Instructions for Payout using Payments APIs, you do not need to complete this step.

After you have created an intention for payment, you need to direct your customers to the UI where they will enter their Financial Instrument detail. For that reason, you will have to associate the intention with the UI. You can choose either of the following options to associate the intention with the UI.

Request a session token and embed it to the webpage that will hold Payments' checkout UI.
Send a link generated by the Pay-By-Link endpoint.

The billing details in the request body of Create session token endpoint are optional. The values of the orderRef and instructionRef properties should be the the same as in Step 2: Define your payment intention.

Step 4: 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 once the transaction has been completed.

Troubleshooting

What do I do with the checkout token?

You can embed the checkout token into the iFrame of your website. See Embed Checkout Token for more information.

My transaction has failed. Can I retry using the same Order and Instructions?

You can retry using the same Order and Instructions. However, ensure that the details provided in the intetion are correct.