Getting Started with Payments Orchestrator

Duck Creek Payments Orchestrator lets you collect money or issue payouts or rewards. This Getting Started guide is designed to walk you through the quickest and simplest steps that you can follow to see the core functionality of the application.

Who is this guide for?

If you are just starting your journey with Payments Orchestrator and are eager to learn what it can do, this guide is for you. This guide is also for you if you want to refresh your knowledge on the basic functionality of the application.

Who is this guide not for?

If you want to explore all the features available in Payments Orchestrator, this guide is not for you. See User Guide for in-depth information on all available features.

Before You Start

Before you start using this guide, there are a few prerequisites that you will need to meet. Some of the following prerequisites, as "Setup an Account" and "Setup a Tenant" might only be required once. If you have already completed the following setup, you can directly jump to the Four Steps that Demonstrate the Payments Orchestrator Platform.

Understand Payments Orchestrator-related Terms

This guide assumes that you are familiar with the basic terminologies used throughout the application. See Concepts for a list of all the terminologies used.

Set up an Account for an Account API Key

When you complete your registration with Duck Creek, you will receieve an Account. You will have to set up your Account to obtain an Account API Key.

Set up a Tenant

You can create as many Tenants as you need.

Once you have an Account, you must set up at least one Tenant. Setting up a Tenant usually involves the following:

Four Steps that Demonstrate the Payments Orchestrator Plaform

At Duck Creek, we believe in experimenting with the product in addition to reading guides about it. We invite you to perform the following steps:

Authenticate your Identity
Create an Order and Instruction
Load Checkout Component
Get Transaction Status

Step 1: Authenticate your Identity

Just as you would require a password to access your email address or a key to unlock the door at your house, Payments Orchestrator also requires a key from you before you can access any features. Payments Orchestrator uses this key to prevent anyone who doesn't have access to your tenant from accessing your information. Payments Orchestrator uses an industry-standard HMAC token to generate the key (Access Token) that will be used to authenticate your requests.

Create and Obtain your Tenant API Key.

Tenant API Key and Account API Key are two different concepts.

Generate the HMAC Token
Create an Access Token by sending the HMAC Token to the /v1/identity/hmac endpoint
Use the Access Token in the Authorization header of your following API requests

For full context about authentication used on Payments Orchestrator API requests check UserJourney : Authenticate your API Requests

Step 2: Create Instruction(s) and Order

Whether you want to pay out, collect a one-off payment or collect recurrently, the payment intent to transact with Payments Orchestrator starts with Instruction(s) and an Order that can aggregate the Instruction(s). Instructions, as the name suggests, are the rules (e.g., how much to collect/pay, when to collect/pay, currency) that Payments Orchestrator will follow to complete a transaction. An Order is a group of these instructions.

Get the schemeId from one of the schemes you created while setting up the Tenant.
Follow the API Reference documentation on Create Instruction to create the request body for Instruction(s) using the schemeId

Set the direction property to Debit for collection and Credit for rewards payout.
To collect recurrently or schedule future payments, set the value of the settledByDate property to the date when Payments Orchestrator should process the payment.

Follow the API Reference documentation on Create Order to create the request body for the Order that will group the Instruction(s) you've created.

Step 3: Load Checkout Component

Orders and Instructions define the details of transaction. To complete the transaction, your customers must provide the details of the Financial Instrument they want to use. Payments Orchestrator offers a Checkout component (a secure and user-friendly interface) that you can present to your customer to collect the details of their Financial Instruments.

Use the orderRef value you set while creating Orders and instructionRef value you set while creating Instructions to create request body for generating Session Token.
Load the Checkout Component using the Session Token and present it to your customers.

When a customer submits the details of their Financial Instruments, Payments Orchestrator will automatically fill the financialInstrumentId property in the original Instruction that was used to generate the Session Token. You can reuse the financialInstrumentId for future Instructions against the payments with the same details and the same customer. Set the settledByDate property in future Instructions to reuse the financialInstrumentId.

Step 4: Get Transaction Status

Once your customer submits the Financial Instrument and the Payment Service Provider processes the submission, you will be curious to know whether the transaction was successful. Payments Orchestrator provides two different methods to get a report on the status of your transaction.

While you can opt for only one of the following two methods, it is strongly suggested that you use both methods for a more robust solution.

API Polling

You can autonomously poll the Get Instruction endpoint to receive a response that contains the information about the state of the transaction. You can also poll this endpoint to get the information about the transaction as it passes through the various states of the payment cycle.

Webhook Notifications

If you don't want to poll the Get Instruction endpoint but rather want near real-time notifications to inform you once the transaction has reached its final state, configure webhooks to send you notification. You can also configure webhooks to send you notification as the transaction progresses through different states of the payment cycle.