Electronic Bill Presentment and Payments API - Single Profile Account (1.15.0)

The Electronic Bill Presentment and Payments (EBPP) API enables businesses to accept bank account, credit and debit card payment

Introduction

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.

Environments

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.

Environment Hostname
Sandbox https://sbapi.orbipay.com/payments/v1
Production https://api.orbipay.com/payments/v1

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.

Authentication

Here are the Authorization methods that are supported.

OPAY1-HMAC-SHA256

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.

Item Description
OPAY1-HMAC-SHA256 The algorithm that is used to calculate the signature.
Credential The api_key that is assigned by EBPP to the client.
Signature The Base 64 encoded value of the signature bytes. Calculating the signature bytes is explained below.

Signature Calculation

Signature is calculated as follows.

Base64(HMAC-SHA256(secret,input))

The calculation is explained in detail below.

Item Description
Base64() The encoding of the signature bytes.
HMAC-SHA256() The cryptographic function that computes the HMAC by using the SHA256 algorithm with the client secret provided.
secret The secret key specific to the client that is shared with the client during onboarding.
input The string value of the canonicalized transform of request data that includes the HTTP method, URL, headers, query parameters and body. The details of computing the input is explained below.

The string input is computed as follows.

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

Each of the substrings is explained below.

Item Description
method() The HTTP method for the given request and evaluates to one of GET, PUT, POST or DELETE.
path() The absolute path component of the URI—everything starting with the "/" that follows the domain name and up to the end of the string or to the question mark character ("?") if the given URL has query string parameters.
queryString() A string in the format param1=value1&param2=value2&…, where the query parameters are sorted in alphabetical order of the parameter names. In case multiple values are present for a parameter, the query parameters are sorted in alphabetical order of the parameter names and subsequently by the parameter values for each such paramter. Both the parameter names and their values should be trimmed for leading and trailing whitespaces, should be in their normal pre-encoded format. Only parameters with non-empty values, after trimming the leading and trailing whitespaces, should be included. If there are no query parameters at all, the queryString() should evaluate to an empty string (“”).
headers() A string in the format header1=value1&header2=value2&.......&headerN=valueN. The headers are to be sorted alphabetically. Both the header names and their values must be trimmed for leading and trailing white-space, and in their normal pre-encoded format . Only the headers listed by the application and those that are non-empty, after trimming the leading and trailing whitespaces, are to be included.
payload() The raw HTTP body

Tryout

HTTP Response Codes

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

Code Reason
200 - OK Successfully processed the request
201 - Created The object was successfully created
204 - No Content No Content, Successfully processed the request
400 - Bad Request The request was rejected, most likely due to invalid parameters
401, 403 - Unauthorized, Forbidden Unauthorized or forbidden request
404 - Not Found The resource does not exist
409 - Conflict This typically occurs when duplicate requests are received even while the original request is being processed.
422 - Unprocessable Entity The request body contains well-formed (i.e., syntactically correct), but semantically erroneous, instructions.
500 - Internal Server Error Something went wrong with EBPP and the request could not be processed.

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

code message
error_field The error returned if a mandatory field is missing value or if the value is invalid. This is accompanied by the field that caused the error.
error_customer_missing The request cannot be processed due to invalid customer details.
error_dda_invalid The request cannot be processed due to invalid bank details.
error_payment_rejected The payment is rejected due to business rules violation.
error_payment_disallowed The payment is disallowed due to business rules violation.
error_duplicate_payment The payment is rejected as it duplicates an existing one.
error_payment_update_disallowed The payment cannot be modified due to business rules violation.
error_funding_account_missing The request cannot be processed due to invalid funding account.
error_duplicate_customer The request cannot be processed since one or more customers with the same details exist already.
error_card_expiry The payment is rejected as the card expires before the payment date.
error_card_auth The card could not be authorized.
error_customer_account_missing The request can not be processed with the given account information.
error_customer_account_invalid The request can not be processed with the given account information.
error_duplicate_customer_account The request cannot be processed since one or more customer accounts with the same details exist already.
error_card_invalid Invalid card.
error_insufficient_balance The funding account does not have sufficient balance.
error_card_declined The card has been declined.
error_funding_account_limit_reached The funding account cannot be added since it has reached the maximum limit of funding accounts per customer.
error_tech_difficulties There is a problem processing this request due to technical difficulties.
error_card_cvv_mismatch The payment is rejected as the card CVV details mismatch with cardholders bank.
error_card_avs_mismatch The payment is rejected as the card AVS details mismatch with cardholders bank.
error_funding_account_update_disallowed The funding account cannot be modified due to business rules violation.
error_duplicate_funding_account The funding account is rejected as it duplicates an existing one.
error_unsupported_card The request cannot be processed as the card is not supported for the client.
error_fee_amount_disallowed The fee amount cannot be accepted as it's configured to be calculated by EBPP.
error_customer_account_limit_reached The request cannot be processed since it has reached the maximum limit of customer accounts per customer. This generally occurs when a new customer account is trying to be added for an existing customer or multiple customer accounts are trying to be added for a new customer and multiple customer accounts are not supported for the client.
error_customer_forbidden The request cannot be processed as the customer may be suspended or revoked. In such cases the customer is forbidden from performing actions like making payments and adding funding accounts.
error_funding_account_unusable The request cannot be processed as the funding account is unusable. Funding accounts that are in statuses like inactive, suspended and deleted cannot be used for making payments.
error_funding_account_blocked The request cannot be processed as the funding account is blocked.
error_funding_account_disallowed The request cannot be processed as the funding account status does not allow it. Funding accounts that are in statuses like inactive, suspended and frozen cannot be updated. New funding accounts cannot be created if another one with the same details is in one of the above statuses.
error_funding_account_address_disallowed The request cannot be processed as the funding account with the given address is not allowed. This generally occurs when funding accounts with overseas addresses are used and the client has not opted for the same.
error_payment_not_schedulable The payment cannot be scheduled for the date provided since it might be a holiday or past cut-off time.
error_payment_setup_disallowed The payment setup is disallowed due to business rules violation.
error_refund_disallowed The refund is disallowed due to business rules violation.
error_payment_setup_limit_amount_disallowed The maximum payment limit amount cannot be accepted for the payment setup as it is not configured by the client with EBPP.
error_customer_account_update_disallowed The customer account cannot be modified due to business rules violation.
error_customer_account_disallowed The customer account cannot be added or updated to requested customer as it is associated with another customer.
error_funding_account_invalid The request can not be processed with the given funding account information.
error_dda_verification_failed dda verification failed.
error_dda_verification_limit_reached The dda account cannot be added since it has reached the maximum verification limit for the channel.
error_dda_verification_channel_limit_reached The dda account cannot be added since it has reached the maximum verification limit allowed from all channels.
error_refine_search Please refine the search criteria.

