Concepts

Portals

Portals are the user-friendly interfaces that you can use to interact with Duck Creek Payments Orchestrator functionality. Currently, there are two Portals you can interact with: Account and Tenant.

Account

In order to access your Account Portal, you must create at least one user after the Account setup is complete. If you do not have access to your account, please reach out to your Account Manager.

Once you register with the Payments Orchestrator application, you will obtain a Payments Orchestrator Account. The Account represents your organization and lets you manage licenses and billing with Payments Orchestrator. It also lets you manage multiple Users and Tenants.

You can access your account using the user-friendly interface. Alternatively, you can also use your Account API Key to manage your account through the secure REST API.

Tenant

You can add multiple Tenants to your Account as commercially agreed.

If an Account represents your organization, then Tenants represent its business units. Account Portal doesn't let you access core functionalities, Tenants do. A Tenant serves three main purposes:

Configure and Manage Marketplace Apps, Schemes, and Reports
Execute instructions
Logically isolate data and processing from other tenants as tenants don't share information with each other

Use your Account Portal to create at least one Tenant. You can then configure the Tenant through the user-friendly Tenant Portal, or directly using the REST APIs.

Environments

Once you have signed up with Payments Orchestrator, Sandbox and Production environments are provided to you. See below for more information on each of them.

Environment	Used for	REST API	Account Portal	Tenant Portal
Sandbox	Integrating and experimenting with Payments Orchestrator	https://sandbox-api.imbursepayments.com	https://sandbox-account.imbursepayments.com	https://sandbox-portal.imbursepayments.com
Production	Real-time commercial operations	https://api.imbursepayments.com	https://account.imbursepayments.com	https://portal.imbursepayments.com

Marketplace

Marketplace lists all the Payment Service Providers (PSPs) and Partners you can connect with or have connected with. You can install the Apps related to the PSPs and start using them instantly. Marketplace offers an intuitive Filter Panel that lets you search for an App by App Type, Direction, Payment Methods, Transaction Type, and Networks.

Payment Methods

There are a number of ways you can collect from or pay to your customer. Credit cards, direct to bank, gift cards, vouchers and digital wallets are examples of payment methods. The Payments Orchestrator application connects to your payment methods using Apps.

Networks

Networks refer to payment networks. These are the organizations or associations that issue a Financial Instrument for a payment method. Visa, Mastercard, American Express, and Discover are examples of Networks.

Payment Service Providers

A Payment Service Provider (PSP) is a third-party company that grants access to the payment method.

Apps

To configure your desired App, you will need an agreement with the referent PSP or Financial Institutions. Only then will you be able to obtain the PSP credentials to use with the App.

Apps refer to applications that Payments Orchestrator uses to connect to PSPs and their services. Apps are easy to install and configure. Once you have configured them, Payments Orchestrator can connect and push your payment requests through them.

App Type

In the Payments Orchestrator application, you will find two different types of Apps: Payment and Reward. Payment Apps let you pay (or collect) cash to (or from) your customer using the amount in your bank while Reward Apps let you pay your customer in Gift cards, Travel Miles or Vouchers.

Rewards

Rewards are an alternative form of payout solution that allow your customers to receive payments in the form of gift cards, travel miles, or vouchers.

Reward Groups

Reward Groups let you group multiple Rewards together.

Schemes

Schemes define a set of rules for you to collect payments, issue payouts, and track financial instruments (e.g., movements on bank accounts). Think of them as workflows. They:

Define the payment methods to present to a customer
Define the partner/PSP through which to route a specific transaction
Define the possible rewards a customer may claim
Map an incoming transaction event to the appropriate outgoing notifications

You can create two types of Schemes in Payments Orchestrator: Collect for collection and Payout for payment. Each of these types lets you set up at least one instance of Rules and Apps.

Drafts

Payments Orchestrator allows you to maintain multiple versions of a Scheme using Drafts. Drafts are copies of changes made to a Scheme's setup that you have saved. Define new setup for an active Scheme and save it as a Draft so that you can publish (or activate) that Draft later.

Rules

You can add multiple Rules within a Scheme.

Rules explicitly control a Scheme. It defines the Apps to use for a set of currencies, countries, and collection/payout amount. Whenever there is an attempt to make a collection or issue a payout, Payments Orchestrator will match the Payout/Collect attributes (currencies, countries, and amount) against each Rules within the active Schemes and present the Apps associated with the matching Rules.

Apps

