This document explains the payment capabilities of the EBPP API. The API can be used by a business that wants to accept funds from its customers. Organized around REST, the EBPP API uses standard HTTP verbs and response codes that can be understood by any HTTP client.

There are two models in EBPP, namely,

1. Single-Profile Account, where only a single customer profile can be associated with a customer account.
   

2. Multi-Profile Account model, where multiple customer profiles can be associated with a customer account. For e.g.,

   1. Co-borrowers / Joint borrowers of a loan account who would want to make the EMI payment separately.
      
   2. Designated employees of a company who manage the Group insurance policy on behalf of their employer.
      

   This page contains the set of APIs which can be used with the Single-profile Account model.
   

Important: A Client cannot opt for both the models at the same time. Therefore, before integrating with the EBPP Payments API, please make sure that you are clear about the model you want to opt for. Please contact us if you need any assistance regarding the choice of model.

Bank Account Validation is available within EBPP as part of your bill pay setup. This function should not be used by EBPP Clients unless you need to validate bank accounts outside of your EBPP setup, and a separate license must be purchased to make use of this standalone service.

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

For e.g., the API endpoint URL for Create Customer API on the Production environment is https://api.orbipay.com/payments/v1/customers and that on the Sandbox is https://sbapi.orbipay.com/payments/v1/customers.

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

EBPP 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, EBPP 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, EBPP 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 EBPP API specific error codes are described here.

As per REST guidelines, EBPP 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 Customer Accounts, Retrieve Payments and Retrieve Funding Accounts 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.

Please refer to the individual API for more information on the request headers to be provided.

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 EBPP to the client.
Type: string Pattern: '[a-zA-Z0-9_-]{1,50}'

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

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 EBPP 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 customer, like the customer portal and IVR, the requestor_type should be set to "customer".
If an API is being requested from an application that is being used by third party agents/brokers servicing a customer on behalf of a biller/client, then the requestor_type should be set to "external_user".
Type: string ValidValues: customer , external_user

requestor : The identifier for the requestor of the API, in EBPP. The value to be passed in the requestor field would depend on the requestor_type.
If the requestor_type is "customer", the requestor should be the EBPP generated customer id. In the case of self registration, where there is no EBPP generated customer id yet, the requestor should be set to ''guest''.
If the requestor_type is "external_user", the requestor can be any unique identifier that the client may have for the external agent.
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.

Please refer to the individual API for more information on the response headers that will be returned.

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 EBPP to the client.
Type: string Pattern: '[a-zA-Z0-9_-]{1,50}'

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

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 EBPP 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 customer, like the customer portal and IVR, the requestor_type should be set to "customer".
If an API is being requested from an application that is being used by third party agents/brokers servicing a customer on behalf of a biller/client, then the requestor_type should be set to "external_user".
Type: string ValidValues: customer , external_user

requestor : The identifier for the requestor of the API, in EBPP. The value to be passed in the requestor field would depend on the requestor_type.
If the requestor_type is "customer", the requestor should be the EBPP generated customer id. In the case of self registration, where there is no EBPP generated customer id yet, the requestor should be set to ''guest''.
If the requestor_type is "external_user", the requestor can be any unique identifier that the client may have for the external agent.
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 EBPP, 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

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 customer’s full name and corresponding unique identifier from your system, on a EBPP Customer object. Custom fields are only captured and stored by EBPP and not used for processing of any sort. Please contact support@billerpayments.com for any additional requirement you may have on custom fields. Only the custom fields enabled for the client, in EBPP, would be accepted in the requests.

Below are the supported custom fields datatypes.

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 retry and not reprocessed by EBPP if all the request parameters, including the path and query parameters, the request headers and the request body, match with an earlier request. In case of duplicate requests or retries, the API response will be that of the original request.The only exceptions to this are the Retrieve API even though they may use HTTP POST. We do not consider duplicate requests for Retrieve API like Retrieve Customer, Retrieve Customer Accounts and Retrieve Funding Accounts as idempotent requests.

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

EBPP does not support retry of GET requests and these are processed every time, irrespective of the idempotent_request_key.

The EBPP API is accompanied by a host of SDKs, in various popular programming languages, to simplify the integration. These SDKs are available here, where it's categorized by the version of the API and the language of choice. Detailed instructions on how to set them up and use them are provided in the Readme docs and the SDK code docs for the SDKs. Code samples on how to use them can be accessed in the API Playground and can also be accessed by following the language icon link provided for each of the API. The sample code available in the API playground can be executed and is available in an easy-to-use format with code that can be copied. We provide SDKs in the following languages, for now. Please contact your RM if you need us to provide SDK in any language not listed here.

Customers holds Customer Accounts. A Payment is always made against a Customer Account by/on behalf of a Customer using an associated Funding Account. Each of these resources is labeled with its own id in EBPP.

Customer : The individual or entity associated with a Customer Account.

Customer Account : The billing account against which a customer makes payments.

Funding Account : The credit, debit, or bank account being used to make a payment.

Payment Authorization : The process which enables the clients to hold a certain amount on the customers' Funding Account as a first step in order to debit the customer with the actual amount at a later point of time as a second step.

Payment : The process through which funds from an associated Funding Account are applied towards a balance due on a Customer's billing account.

Payment Setup : The process through which funds from an associated Funding Account are applied towards a balance due on a Customer's billing account on a recurring basis as per a template specified by the customer.

Refund : The process which enable customers to get refunded for a payment that they made.

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

This section outlines the API required to manage Customer Accounts.