Hypermedia

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.

Pagination

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

Request Headers

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

Authorization: The authentication information as per the documentation in Authentication section. This is a standard HTTP header.
Type: string

Response Headers

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

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.

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

Duplicate Requests and Retries

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.

SDKs

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.

Resources

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.

Customer

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

Create Customer

The Create Customer API is used to register a customer with a biller in EBPP. It is also mandatory to create a customer account for the customer. So, at least one customer account should be provided in order to register a customer. There is no limit on the number of accounts that can be associated with the customer. Either first_name or last_name is required to create a customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

requestor
required
string [a-zA-Z0-9]{1,20}

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 “guest”. This is typically used in the case of self registration, where there is no EBPP generated customer id yet.

If the requestor_type is "external_user", the requestor can be any unique identifier that the client may have for the external agent.

Request Body Schema: application/json

The JSON that contains all the attributes of customer to be created.

customer_accounts
required
Array of objects non-empty
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

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

The unique identifier in the client system for the customer.

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

The first name of the customer.

Constraints: CBP101
last_name
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]{1,60}

The last name of the customer.

Constraints: CBP101
middle_name
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]{1,60}

The middle name of the customer.

gender
string
Enum: "male" "female"

The gender of the customer.

date_of_birth
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date of birth of the customer. It should be in the full-date format as per ISO8601, namely, YYYY-MM-DD.

ssn
string [0-9]{9}

The SSN of the customer if the account holder is an individual or the tax ID, if the customer is a business.

locale
string ^[a-z]{2}_[A-Z]{2}$

The language in which the customer wants the alerts and notifications from EBPP. This is to be specified in the format,
< ISO-639-1 language code >_< ISO ALPHA-2 Country Code >.
For e.g., en_US indicates the language preference as US English, which is also the default value.

email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address of the customer to which notifications from EBPP will be sent.

Constraints: CBP102
registered_email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address of the customer registered with the client. This may be used to uniquely identify the customer if the client is set up accordingly in EBPP.

home_phone
string [0-9]{10}

The home phone number of the customer.

work_phone
string [0-9]{10}

The work phone number of the customer.

mobile_phone
string [0-9]{10}

The mobile phone number of the customer.

address
object
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP105

Responses

201

The customer created, with the id for the same in EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers
https://api.orbipay.com/payments/v1/customers

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Update Customer

The Update Customer API is used to edit the customer''s personal details, accounts or the customer''s status. Only the information being updated needs to be sent in the request, along with the id of the customer being updated. A customer can also be associated with new customer accounts using the API.

Along with Customer details , Customer and Customer Account statuses also can be updated using the Update Customer API. Below are the possible customer state transformations.

from_status to_status allowed requestor_type
active suspended
  • external_user
active revoked
  • external_user
suspended active
  • external_user
suspended revoked
  • external_user
revoked active
  • external_user

Below are the possible customer account state transformation.

from_status to_status allowed requestor_type
active inactive
  • external_user
inactive active
  • external_user
active incollections
  • external_user
incollections active
  • external_user
inactive incollections
  • external_user
incollections inactive
  • external_user
active inbankruptcy
  • external_user
incollections inbankruptcy
  • external_user
inbankruptcy active
  • external_user
inbankruptcy inactive
  • external_user
path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the attributes of the customer to be updated.

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

The first name of the customer.

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

The last name of the customer.

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

The middle name of the customer.

gender
string
Enum: "male" "female"

The gender of the customer.

date_of_birth
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date of birth of the customer. It should be in the full-date format as per ISO8601, namely, YYYY-MM-DD.

ssn
string [0-9]{9}

The SSN of the customer if the account holder is an individual or the tax ID, if the customer is a business.

locale
string ^[a-z]{2}_[A-Z]{2}$