If a PSP is in use across multiple Apps in a Rule, you must disable all but one instance of the PSP from the list of Apps.

In the context of a Scheme, Rules will contain the Apps. You must assign at least an App to any Rule you create.

Collect

A Collect Scheme lets you define the Rules for using Apps that will be presented to your customers to collect payments from them.

Payout

A Payout Scheme lets you define the Rules for using Apps will be used to issue a payout to your customers.

Customer Vault

The Customer Vault is an encrypted space that stores details of the Financial instruments related to a Customer, including their sensitive data. Payments Orchestrator respects your right to be forgotten and deletes the encryption keys that protect the sensitive data, whenever the conditions specified by GDPR apply.

Customer Ref

Customer Ref should not contain any personal identifiable information of the customer.

This is a unique customer reference code that should be mapped to a customer identifier on your side. It represents your customer on Payments Orchestrator.

Financial Instruments

Financial Instruments represent payment methods owned by a customer. Examples of Financial Instruments would be a Credit Card number, Bank Account Number, mobile phone number, Direct Debit Mandate, or an Authorized Reward amount.

Financial Instruments may support Credit, Debit, or Both types of transactions.

There are different ways to create these Financial Instruments, according to the type of operation and payment options desired to provide to the customer. If you use the Payments Orchestrator Whitelabel Integration and incorporate the Checkout Component, the Financial Instrument for Card Payments is automatically generated.

See Customer Vault API specification, to learn more about creating a Bank Account for payout.
See the Whitelabel service documentation to learn how Payments Orchestrator handles Credit Card sensitive customer information in a PCI-DSS compliant manner.
See Mandate Management Tool, to learn more about creating/registering a Direct Debit Mandate.

Financial Instrument States

Active: The Financial Instrument (FI) is operational and can be used for payments and premiums.
Inactive: The FI is not operational, and therefore cannot be used for payments or premiums. Inactivity reasons are recorded for clarity.
Locked: The FI has been successfully used for a single-use payment and cannot be used for further transactions.
Closed: The FI has been permanently closed by the Carrier and cannot be used for any payments or premiums.

Active State Diagram

Inactive State Diagram

Locked State Diagram

Closed State Diagram

Orders and Instructions

Orders and Instructions represent an intention to Debit or Credit an amount. They hold all the necessary details that Payments Orchestrator requires to process a collection or issue a payout on your behalf.

Direction

The Payments Orchestrator application uses the concept of direction to understand whether a transaction is supposed to be a Debit or a Credit.

Transaction Type

The Payments Orchestrator application supports two types of Transactions: Merchant initiated and Customer initiated. A Merchant initiated transaction is triggered by you whereas a Customer initiated transaction is triggered by your customer.

Debit

A transaction that deducts an amount of money from a customer's account.

Credit

A transaction that adds an amount of money to a customer's account.

Instruction

Instruction refers to the details that defines the amount to process, the Financial Instrument to use and the nature of transaction (Debit or Credit). The Apps will use these details to process the transaction. |

Order

An Order is a logical group of multiple instructions. Examples of a Order could be a policy, or a subscription.

Checkout component

Checkout component is a part of the Payments Orchestrator Whitelabel solution that features a UI where your customers will enter their card or bank details to make a payment or recieve a Rewards payout.

Checkout token

An encrypted string representing your intention for payment. This string holds the information of payment such as payment amount and currency of payment.

Theme template

A set of properties used to style the Checkout component.

Pay-By-Link

A unique offering where a secure link is generated for you in return of your payment intention. If your customers click on this link, they will be directed to a page where they can enter their Financial Instrument details.

Refunds and Claims

Chargebacks

Chargeback is a state when your funds are forcibly reversed to your customer by an issuing bank because your customer claimed that a transaction shouldn't have occured in the first place. It is also known as claim, payment dispute, reversal, indemnity, or indemnity claim.

A chargeback is initiated by a customer's request to the bank and can occur for one of the following reasons:

Fraud - Purchases that have been made without the customer's knowledge or consent
Quality - Purchases that were paid for but haven't been received
Clerical - Purchases that the customer has been billed for more than once, purchases that have been billed incorrectly, or refunds that haven't been issued
Technical - Purchases that the customer doesn't have enough funds to cover, or bank errors

Refund

Refund refers to the action of returning the amount debited from a customer's account. It can occur for multiple reasons like inability to fulfil the order placed by a customer, change of customer's mind or incorrect billing.

Authentication

Authentication is a mandatory security measure enforced by Payments Orchestrator to prevent unauthorized entities from making calls to the Payments Orchestrator API.

