Digital Disbursements is a highly flexible and configurable online disbursement platform designed for businesses to efficiently distribute funds to beneficiaries. This document outlines the capabilities of the Digital Disbursements API, which is built around REST principles.

The API utilises standard HTTP methods and response codes, ensuring compatibility with any HTTP client. It provides a straightforward and reliable means for managing disbursements through clear and consistent interfaces.

The following environments are available to clients who would like to integrate with the Disbursements API. Please use the appropriate hostname, based on the environment being accessed, while invoking an API.

For e.g., the API endpoint URL for Save Payee API on the Production environment is https://api.orbipay.com/disbursements/v1/payees and that on the Sandbox is https://sbapi.orbipay.com/disbursements/v1/payees.

Here are the Authorization methods that are supported.

The HTTP Authorization request header is used to provide authentication information. This header looks like the following.

Authorization : OPAY1-HMAC-SHA256 Credential=...,Signature=...

The constituents of the authorization header are explained in the table below.

Signature Calculation

Signature is calculated as follows.

Base64(HMAC-SHA256(secret,input))

The calculation is explained in detail below.

The string input is computed as follows.

input = method():path():queryString():headers():payload()

Each of the substrings is explained below.

Tryout

Digital Disbursements uses standard HTTP response codes to return the status of an API call. Additional information, such as errors, may be useful to a caller. An HTTP response code of 2xx indicates success. In this case, additional information pertaining to the request is sent back in the header parameters. An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Digital Disbursements also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable.)

Http Response Codes

An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Digital Disbursements also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable). The Digital Disbursements API specific error codes are described here.

As per REST guidelines, Digital Disbursements API supports hypermedia. This allows for simple and intuitive navigation between the resources, making it easy to fetch associated metadata for any given resource.

The various Retrieve methods listed below, like Retrieve Payees, Retrieve Disbursements and Retrieve Payout Methods return a list of results matching the specified filter criteria. However, all the items in the list are not returned at once, but instead are returned in groups called pages. The size of the page can be set by the caller using the request parameter called page_size. The default page size is 10.

Each page of results consists of a list of items, the url to fetch any page in the list along with the from index and the to index of the results on that page. If both from_index and to_index are provided, only from_index is considered.To fetch any page in the list, the appropriate query string has to be appended to the url. This can be done as follows.

<url>&from_index=<new from index>&page_size=<page size> ( or ) <url>&to_index=<new to index>&page_size=<page size>

For e.g., the second page of a list with a page size of 10 would return with from_index 11 and to_index 20. To retrieve the third page, the from_index to be used in the request would be 21 and for the first page would be 1. The third page could be retrieved using any of the following urls.

<url>&from_index=21&page_size=10 ( or ) <url>&to_index=30&page_size=10

Every API call includes request headers. These HTTP header parameters are required to define the context in which the API is invoked.

channel : The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
Type: string

client_key : The unique identifier assigned by Disbursment to the client.
Type: string Pattern: '[a-zA-Z0-9_-]{1,50}'

product : The product identifier corresponding to the API.
Type: string ValidValues: orbipay_disbursements

timestamp : The timestamp for the moment when the API request is created, in the format, yyyy-MM-dd HH:mm:ss.SSSZ
For e.g., 2018-07-13 11:41:17.422+00:00 Please ensure that consecutive spaces are not used in the timestamp.
Type: string

idempotent_request_key : The unique token that clients can generate and maintain in order to identify an API request. This is used by Disbursment to identify duplicate requests and retries. Please refer to the "Duplicate Requests & Retries" section for more details.
Type: string Pattern: '[a-zA-Z0-9]{1,50}'

requestor_type : If an API is being requested from an application that is being used directly by a payee, like the payee portal and IVR, the requestor_type should be set to "payee".
Type: string ValidValues: external_user and payee

requestor : The identifier for the requestor of the API, in Disbursment. The value to be passed in the requestor field would depend on the requestor_type.
Type: string Pattern: '[a-zA-Z0-9]{1,20}'

X-OPAY-Headers : Intended for the future use.
Type: string