The language in which the customer wants the alerts and notifications from EBPP. This is to be specified in the format,
< ISO-639-1 language code >_< ISO ALPHA-2 Country Code >.
For e.g., en_US indicates the language preference as US English, which is also the default value.

email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address of the customer to which notifications from EBPP will be sent.

Constraints: CBP102
registered_email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address of the customer registered with the client. This may be used to uniquely identify the customer if the client is set up accordingly in EBPP.

home_phone
string [0-9]{10}

The home phone number of the customer.

work_phone
string [0-9]{10}

The work phone number of the customer.

mobile_phone
string [0-9]{10}

The mobile phone number of the customer.

address
object
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP105
status
string
Enum: "active" "revoked" "suspended"

The status of the customer in EBPP.

customer_accounts
Array of objects
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP107

Responses

200

The customer along with the list of customer accounts updated for the customer.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

put/customers/{ID_CUSTOMER}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Customer

The Get Customer API is used to retrieve the details of the customer based on the id.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The customer along with the list of customer accounts available to the customer

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Customer

This API is used to retrieve/lookup customers from EBPP. Customers can be retrieved matching criteria that includes the customer_reference, the ssn, the email or the customer account number. A unique customer can be retrieved by using search criteria as per the customer uniqueness parameters opted by the client/biller. If the requestor_type is customer, the Retrieve Customer API will return an error if it cannot retrieve a unique customer.

query Parameters
page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

requestor
required
string [a-zA-Z0-9]{1,20}

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

Content-Type
required
string

