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


Once you register with the Payments application, you will obtain a Payments Account. The Account represents your organization and lets you manage licenses and billing with Payments. 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.


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.


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

EnvironmentUsed forREST APIAccount PortalTenant Portal
SandboxIntegrating and experimenting with Paymentshttps://sandbox-api.imbursepayments.comhttps://sandbox-account.imbursepayments.com
ProductionReal-time commercial operationshttps://api.imbursepayments.comhttps://account.imbursepayments.com


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 application connects to your payment methods using Apps.


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 refer to applications that Payments uses to connect to PSPs and their services. Apps are easy to install and configure. Once you have configured them, Payments can connect and push your payment requests through them.

App Type

In the Payments 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 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 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: Collect for collection and Payout for payment. Each of these types lets you set up at least one instance of Rules and Apps.


Payments 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 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 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.


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


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


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 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

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

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.

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 Payments White Label Integration and incorporate the Checkout Component, the Financial Instrument for Card Payments is automatically generated.

Orders and Instructions

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


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

Transaction Type

The Payments 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.


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


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


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. |


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' 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.


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


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 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 is a mandatory security measure enforced by Payments to prevent uuauthorized entities from making calls to the Payments API.

Payments 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 refers to the set of Public and Private Keys that Payments APIs use to authorize the API requests you make. You will find two API Keys when you work with the Payments application.

Account API Key

Account API Key is used to manage your account, its tenants, including Tenant API Keys through Payments 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.

FunctionRole Key for read-only accessRole Key for read-write access
All aspects of Tenant, including Users and Tenant API Keystenant-admin
Tenant informationtenant-management
Collect Schemestenant-collect-scheme-readtenant-collect-scheme-write
Payout Schemestenant-payout-scheme-readtenant-payout-scheme-write
Reward Groupstenant-reward-group-readtenant-reward-group-write

Hash-based Message Authorization Code (HMAC)

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

Before you make the call to Payments APIs, you will have to create a unique HMAC using your Tenant API Keys (Public and Private). This HMAC is then shared with Payments as a part of the API request. Upon receving your HMAC, Payments 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 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 APIs.


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 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.

Copyright 2024 Duck Creek Technologies. All Rights Reserved.