trace_id : The unique reference that can be used for tracing and debugging an API call.
Type: string Pattern: '[a-zA-Z0-9_=-]{1,50}'

HTTP header parameters are returned as part of every API response. Most of these parameters match those sent in the request.

channel : The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
Type: string

client_key : The unique identifier assigned by Disbursment to the client.
Type: string Pattern: '[a-zA-Z0-9_-]{1,50}'

product : The product identifier corresponding to the API.
Type: string ValidValues: orbipay_disbursements

timestamp : The timestamp for the moment when the API request is created, in the format, yyyy-MM-dd HH:mm:ss.SSSZ
For e.g., 2018-07-13 11:41:17.422+00:00 Please ensure that consecutive spaces are not used in the timestamp.
Type: string

idempotent_request_key : The unique token that clients can generate and maintain in order to identify an API request. This is used by Disbursment to identify duplicate requests and retries. Please refer to the "Duplicate Requests & Retries" section for more details.
Type: string Pattern: '[a-zA-Z0-9]{1,50}'

requestor_type : If an API is being requested from an application that is being used directly by a payee, like the payee portal and IVR, the requestor_type should be set to "payee".
Type: string ValidValues: external_user and payee

requestor : The identifier for the requestor of the API, in Disbursment. The value to be passed in the requestor field would depend on the requestor_type.
Type: string Pattern: '[a-zA-Z0-9]{1,20}'

X-OPAY-Headers : Intended for the future use.
Type: string

request_uuid : The unique ID for the request, generated by Disbursment, that can be used for tracing and audit trail.
Type: string Pattern: '[a-z0-9]{1,50}'

response_codes : Codes corresponding to any additional information or warning, pertaining to the API call, in a comma separated format, that are returned in the response.
Type: string

response_text : The text detailing any additional information or warning, pertaining to the API call, in a pipe separated format, that is returned in the response.
Type: string

trace_id : The unique reference that can be used for tracing and debugging an API call.
Type: string Pattern: '[a-zA-Z0-9_=-]{1,50}'

We support idempotency for the HTTP methods POST, PUT, DELETE and PATCH using the header parameter, namely, idempotent_request_key.

In other words, any POST, PUT, DELETE and PATCH request will be considered as a duplicate request or retries and not reprocessed by Digital Disbursements if all the request parameters, including the idempotent_request_key, match with an earlier request. Please note that the entire request with all the request parameters, including the idempotent_request_key, have to match with the original request for it to be treated as a duplicate request or retry. In case of duplicate requests or retries, the API response will be that of the original request.

The idempotent_request_key is valid only for a duration of one hour from the time of the original request. Any duplicate request or retry after a gap of one hour from the original request will be considered as a fresh request and reprocessed by Digital Disbursements.

Digital Disbursements does not support retrial of GET requests and these are processed every time, irrespective of the idempotent_request_key.

Custom fields are useful for storing additional structured information on an object. Please check with the specific Resource definition below to check if it supports custom fields. For example, you could store the payee’s full name and corresponding unique identifier from your system, on a Digital Disbursements Payee object. Custom fields are only captured and stored by Digital Disbursements and not used for processing of any sort. Please contact support@billerpayments.com for any additional requirement you may have on custom fields.

Below are the supported custom fields datatypes.

| data_type | pattern        |
| ------------ | ------------ |
| string | [0-9a-zA-Z #,.'&/\-@!$%*()_+={}\|:;`\[\]\^\~\\"]{0,100}|
| dollar | (\+\|\-)?([0-9]+(.[0-9]+)?)|

Payee hold Payee Accounts. A disbursement is always made against a Payee Account by/on behalf of a Payee using an associated Payout Method. Each of these resources is labeled with its own id in Digital Disbursements.

Payee The individual or entity associated with a Payee Account.

Payout Method The bank account being used to receive funds.

Disbursement The process through which disbursements will be credited.

Disbursement Setup The process through which disbursement setups will be credited.

This section outlines the API required to exchange and manage payee information, such as payee account details.

This section outlines the API required to enable payees to manage their payout methods.

This section outlines the API required to enable payees to manage their disbursements.