The content type of the API. It will be 'application/x-www-form-urlencoded' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/x-www-form-urlencoded
customer_reference
string ^$|[0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\s\\"]{1,100}

Unique ID assigned by the biller/client system for a given customer.

ssn
string [0-9]{9}

The SSN of the customer if the account holder is an individual or the tax ID, if the customer is a business.

email
string [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

This field contains the customer’s email address within EBPP.

account_number
string [a-zA-Z0-9-_/!@#$%&*{}. ']{1,100}

Customer Account Number of the customer to get details of.

Responses

200

The list of customers matching the criteria provided, the total results count and the urls to get the next/previous pages.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/lists
https://api.orbipay.com/payments/v1/customers/lists

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Initiate Contact Verification

This API generates a verification code for the specified phone number of a given customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to Initiate Contact Verification.

customer
required
object
contact
required
object

Responses

204

Returns 204 http status code with empty body.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/contacts/verification
https://api.orbipay.com/payments/v1/contacts/verification

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Link Customer Contact

This API is used to link a customer's contact information to their existing account. The API takes a request body containing the customer's unique identifier and the contact information to be linked. It should be noted that for a specific contact type, such as email or sms, only one contact can be linked per customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to link a contact to customer.

customer
required
object
contact
required
object

Responses

201

contact is linked for the given customer.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/contacts/link
https://api.orbipay.com/payments/v1/contacts/link

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Unlink Customer Contact

This API is used to unlink a customer's contact information from their account. The API takes a request body containing the customer's unique identifier and the contact information to be unlinked.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to unlink a contact from the customer.

customer
required
object
contact
required
object

Responses

204

Returns 204 http status code with empty body.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/contacts/unlink
https://api.orbipay.com/payments/v1/contacts/unlink

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Customer Account

This section outlines the API required to manage Customer Accounts.

Retrieve Customer Accounts

The API is used to retrieve all the customer accounts associated with a customer. The customer accounts can be filtered using the account number, status. The API responds with the first page of the list of customerAccounts matching the criteria. The results are sorted in descending order of the last_modified_time.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

query Parameters
page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/x-www-form-urlencoded' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/x-www-form-urlencoded
account_number
string [a-zA-Z0-9-_/!@#$%&*{}. ']{1,100}

The Account Number to get details of.

status
Array of strings
Items Enum: "active" "inactive" "incollections" "inbankruptcy"

The status of the customer account in EBPP. This can take multiple values in the format key=value1&key=value2....

Responses

200

List of customer accounts matching the criteria provided, the total results count and the urls to get the next/previous pages.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/customeraccounts/lists
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/customeraccounts/lists

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Customer Accounts Pagination

This API is used to paginate through the list of customer Accounts returned in the Retrieve Customer Accounts API.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

query Parameters
page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

query_id
required
string [a-z0-9]{1,50}

query id of the Retrieve/Search Accounts lookup.

from_index
string [0-9]{1,4}

To fetch the next set of objects that start after this object

to_index
string [0-9]{1,4}

To fetch the previous set of objects that end at this object

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

All the applicable accounts are returned in the response. The fields applicable vary with the type of account.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/customeraccounts/lists
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/customeraccounts/lists

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Customer Account

The Get Customer Account API is used to retrieve the details of a customer account based on the id.

path Parameters
ID_CUSTOMER_ACCOUNT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the Customer Account.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The customer account.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Renew Customer Account

This API is used to renew a customer account. The API migrates all the pending payments and active payment setups from the original customer account to the new one.

path Parameters
ID_CUSTOMER_ACCOUNT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the Customer Account.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Value: "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the attributes of the Customer account to be renewed.

account_holder_name
required
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]{1,60}

The name as specified on the customer account.

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

The nickname by which a customer might want to identify the customer account.

address
object
customer_account_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the customer account.

account_number
required
string [a-zA-Z0-9-_/!@#$%&*{}. ']{1,100}

The number or reference that a customer uses to identify the customer account.

current_balance
string (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)

The current balance on the customer account with the biller.

current_statement_balance
string (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)

The balance on the customer account with the biller as reported on the last statement.

minimum_payment_due
string (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)

The minimum payment amount, as specified by the biller, that needs to be made against the customer account.

past_amount_due
string (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)

The amount that is due from the past bills/statements on the customer account with the biller.

payment_due_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date by which the customer needs to clear the dues against the customer account with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

statement_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the biller generates the statement for the customer account. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

payoff_amount
string (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)

This field contains the computed current loan payoff amount at the time of inquiry for the customer account with the biller.

Constraints: CBP110
payoff_expiry_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date till the payoff_amount is valid for the customer account with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP111
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP108
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP109

Responses

201

The customer account.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}/renew
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}/renew

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Funding Account

This section outlines the API required to enable customers to manage their funding accounts.

Add Funding Account

This API is used to add a funding account for the customer. The funding account is available for servicing all the customer accounts the customer holds. An exhaustive set of account types are supported as funding accounts as indicated in the field account_subtype. ABA routing number and account sub-type are mandatory for bank accounts. Expiry date, address fields and Card CVV are required for card accounts.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the attributes of the Funding account to be added to customer.

account_holder_name
required
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]{1,60}

The name as specified on the funding account.

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

The nickname by which a customer might want to identify the funding account.

address
object
account_number
required
string [a-zA-Z0-9]{4,32}

The number or reference that a customer uses to identify the funding account.

aba_routing_number
string [0-9]{9}

The ABA/Routing number for the bank account.

Constraints: CBP201
expiry_date
string [0-9]{2}/[0-9]{2}

The expiry date for the card. This is to be in the format MM/YY.

Constraints: CBP203
account_holder_type
string
Enum: "personal" "business"

The type of ownership for the funding account.

Constraints: CBP209
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP210
account_subtype
string
Enum: "savings" "checking" "money_market" "visa_credit" "mastercard_credit" "american_express_credit" "discover_credit" "visa_debit" "mastercard_debit" "discover_debit" "voyager_fleet"

The sub type of the funding account.

Constraints: CBP202
card_cvv_number
string [0-9]{3,4}
Constraints: CBP208
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP211

Responses

201

The funding account created, with the id for the same in EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/fundingaccounts
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Update Funding Account

The API is used to edit the funding account details. The type of the funding account cannot be changed. In other words, a card account cannot be changed to a bank account and vice versa. The sub-type of a bank account can be changed. For e.g., a saving account can be updated to a money market account. However, the sub-type cannot be updated for a card account. CVV is mandatory to make any change to a card account. The Id of the funding account gets updated to a new value if the account number is updated. Editing a funding account updates the account information on all pending payments made using that account but does not change the details on payments that have been completed.

Below are the possible funding account state transformation.

from_status to_status allowed requestor_type
active deleted
  • external_user
  • customer
active frozen
  • external_user
active inactive
  • external_user
frozen active
  • external_user
inactive active
  • external_user
path Parameters
ID_FUNDING_ACCOUNT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the Funding Account.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the attributes of the Funding account to be updated.

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

The name as specified on the funding account.

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

The nickname by which a customer might want to identify the funding account.

address
object
account_number
string [a-zA-Z0-9]{4,32}

The number or reference that a customer uses to identify the funding account.

aba_routing_number
string [0-9]{9}

The ABA/Routing number for the bank account.

Constraints: CBP201
expiry_date
string [0-9]{2}/[0-9]{2}

The expiry date for the card. This is to be in the format MM/YY.

Constraints: CBP203
account_holder_type
string
Enum: "personal" "business"

The type of ownership for the funding account.

Constraints: CBP209
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP210
account_subtype
string
Enum: "savings" "checking" "money_market" "visa_credit" "mastercard_credit" "american_express_credit" "discover_credit" "visa_debit" "mastercard_debit" "discover_debit" "voyager_fleet"

The sub type of the funding account. This is derived by EBPP in the case of card funding accounts.

Constraints: CBP202
status
string
Enum: "active" "frozen" "unverified" "inactive"

The status of the funding account in EBPP.

card_cvv_number
string [0-9]{3,4}
Constraints: CBP208
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP211

Responses

200

The updated funding account.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

put/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Funding Account

The Get Funding Account API is used to retrieve the details of the funding account based on the id.

path Parameters
ID_FUNDING_ACCOUNT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the Funding Account.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The funding account with the id provided.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Delete Funding Account

The Delete Funding Account API is used to delete the funding account of a customer. All pending payments made with that account are cancelled upon deletion of the funding account.

path Parameters
ID_FUNDING_ACCOUNT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the Funding Account.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

Details of account to be deleted.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP211

Responses

200

The id of the funding account being deleted and the status of the deletion.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

delete/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Funding Accounts

This API is used to retrieve all the funding accounts associated with a customer. Accounts can be filtered using the account number, the ABA routing number (for bank accounts), the funding account status, account type, account sub-type and others mentioned below. The results are sorted based on their last_modified_time in descending order. The API responds with the first page of the list of funding accounts matching the criteria.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

query Parameters
page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/x-www-form-urlencoded' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/x-www-form-urlencoded
account_number
string [a-zA-Z0-9]{4,32}

The Account Number to get details of.

status
Array of strings
Items Enum: "active" "frozen" "unverified" "unusable" "inactive"

The status of the funding account in EBPP. This can take multiple values in the format key=value1&key=value2....

aba_routing_number
string [0-9]{9}

The ABA/Routing number for the bank account.

account_type
Array of strings
Items Enum: "bank" "debit_card" "credit_card" "closed_loop"

The type of the funding account. This can take multiple values in the format key=value1&key=value2....

account_subtype
string
Enum: "savings" "checking" "money_market" "visa_credit" "mastercard_credit" "american_express_credit" "discover_credit" "visa_debit" "mastercard_debit" "discover_debit" "voyager_fleet"

The sub type of the funding account. This is derived by EBPP in the case of card funding accounts.

Constraints: CBP202

Responses

200

The list of funding accounts matching the criteria provided, the total results count and the urls to get the next/previous pages.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/fundingaccounts/lists
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts/lists

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Funding Accounts Pagination

This API is used to paginate through the list of funding accounts returned in the Retrieve Funding Accounts API.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

query Parameters
page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

query_id
required
string [a-z0-9]{1,50}

query id of the Retrieve/Search Accounts lookup.

from_index
string [0-9]{1,4}

To fetch the next set of objects that start after this object

to_index
string [0-9]{1,4}

To fetch the previous set of objects that end at this object

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

All the applicable accounts are returned in the response. The fields applicable vary with the type of account.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/fundingaccounts/lists
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts/lists

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Replace Funding Account

The API is used to replace the funding account details. The type of the funding account cannot be replaced. In other words, a card account cannot be replaced to a bank account and vice versa. CVV is mandatory to make any change to a card account.Replacing a funding account updates the account information on all pending payments made using that account but does not change the details on payments that have been completed.

path Parameters
ID_FUNDING_ACCOUNT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the Funding Account.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the attributes of the Funding account to be replaced.

account_holder_name
required
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]{1,60}