Payments Orchestrator APIs use Bearer tokens encoded as JSON Web Tokens (JWT) to autheticate API calls. To generate a Bearer token, you will have to call the hmac endpoint using your Account ID, Tenant ID and a secret code.

API Key

API Key refers to the set of Public and Private Keys that Payments Orchestrator APIs use to authorize the API requests you make. You will find two API Keys when you work with the Payments Orchestrator application.

Account API Key

Account API Key is used to manage your account, its tenants, including Tenant API Keys through Payments Orchestrator APIs.

Tenant API Key

Tenant API Key defines the role of a Tenant API user. Each user Role can have a different degree of control over the Tenant and its Marketplace, Schemes and Services.

A Tenant Administrator (indicated as tenant-admin), for instance, has a complete control of the tenant and can create other Tenant API Keys. Whereas, a user with tenant-management role can only view the information of the Tenant. See the table below, for a list of available roles along with the functions they have access to.

Function	Role Key for read-only access	Role Key for read-write access
All aspects of Tenant, including Users and Tenant API Keys		`tenant-admin`
Tenant information	`tenant-management`
Apps	`tenant-app-read`	`tenant-app-write`
Collect Schemes	`tenant-collect-scheme-read`	`tenant-collect-scheme-write`
Payout Schemes	`tenant-payout-scheme-read`	`tenant-payout-scheme-write`
Reward Groups	`tenant-reward-group-read`	`tenant-reward-group-write`
Transactions	`tenant-transaction-read`	`tenant-transaction-write`

We recommend that you grant the minimum necessary permissions for your Tenant API Keys.

Hash-based Message Authorization Code (HMAC)

Payments Orchestrator uses the HMACSHA256 algorithm to generate HMAC code.

HMAC is a secured and secret Authentication code used commonly with financial APIs. Payments Orchestrator uses HMAC to generate Bearer tokens.

Before you make the call to Payments Orchestrator APIs, you will have to create a unique HMAC using your Tenant API Keys (Public and Private). This HMAC is then shared with Payments Orchestrator as a part of the API request. Upon receving your HMAC, Payments Orchestrator will generate its own HMAC and compare it with the HMAC you submitted. If they match, the application will know that the request is coming from the right person i.e., you.

See our dedicated GitHub page on HMAC to learn more about the technical aspects of HMAC, including the formula used to generate it.

Bearer token

Bearer token (also known as Access Token) is a cryptic string that Payments Orchestrator uses to authorize your API requests.

HMACs are extremely secure but are computationally expensive and slow. For that reason, HMAC is only used initially to generate and send a secure Bearer token as a response to the hmac endpoint call. Once you have received the Bearer token, you will have to use for API authentication for every subsequent calls that you make to Payments Orchestrator APIs.

A Bearer token has an expiration time. Once generated, it will last for approximately an hour. After it has expired, you will have to regenerate the token using HMAC, your Account ID and your Tenant ID.

Webhooks

Webhooks, also known as Web Callbacks or an HTTP push API, is a way for an application to provide other applications with near real-time information.

Payments Orchestrator uses Webhooks to provide you with near real-time notifications to your internal systems, such as when a payment is updated and settled, a mandate is registered, or a chargeback occurs.

Authorization Source

Your Financial Instruments have an Authorization Source (authorizationSource) attribute. For Collections, the Authorization Source value will default to WEB for the B2C customer type. The value will default to PAPER for the B2B customer type.For Payouts, the Authorization Source value will default to PAPER.

The Authorization Source attribute will identify the flow for how payments should be initiated, for example:

Your customer is presented with a Whitelabel services Checkout component to input their payment details on your website. In this scenario, when creating the Whitelabel session, the Authorization Source should be WEB so that Strong Customer Authorization (SCA) can be triggered and presented to the customer if an SCA challenge is required.
Your customer has mailed in their payment details. Your employee enters the customer payment details manually using the Whitelabel session. The Authorization Source should be PAPER to ensure that the proper payment procedures are being followed.
Your customer calls your call center employee to update their payment details. The call center employee updates the customer payment details manually using the Whitelabel session. The Authorization Source should be TEL to ensure that the proper payment procedures are being followed.

It should be noted that calls should not be recorded when recieving card details as per Payment Card Industry Data Security Standard (PCI DSS). When card details have been submitted via a paper form, the card details should be appropriately redacted or masked when storing the documentation, either electronically or on a hard copy.

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