The name as specified on the funding account.

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

The nickname by which a customer might want to identify the funding account.

address
object
account_number
required
string [a-zA-Z0-9]{4,32}

The number or reference that a customer uses to identify the funding account.

aba_routing_number
string [0-9]{9}

The ABA/Routing number for the bank account.

Constraints: CBP201
expiry_date
string [0-9]{2}/[0-9]{2}

The expiry date for the card. This is to be in the format MM/YY.

Constraints: CBP203
account_holder_type
string
Enum: "personal" "business"

The type of ownership for the funding account.

Constraints: CBP209
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP210
account_subtype
string
Enum: "savings" "checking" "money_market" "visa_credit" "mastercard_credit" "american_express_credit" "discover_credit" "visa_debit" "mastercard_debit" "discover_debit" "voyager_fleet"

The sub type of the funding account. This is derived by EBPP in the case of card funding accounts.

Constraints: CBP202
card_cvv_number
string [0-9]{3,4}

This is never returned by EBPP.

Constraints: CBP208
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP211

Responses

201

The replaced funding account.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}/replacement
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}/replacement

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Payment Authorization

This section outlines the API required to enable customers to manage their payment authorizations.

Create Payment Authorization

The API is used to create a payment authorization with certain amount on a given card account. Client systems can provide the unique identifier for the payment authorization in their system as payment_auth_reference. As of now this API is supported only for voyager fleet card payments

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to make a payment.

payment_auth_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the payment authorization. This is mandatory in case of voyager fleet card payment.

Constraints: CBP303
auth_amount
required
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being authorized.

Constraints: CBP301
card_cvv_number
string [0-9]{3,4}
Constraints: CBP302
customer
required
object
funding_account
required
object
customer_account
required
object
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP309
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP308

Responses

201

The Payment Authorization object with id issued by EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/payments/auth
https://api.orbipay.com/payments/v1/payments/auth

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Cancel Payment Authorization

The API is used to cancel a payment authorization. Payment Authorizations that are already been processed into Payment cannot be cancelled. It returns 204 http status code with empty body in successful case.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

ID_AUTHORIZATION
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment authorization.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

Details of payment authorization to be cancelled

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP309

Responses

204

Returns 204 http status code with empty body.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/payments/auth/{ID_AUTHORIZATION}/cancel
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/payments/auth/{ID_AUTHORIZATION}/cancel

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Payment

This section outlines the API required to enable customers to manage their payments.

Create Payment

The API is used to make payments to service a customer account. Client systems can provide the unique identifier for the payment in their system as payment_reference.

Fee amount and fee type are conditional and should be provided if the details of the fee to be charged are maintained in the client system. The fee types that are supported in EBPP are add_to_principal and bill_separately. Alternatively, the fee information can be setup in EBPP, in which case, these fields are ignored. If fee information is setup in the system, the details of the fee are returned in the response.

Create Payment can be invoked following a payment authorization also. In that case, the appropriate payment authorization id should be provided in the API request.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to make a payment.

payment_amount_type
required
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance" "discounted_amount" "penalty_amount" "other" "payoff_amount" "paydown_amount"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.

Constraints: CBP334
amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid.

card_cvv_number
string [0-9]{3,4}
Constraints: CBP302
payment_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP330
payment_request_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP310
fee
object
Constraints: CBP305
customer
required
object
funding_account
required
object
customer_account
required
object
payment_authorization
object
payment_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the payment. This is mandatory in case of voyager fleet card payment.

Constraints: CBP303
payment_notification_email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address to which notifications for the payment will be sent.

Constraints: CBP304
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP309
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP308

Responses

201

The Payment object with confirmation number and id issued by EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/payments
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/payments

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Update Payment

The API is used to edit a payment. Only payments in scheduled status can be edited.

path Parameters
ID_PAYMENT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

Details of the Payment to be updated.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP309
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP308
fee
object
Constraints: CBP305
payment_amount_type
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance" "discounted_amount" "penalty_amount" "other" "payoff_amount" "paydown_amount"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.

Constraints: CBP334
amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid.

Constraints: CBP301
card_cvv_number
string [0-9]{3,4}
Constraints: CBP302
payment_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP330
payment_request_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP310
funding_account
object

Responses

200

The Payment with the id provided, duly updated.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

put/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Payment

The API is used to retrieve the details of a payment or a recorded payment by id.

path Parameters
ID_PAYMENT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The Payment with the id provided.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Delete Payment

The API is used to delete or cancel a payment. Payments that are under processing or have already been processed cannot be deleted.

path Parameters
ID_PAYMENT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

Details of payment to be deleted/cancelled

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP309

Responses

200

The id of the payment being deleted and the status of the deletion.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

delete/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Payments

The API is used to retrieve the payments and recorded payments made by a customer. Payments can be filtered using the confirmation number, customer account, funding account, status and payment schedule type, payment method, by date range and others mentioned below. If no dates are provided for retrieval, payments in the last six months and all the payments scheduled for a future date are returned. In case a payment has failed due to ACH returns, then the payment return date and the return code will be available in the response. The results are sorted in descending order of the payment_date followed by the last_modified_time.

query Parameters
id_customer
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

id_funding_account
string [0-9]{1,20}

The unique identifier assigned by EBPP to the funding account

id_customer_account
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer account

confirmation_number
string [a-zA-Z0-9]{1,30}

The confirmation number or reference provided to the customer for the successful payment.

status
Array of strings
Items Enum: "scheduled" "cancelled" "processing" "processed" "returned" "declined" "disputed" "error"

The status of the payment. This can take multiple values in the format key=value1&key=value2....

payment_schedule_type
Array of strings
Items Enum: "one_time_payment" "autopay_generated_payment" "variable_recurring_generated_payment" "payment_plan_generated"

The schedule type for the payment setup. This can take multiple values in the format key=value1&key=value2....

payment_method
Array of strings
Items Enum: "ach" "check" "visa_debit" "pinless_debit" "master_debit" "amex_credit" "discover_credit" "visa_credit" "master_credit" "discover_debit" "cash" "swiped_card" "scanned_check" "apple_pay" "google_pay" "voyager_fleet" "external_pos" "rtp_rfp"

The fulfillment method for the payment.

from_date
string

The date from which payments, matching the criteria specified, need to be retrieved.

to_date
string

The date upto which payments, matching the criteria specified, need to be retrieved.

page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

query_id
string [a-z0-9]{1,50}

query id of the Retrieve/Search Customers lookup.

from_index
string [0-9]{1,4}

To fetch the next set of objects that start after this object

to_index
string [0-9]{1,4}

To fetch the previous set of objects that end at this object

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

List of payments matching the criteria provided, the total results count and the urls to get the next/previous pages.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/payments
https://api.orbipay.com/payments/v1/payments

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Simple Payment

The API is used to make payments to service a customer account. Client systems can provide the unique identifier for the payment in their system as payment_reference.

Fee amount and fee type are conditional and should be provided if the details of the fee to be charged are maintained in the client system. The fee types that are supported in EBPP are add_to_principal and bill_separately. Alternatively, the fee information can be setup in EBPP, in which case, these fields are ignored. If fee information is setup in the system, the details of the fee are returned in the response.

This API updates the details of the customer, customer account and the funding account if those exist in EBPP or creates them otherwise.

query Parameters
save_funding_account
string
Value: "true"

query param

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

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 “guest” or the EBBP generated customer id, if available.

If the requestor_type is "external_user", the requestor can be any unique identifier that the client may have for the external agent.

X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to make a payment.

payment_amount_type
required
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance" "discounted_amount" "penalty_amount" "other" "payoff_amount" "paydown_amount"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment.

Constraints: CBP334
amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid.

Constraints: CBP301
card_cvv_number
string [0-9]{3,4}
Constraints: CBP302
payment_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP330
payment_request_date
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

Constraints: CBP310
fee
object
Constraints: CBP305
customer
required
object
funding_account
required
object
customer_account
required
object
payment_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the payment.

Constraints: CBP303
payment_notification_email
string <email> [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]{1,100}

The email address to which notifications for the payment will be sent.

Constraints: CBP304
cryptogram
string [a-zA-Z0-9\-=+\/]{28}

Online Payment Cryptogram, as defined by 3-D secure.

Constraints: CBP306
eci
string [0-9]{2}

ECI Indicator, as defined by 3-D secure. The card network may add an ECI indicator to the card data.

Constraints: CBP307
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP309
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP308

Responses

201

The Payment object with confirmation number and id issued by EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/payments
https://api.orbipay.com/payments/v1/payments

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Fee Payment

The API is used to retrieve the details of a fee payment by id.

path Parameters
ID_FEE
required
string [0-9]{1,20}

The unique identifier assigned by OrbiPay to the FeePayment.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by OrbiPay to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by OrbiPay to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The FeePayment with the id provided.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/fees/{ID_FEE}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/fees/{ID_FEE}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Record Payment

The API is used to record payments in EBPP those are made and fulfilled outside EBPP.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Value: "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to record a payment.

payment_amount_type
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance" "other" "payoff_amount" "paydown_amount"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.

Constraints: CBP334
amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid.

Constraints: CBP311
payment_date
required
string ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|1\d|2\d|3[01])$

The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.

payment_method
required
string
Enum: "cash" "swiped_card" "scanned_check"

The non fulfillment method for the payment.

token
string [0-9a-zA-Z._-]{1,64}

The token is used to uniquely identify the payment, such as the POS token.

fee
object
Constraints: CBP305
customer
required
object
funding_account
object
customer_account
required
object
payment_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the payment.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]{1,100}
Constraints: CBP313
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP312

Responses

201

The Payment object with confirmation number and id issued by EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/recordedpayments
https://api.orbipay.com/payments/v1/recordedpayments

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Delete Recorded Payment

The API is used to delete the recorded payment. It returns 204 http status code with empty body in successful case

path Parameters
ID_PAYMENT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

Details of payment to be deleted/cancelled

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP312

Responses

204

Returns 204 http status code with empty body.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

delete/recordedpayments/{ID_PAYMENT}
https://api.orbipay.com/payments/v1/recordedpayments/{ID_PAYMENT}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Payment Setup

This section outlines the API required to enable customers to set up and manage payment setups for their Customer Accounts.

Create Payment Setup

The API is used to set up recurring payments to service a customer account.

path Parameters
ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to create a recurring payment setup.

payment_setup_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the paymentSetup.

payment_setup_schedule_type
required
string
Enum: "variable_recurring_enrollment" "autopay_enrollment" "payment_plan"

The schedule type for the payment setup.

amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The amount being paid.

Constraints: CBP411
card_cvv_number
string [0-9]{3,4}
Constraints: CBP412
fee
object
Constraints: CBP408
customer
required
object
funding_account
required
object
customer_account
required
object
payment_schedule
required
object

The schedule for the payments that are created as part of a payment setup like recurring payment or autopay.

custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP409
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP410

Responses

201

The payment setup

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/paymentsetups
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/paymentsetups

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Update Payment Setup

The API is used to edit a payment Setup. Only autopay payment setup is allowed to edit.

path Parameters
ID_PAYMENT_SETUP
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment setup.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

Details of the Payment Setup to be updated.

funding_account
object
payment_schedule
object

The schedule for the payments that are created as part of a payment setup like recurring payment or autopay.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP410

Responses

200

The Payment Setup with the id provided, duly updated.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

put/customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Payment Setup

The API is used to retrieve the details of a recurring payment setup by id.

path Parameters
ID_PAYMENT_SETUP
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment setup.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The payment setup with the id provided.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Delete Payment Setup

The API is used to delete or cancel a recurring payment setup. Cancelling a payment setup will also cancel all the pending and future payments under the setup.

path Parameters
ID_PAYMENT_SETUP
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment setup.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to delete a payment. Setup.

comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP410

Responses

200

The id of the recurring payment setup being deleted and the status of the deletion.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

delete/customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Payment Setups

The API is used to retrieve the recurring and autopay payments setup made against a customer account. The setup can be filtered using the confirmation number, customer account, funding account, status and payment setup schedule type, by date range and others mentioned below. If no dates are provided for retrieval, recurring payments set up in the last six months and all the ones in future are returned. The results are sorted in descending order of the payment_start_date followed by the last_modified_time.

query Parameters
id_customer
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

id_funding_account
string [0-9]{1,20}

The unique identifier assigned by EBPP to the funding account

id_customer_account
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer account

confirmation_number
string [a-zA-Z0-9]{1,30}

The confirmation number or reference provided to the customer for the successful payment.

status
Array of strings
Items Enum: "scheduled" "cancelled" "declined" "error" "completed"

The status of the payment. This can take multiple values in the format key=value1&key=value2....

payment_setup_schedule_type
Array of strings
Items Enum: "variable_recurring_enrollment" "autopay_enrollment" "payment_plan"

The schedule type for the payment setup. This can take multiple values in the format key=value1&key=value2....

from_date
string

The date from which recurring payments setup, matching the criteria specified, need to be retrieved.

to_date
string

The date upto which recurring payments setup, matching the criteria specified, need to be retrieved.

page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

query_id
string [a-z0-9]{1,50}

query id of the Retrieve/Search Customers lookup.

from_index
string [0-9]{1,4}

To fetch the next set of objects that start after this object

to_index
string [0-9]{1,4}

To fetch the previous set of objects that end at this object

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

List of recurring payments setup matching the criteria provided, the total results count and the urls to get the next/previous pages.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/paymentsetups
https://api.orbipay.com/payments/v1/paymentsetups

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Refund

This section outlines the API required to enable customers to get refunded for the payments made via EBPP.

Create Refund

This API is used to initiate a refund. Any payment made using EBPP can be refunded. Customer cannot initiate a refund request. In other words, the Create Refund request will fail if the associated requestor_type is customer.

path Parameters
ID_PAYMENT
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the payment.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Value: "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to refund a payment.

refund_reference
string [0-9a-zA-Z._-]{1,50}

The unique identifier in the client system for the refund.

refund_amount
string ^[0-9]{1,14}(\.[0-9][0-9]?)?$

The refund amount upto 2 decimal places.

fee_refund
object
comments
string [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"\r\n]{1,1000}

Comments that can be used to recollect the operation performed on the resource object.

Constraints: CBP502
custom_fields
object

The additional information or meta-information that EBPP can accept, maintain and transmit back to the client.

Constraints: CBP501

Responses

201

The refund object with confirmation number, id, status, expected settlement date and corresponding refund reference.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}/refunds
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}/refunds

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve Refunds

The API is used to retrieve the refunds made to a customer against payments processed through EBPP. Refunds can be filtered using the customer id, confirmation number of the payment being refunded or of the refund, status of the refund and others mentioned below. Scheduled refunds that are yet to be processed and all the refunds processed in the last six months are returned if date criteria is not specified. The results are sorted in descending order of the refund_date followed by the last_modified_time.

query Parameters
id_customer
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

confirmation_number
string [a-zA-Z0-9]{1,30}

The confirmation number provided to the customer for the refund or for the corresponding successful payment.

status
Array of strings
Items Enum: "scheduled" "cancelled" "processing" "processed" "returned" "declined" "disputed" "error"

The status of the refund. This can take multiple values in the format key=value1&key=value2....

from_date
string

The date from which refunds, matching the criteria specified, need to be retrieved.

to_date
string

The date upto which refunds, matching the criteria specified, need to be retrieved.

page_size
string [0-9]{1,2}

The maximum number of objects returned in the query.

query_id
string [a-z0-9]{1,50}

query id of the Retrieve/Search Customers lookup.

from_index
string [0-9]{1,4}

To fetch the next set of objects that start after this object

to_index
string [0-9]{1,4}

To fetch the previous set of objects that end at this object

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

201

List of refunds matching the criteria provided, the total results count and the urls to get the next/previous pages.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/refunds
https://api.orbipay.com/payments/v1/refunds

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Get Refund

The API is used to retrieve the details of a refund by id.

path Parameters
ID_REFUND
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the refund.

ID_CUSTOMER
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The refund with the id provided.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/customers/{ID_CUSTOMER}/refunds/{ID_REFUND}
https://api.orbipay.com/payments/v1/customers/{ID_CUSTOMER}/refunds/{ID_REFUND}

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Payment Enrollment

This section outlines the API required to enable customers to enroll to Pay By Text(PBT) via EBPP.

Manage PBT Enrollment

This API allows the management of Pay-By-Text (PBT) enrollment for a given customer by providing details such as phone number, customer account, funding account, and enrollment status. The API supports three main functionalities, which are create new enrollment, update existing enrollment or unenroll existing enrollment

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Content-Type
required
string

The content type of the API. It will be 'application/json' for this API. This is a standard HTTP header and will not be used for generating the Signature as described in the Authentication section.

Request Body Schema: application/json

JSON containing all the fields required to manage a customer for PBT enrollment.

customer
required
object
contact
required
object
customer_account
required
object
funding_account
required
object
payment_amount_type
required
string
Enum: "current_balance" "minimum_payment_due" "past_payment_due" "statement_balance"

The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.

days_before_due
required
string [0-9]{1,2}

The number of days before the payment due date on which the payment alert is to be sent to the enrolled customer to the contact phone provided here.

enrollment_status
string
Enum: "enrolled" "unenrolled"

The status of the payment enrolment. Use “unenrolled” to cancel the existing enrolment.

Responses

201

The Payment Enrollment created or updated in EBPP.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

post/pbt
https://api.orbipay.com/payments/v1/pbt

Please click on a language icon above to try out the API

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Retrieve PBT Enrollments

The API can be utilized to retrieve the enrollment details of Pay by Text (PBT) for a specified customer based on search criteria.

query Parameters
id_customer
required
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer.

id_customer_account
string [0-9]{1,20}

The unique identifier assigned by EBPP to the customer account

header Parameters
channel
required
string

The channel through which the API is invoked.

client_key
required
string [a-zA-Z0-9_-]{1,50}

The unique identifier assigned by EBPP to the client.

product
required
string
Value: "orbipay_payments"

The product identifier corresponding to the API.

timestamp
required
string

The timestamp for the moment when the API request is created.

idempotent_request_key
required
string [a-zA-Z0-9]{1,50}

The unique token that clients can generate and maintain in order to identify an API request.

requestor_type
required
string
Enum: "customer" "external_user"

Type of the requestor of the API.

Constraints: CBP001
requestor
required
string [a-zA-Z0-9]{1,20}

The identifier for the requestor of the API.

Constraints: CBP002
X-OPAY-Headers
string

Intended for the future use.

trace_id
string [a-zA-Z0-9_=-]{1,50}

The unique reference that can be used for tracing and debugging an API call.

Authorization
required
string

The authentication information as per the documentation in Authentication section. This is a standard HTTP header.

Responses

200

The response contains all PBT enrollments that match the search criteria.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

409

Conflict

422

The parameters were valid but the request failed..

500

Something went wrong and the request could not be processed.

get/pbt/lists
https://api.orbipay.com/payments/v1/pbt/lists

Please click on a language icon above to try out the API

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}