This section covers topics which are common to all the API mentioned below.
Introduction
Orbipay is a highly flexible and configurable online payment platform. This document explains the payment capabilities of the Orbipay platform. This API is to be used where a business wants to accept funds from its customers.
Organized around REST, Orbipay API uses standard HTTP verbs and response codes that can be understood by any HTTP client.
Authentication
Signature Calculation Example:
Http Request Before Including Authorization Header:
GET /payments/v1/payments?page_size=10&id_customer
=123456&from_date= & status = scheduled
&status=processing HTTP/1.1
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 client key ( Please refer to the Request Headers section for more details ).
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 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¶m2=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
HTTP Response Codes
Http Response Codes
Code
Reason
200 - OK
Successfully processed the request
201 - Created
The object was successfully created
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 Orbipay and the request could not be processed.
Orbipay 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, Orbipay 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.)
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 Orbipay Customer object. Custom fields are only captured and stored by Orbipay 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 Orbipay, would be accepted in the requests.
Hypermedia
As per REST guidelines, Orbipay 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 Customers, 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
Error Codes
Example:
{
"errors": [
{
"code": "error_field",
"message": "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.",
"field": "account_number"
}
]
}
An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Orbipay 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 Payments 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 Orbipay.
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 Orbipay.
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.
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 Orbipay.
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
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.
Duplicate Requests & 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 Orbipay 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 Customers, 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 Orbipay.
Orbipay does not support retry of GET requests and these are processed every time, irrespective of the idempotent_request_key.
Request Headers
Every API call includes request headers. These HTTP header parameters are required to define the context in which the API is invoked.
channelstringrequired
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
client_keystringrequired
The unique identifier assigned by Orbipay to the client.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9_-]{1,50}
productstringrequired
The product identifier corresponding to the API.
Valid Values: orbipay_payments
timestampstringrequired
The timestamp for the moment when the API call is made, 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.
idempotent_request_keystringrequired
The unique token that clients can generate and maintain in order to identify an API request. This is used by Orbipay to identify duplicate requests and retrials. Please refer to the "Duplicate Requests & Retrials" section for more details.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
requestor_typestringrequired
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstringrequired
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
X-OPAY-Headersstring
Intended for the future use.
Response Headers
HTTP header parameters are returned as part of every API response. Most of these parameters match those sent in the request.
channelstringThe channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
client_keystringThe unique identifier assigned by Orbipay to the client.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9_-]{1,50}
productstringThe product identifier corresponding to the API.
Valid Values: orbipay_payments
requestor_typestringIf 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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstringThe identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstringThe timestamp for the moment when the API call is made, 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.
idempotent_request_keystringThe unique token that clients can generate and maintain in order to identify an API request. This is used by Orbipay to identify duplicate requests and retrials. Please refer to the "Duplicate Requests & Retrials" section for more details.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
request_uuidstringThe unique ID for the request, generated by Orbipay, that can be used for tracing and audit trail.
Max. Length: 50Reg. Exp.: [a-z0-9]{0,50}
response_codesstringCodes corresponding to any additional information or warning, pertaining to the API call, in a comma separated format, that are returned in the response.
response_textstringThe text detailing any additional information or warning, pertaining to the API call, in a pipe separated format, that is returned in the response.
X-OPAY-HeadersstringIntended for the future use.
Payments API
API EndpointsProduction: https://api.orbipay.com/payments/v1Sandbox: https://sbapi.orbipay.com/payments/v1
The Payments API enables businesses to accept credit, debit, and bank account payments.
Customer
This section outlines the API required to exchange and manage customer information, such as customer account details.
The Customer Object
A Customer holds Customer Accounts. Customer Accounts are always associated with a Customer. A Customer can be an individual, or an entity - such as an organization or a business. A customer can be uniquely identified using any one of its attributes, namely, customer_reference, ssn, email or account number depending on the client's choice. If the requestor type is "customer" then one of the attributes that uniquely identifies a customer is mandatory.
The date of birth of the customer. It should be in the full-date format as per ISO8601, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
ssnstring
The SSN of the customer if the account holder is an individual or the tax ID, if the customer is a business.
Min. Length: 9Max. Length: 9Reg. Exp.: [0-9]{9}
localestring
The language in which the customer wants the alerts and notifications from Orbipay. 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.
Min. Length: 5Max. Length: 5Reg. Exp.: ^[a-z]{2}_[A-Z]{2}$
emailstring
The email address of the customer to which notifications from Orbipay will be sent. This will default to the registered_email while creating a customer.
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 Orbipay.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields. Only the custom fields enabled for the client, in Orbipay, would be accepted in the requests.
customer_referencestring
The unique identifier in the client system for the customer.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
customer_account_referencestring
The unique identifier in the client system for the customer account.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
account_numberstring
The number or reference that a customer uses to identify the customer's account.
Min. Length: 1Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}. ']+
current_balancestring
The current balance on the customer's account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
current_statement_balancestring
The balance on the customer’s account with the biller as reported on the last statement.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
minimum_payment_duestring
The minimum payment amount, as specified by the biller, that needs to be made against the customer’s account.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
past_amount_duestring
The amount that is due from the past bills/statements on the customer’s account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
payment_due_datestring
The date by which the customer needs to clear the dues against the customer's account with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
statement_datestring
The date on which the biller generates the statement for the customer's account. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
idstring
Id is a unique identifier assigned to the customer account in Orbipay.
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields. Only the custom fields enabled for the client, in Orbipay, would be accepted in the requests.
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
urlstring
This URL fetches the list of Customer accounts of a customer.
funding_accountsobject
urlstring
This URL fetches the list of Funding accounts of a customer.
paymentsobject
urlstring
This URL fetches the list of payments of a customer.
payment_setupsobject
urlstring
This URL fetches the list of payment setups of a customer.
audit_infoobject
createdobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
Create Customer
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to tryout the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on the language button above to try out the API.
The Create Customer API is used to register a customer with a biller in Orbipay. 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.
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.
This API is used to retrieve/lookup customers from Orbipay. Customers can be retrieved matching criteria that includes the customer_reference, the ssn, the email or the customer account number.
Customer Account Number of the customer to get details of.
Min. Length: 1Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}. ']+
Returns
The list of customers matching the criteria provided, the total results count and the urls to get the next/previous pages.
Customer Account
This section outlines the API required to manage Customer Accounts.
The Customer Account Object
Central to Orbipay Payment API, a Customer Account is the virtual destination against which a Payment is made. A Customer Account has balance, inflow and outflow like any bank or card account. Examples of Customer Accounts include: Billing Accounts - against which bill payments can be made Vendor Accounts - against which invoice payments can be made
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
customer_account_referencestring
The unique identifier in the client system for the customer account.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
account_numberstring
The number or reference that a customer uses to identify the customer's account.
Min. Length: 1Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}. ']+
current_balancestring
The current balance on the customer's account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
current_statement_balancestring
The balance on the customer’s account with the biller as reported on the last statement.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
minimum_payment_duestring
The minimum payment amount, as specified by the biller, that needs to be made against the customer’s account.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
past_amount_duestring
The amount that is due from the past bills/statements on the customer’s account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
payment_due_datestring
The date by which the customer needs to clear the dues against the customer's account with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
statement_datestring
The date on which the biller generates the statement for the customer's account. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
idstring
Id is a unique identifier assigned to the customer account in Orbipay.
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields. Only the custom fields enabled for the client, in Orbipay, would be accepted in the requests.
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
Retrieve Customer Accounts
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to tryout the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on the language button above to try out the API.
POST /customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}/renew
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.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 2Max. Length: 10Reg. Exp.: [a-zA-Z0-9 -]{2,10}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
aba_routing_numberstring
The ABA/Routing number for the bank account.
Min. Length: 9Max. Length: 9Reg. Exp.: [0-9]{9}
issuer_namestring
The name of the authority that has issued the account. This is relevant only in the case of bank accounts.
The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by Orbipay. This defaults to USD.
Min. Length: 3Max. Length: 3Reg. Exp.: [A-Z]{3}
expiry_datestring
The expiry date for the card. This is to be in the format MM/yy. Only applicable for cards accounts.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{2}/[0-9]{2}
account_holder_typestring
The type of ownership for the funding account. This is applicable only in the case of bank accounts and it is defaults to personal.
Valid Values: personal, business
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields. Only the custom fields enabled for the client, in Orbipay, would be accepted in the requests.
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account. For e.g., a savings account, a checking account.
Id is a unique identifier assigned to the funding account in Orbipay. A new Id is generated for the funding account when the account number is updated.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
urlstring
This URL fetches the funding account details.
ach_eligible_flagstring
Indicates if the funding account can be debited vide ACH, in case the funding account is a Demand Deposit Account (DDA).
Valid Values: yes, no
atm_eligible_flagstring
Indicates if the funding account can be debited vide the ATM Rail network, in case the funding account is a Debit Card.
Valid Values: yes, no
card_cvv_numberstring
This is never returned by Orbipay. This needs to be passed to Orbipay when adding or editing a card funding account.
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
Add Funding Account
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to tryout the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on the language button above to try out the API.
Request JSON
{"account_holder_name": "Michael Smith","nickname": "Smith","address": {"address_line1": "1551 South Washington Ave","address_line2": "Suite 130 Piscataway","address_city": "Piscataway","address_state": "NJ","address_country": "USA","address_zip1": "12345","address_zip2": "1234"},"account_number": "123450206","aba_routing_number": "123456789","expiry_date": "","account_holder_type": "personal","custom_fields": { },"account_subtype": "savings","card_cvv_number": "","comments": "Adding fund source"}
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.
POST /customers/{ID_CUSTOMER}/fundingaccounts/lists
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 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 type of the funding account. This can take multiple values in the format key=value1&key=value2....
Valid Values: bank, debit_card, credit_card
account_subtypestringin: formData
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
PUT /customers/{ID_CUSTOMER}/fundingaccounts/{ID_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.
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.
POST /customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}/replacement
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.
The unique identifier assigned by Orbipay to the Funding Account.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
ID_CUSTOMERstringin: pathrequired
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
account_holder_namerequired
nickname
address
address_line1
address_line2
address_city
address_state
address_country
address_zip1
address_zip2
account_numberrequired
aba_routing_number
expiry_date
account_holder_type
custom_fields
account_subtype
card_cvv_number
comments
Returns
The replaced funding account.
Payment
This section outlines the API required to enable customers to manage their payments.
The Payment Object
A Payment is always made using a Funding Account. Payments are initiated by a Customer or on behalf of a Customer (i.e., by a customer service agent).Payments follow a "good funds" model, which means the customer must ensure the funds required to make a payment are available in the funding account before initiating the transaction. Payments can be scheduled for the same day or a later date. The actual settlement of the funds will depend on the payment method used (i.e., credit card, ACH etc.) and other factors.
The unique identifier assigned by Orbipay to the payment.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
urlstring
This URL fetches the details of payment.
feeobject
fee_typestring
The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.
Valid Values: add_to_principal, bill_separately
fee_amountstring
The fee amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
idstring
The unique identifier assigned by Orbipay to the fee. In case of split fee.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of fee as a payment resource. In case of split fee.
The confirmation number or reference provided to the customer for the payment.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields. Only the custom fields enabled for the client, in Orbipay, would be accepted in the requests.
currency_code3dstring
The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by Orbipay. This defaults to USD.
Min. Length: 3Max. Length: 3Reg. Exp.: [A-Z]{3}
amountstring
The amount being paid. In case the payment_amount_type is 'discounted_amount', 'penalty_amount' or 'other', the amount needs to be specified. In other cases, this is derived from the payment_amount_type.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
card_cvv_numberstring
This is never returned by Orbipay. This needs to be passed to Orbipay when making or editing a payment with a card funding account.
Min. Length: 3Max. Length: 4Reg. Exp.: [0-9]{3,4}
payment_datestring
The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_schedule_typestring
The schedule type for the payment. This defaults to one_time_payment.
The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD. This is applicable only if the client has opted for it.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_amount_typestring
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.
Valid Values: current_balance, minimum_payment_due, past_payment_due, statement_balance, discounted_amount, penalty_amount, other
payment_referencestring
The unique identifier in the client system for the payment.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
expected_payment_settlement_datestring
The date on which the payment is expected to be settled with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_entry_datestring
The date on which the payment is captured in Orbipay. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_return_datestring
The date on which the ACH returns is received by Orbipay.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
return_codestring
The ACH return code or the chargeback code received from Visa/Mastercard, in the event of returned payments.
Max. Length: 10Reg. Exp.: [a-z0-9]{0,10}
customerobject
The customer making the payment
idstring
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
The URL that can be used to fetch the details of the customer.
customer_referencestring
The unique identifier in the client system for the customer.
The email address of the customer to which notifications from Orbipay will be sent. This will default to the registered_email while creating a customer.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
funding_accountobject
The customer's funding account with which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the funding account details.
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
account_typestring
The type of the funding account.
Valid Values: bank, debit_card, credit_card
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
The customer account against which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the customer account details.
payment_network_responseobject
The response received from either the ACH or Card network.
payment_auth_codestring
The Auth Code returned by the card gateway. This is relevant only for card payments.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]{0,30}
payment_response_codestring
This is the ACH return code in the case of a returned payment over the NACHA ACH network. In the case of declined card payment, it's the decline code received from the card issuer or the card processor. In the case of a card chargeback, it's the chargeback code received from the card network.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]{0,30}
payment_response_msgstring
The text describing the appropriate code captured in the payment_response_code as received from the corresponding payment network.
Max. Length: 200
audit_infoobject
createdobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
Retrieve Payments
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to tryout the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on the language button above to try out the API.
The API is used to retrieve the payments made by a customer. Payments can be filtered using the confirmation number, customer account, funding account, status and payment schedule type, 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.
If the requestor type is customer then the id_customer request parameter is mandatory.
Response content type: application/json
Request Parameters
id_customerstringin: query
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_funding_accountstringin: query
The unique identifier assigned by Orbipay to the funding account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_customer_accountstringin: query
The unique identifier assigned by Orbipay to the customer account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
confirmation_numberstringin: query
The confirmation number or reference provided to the customer for the successful payment.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
statusstringin: query
The status of the payment. This can take multiple values in the format key=value1&key=value2....
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 Orbipay are add_to_principal and bill_separately. Alternatively, the fee information can be setup in Orbipay, 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 Orbipay or creates them otherwise.
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 Orbipay are add_to_principal and bill_separately. Alternatively, the fee information can be setup in Orbipay, 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.
The unique identifier assigned by Orbipay to the payment.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
ID_CUSTOMERstringin: pathrequired
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
comments
Returns
The id of the payment being deleted and the status of the deletion.
Payment Setup
This section outlines the API required to enable customers to set up and manage payment setups for their Customer Accounts.
The Payment Setup Object
Payments can be scheduled on a recurring basis – monthly, quarterly, bi-annually, or annually. Customers can designate a fixed amount to pay for each billing cycle, or set the payment amount to automatically adjust to the current balance due based on a feed sent to Orbipay (this feature requires additional setup). Please contact support@billerpayments.com for more details.
The unique identifier assigned by Orbipay to the payment setup.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
urlstring
This URL fetches the details of payment setup.
feeobject
fee_typestring
The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.
Valid Values: add_to_principal, bill_separately
fee_amountstring
The fee amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
idstring
The unique identifier assigned by Orbipay to the fee. In case of split fee.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of fee as a payment resource. In case of split fee.
The confirmation number or reference provided to the customer for the payment setup.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields. Only the custom fields enabled for the client, in Orbipay, would be accepted in the requests.
currency_code3dstring
The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by Orbipay. This defaults to USD.
Min. Length: 3Max. Length: 3Reg. Exp.: [A-Z]{3}
amountstring
The amount being paid. In case the payment_amount_type is 'discounted_amount', 'penalty_amount' or 'other', the amount needs to be specified. In other cases, this is derived from the payment_amount_type.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
card_cvv_numberstring
This is never returned by Orbipay. This needs to be passed to Orbipay when making or editing a payment setup with a card funding account.
Min. Length: 3Max. Length: 4Reg. Exp.: [0-9]{3,4}
next_payment_datestring
The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_setup_referencestring
The unique identifier in the client system for the payment setup.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
payment_scheduleobject
The schedule for the payments that are created as part of a payment setup like recurring payment or autopay.
payment_recurring_typestring
The frequency of the payments created as part of a payment setup. This is applicable only for recurring payment setup, in which case it is mandatory.
The maximum number of payments that can be created as part of a recurring payment setup. This cannot be specified for autopay setups.
Min. Length: 1Max. Length: 3Reg. Exp.: [0-9]+
payment_amount_typestring
The amount type that is used to set the amount for payments created as part of a recurring payment or autopay setup. In the case of a recurring payment setup, the payment amount can be specified by the customer. In that case, the payment_amount_type should not be sent as it would default to 'other'. In the case of an autopay setup, the payment amount type is mandatory and it cannot be specified as 'other'. In this case, the payment amount should not be sent.
Valid Values: current_balance, minimum_payment_due, past_payment_due, statement_balance, discounted_amount, penalty_amount, other
payment_start_datestring
The date on which the first payment will be drafted as part of a recurring payment setup. This is to be specified in the ISO8601 full-date format, namely, YYYY-MM-DD. This is mandatory for recurring payment setup. This cannot be specified for autopay setups.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_end_datestring
The date by which the last payment will be drafted as part of a recurring payment setup. This is to be specified in the ISO8601 full-date format, namely, YYYY-MM-DD. This cannot be specified for autopay setups.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_limit_amountstring
The upper limit for the payment amount in the case of recurring or autopay payments. Any amount above the limit will not be paid automatically as part of recurring payments and autopay.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
payment_plan_idstring
The reference to the payment plan, offered by the biller, that is used to set up the recurring payment. The list of payment plans offered is published as part of the biller set-up.
Max. Length: 9Reg. Exp.: [0-9]{0,9}
payment_defer_daysstring
The number of days from the bill due date that the customer wishes to delay the autopay payment by. By default an autopay payment is drafted on the bill due date.
Min. Length: 1Max. Length: 2Reg. Exp.: [0-9]+
payment_setup_entry_datestring
The date on which the payment setup is captured in Orbipay. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
customerobject
The customer making the payment
idstring
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
The URL that can be used to fetch the details of the customer.
customer_referencestring
The unique identifier in the client system for the customer.
The email address of the customer to which notifications from Orbipay will be sent. This will default to the registered_email while creating a customer.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
funding_accountobject
The customer's funding account with which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the funding account details.
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
account_typestring
The type of the funding account.
Valid Values: bank, debit_card, credit_card
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
The customer account against which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the customer account details.
payment_network_responseobject
The response received from either the ACH or Card network.
payment_auth_codestring
The Auth Code returned by the card gateway. This is relevant only for card payments.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]{0,30}
payment_response_codestring
This is the ACH return code in the case of a returned payment over the NACHA ACH network. In the case of declined card payment, it's the decline code received from the card issuer or the card processor. In the case of a card chargeback, it's the chargeback code received from the card network.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]{0,30}
payment_response_msgstring
The text describing the appropriate code captured in the payment_response_code as received from the corresponding payment network.
Max. Length: 200
audit_infoobject
createdobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
Retrieve Payment Setups
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to tryout the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on the language button above to try out the API.
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. If the requestor type is customer then the id_customer request parameter is mandatory.
Response content type: application/json
Request Parameters
id_customerstringin: query
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_funding_accountstringin: query
The unique identifier assigned by Orbipay to the funding account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_customer_accountstringin: query
The unique identifier assigned by Orbipay to the customer account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
confirmation_numberstringin: query
The confirmation number or reference provided to the customer for the successful payment.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
statusstringin: query
The status of the payment. This can take multiple values in the format key=value1&key=value2....
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.
The unique identifier assigned by Orbipay to the payment setup.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
ID_CUSTOMERstringin: pathrequired
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
comments
Returns
The id of the recurring payment setup being deleted and the status of the deletion.
Refund
This section outlines the API required to enable customers to get refunded for the payments made via Orbipay.
The Refund Object
Payments made using Orbipay can be fully or partially refunded as one or more refund transactions. Credits are posted to the funding source associated with the payment being refunded. Both ACH and card payment methods are supported for refunds. Only payments in the 'processed' status can be refunded.
The unique identifier in the client system for the refund.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
idstring
The unique identifier assigned by Orbipay to the refund.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of refund.
refund_typestring
The portion of the payment amount that is to be or has been refunded. The original payment can be refunded fully including the amount and the fee components, or partially, for just the amount or the fee component. Refund can also be initiated for an arbitrary amount limited by the original payment amount.
Valid Values: payment_and_fee, payment_only, fee_only, other
refund_amountstring
The refund amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
fee_refundobject
fee_refund_amountstring
The refunded fee amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
fee_typestring
The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.
Valid Values: add_to_principal, bill_separately
statusstring
The status of the refund.
Valid Values: scheduled, cancelled, processing, processed, declined, returned
confirmation_numberstring
The confirmation number or reference provided to the customer for the refund.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
refund_datestring
The date on which the refund is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
refund_entry_datestring
The date on which the refund captured in Orbipay. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
expected_refund_settlement_datestring
The date by which the credits would be posted to the original funding account. ISO8601 full-date format, YYYY-MM-DD
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
source_paymentobject
idstring
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of source payment.
customerobject
idstring
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of source payment.
customer_referencestring
The unique identifier in the client system for the customer.
The number or reference that a customer uses to identify the customer's account.
Min. Length: 1Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}. ']+
funding_accountobject
The customer's funding account with which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the funding account details.
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
account_typestring
The type of the funding account.
Valid Values: bank, debit_card, credit_card
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
The response received from either the ACH or Card network.
payment_auth_codestring
The Auth Code returned by the card gateway. This is relevant only for card payments.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]{0,30}
payment_response_codestring
This is the ACH return code in the case of a returned payment over the NACHA ACH network. In the case of declined card payment, it's the decline code received from the card issuer or the card processor. In the case of a card chargeback, it's the chargeback code received from the card network.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]{0,30}
payment_response_msgstring
The text describing the appropriate code captured in the payment_response_code as received from the corresponding payment network.
Max. Length: 200
audit_infoobject
createdobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
last_modifiedobject
channelstring
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
requestor_typestring
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". It should be noted that these users would not have logins for the Orbipay EBPP Portal or Payment Center.
Valid Values: customer, external_user
requestorstring
The identifier for the requestor of the API, in Orbipay. 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 Orbipay generated customer id. In the case of self registration, where there is no Orbipay 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.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstring
The UTC timestamp, in ISO8601 format, for the moment when the resource got created or modified in Orbipay. For e.g., 2019-08-13T09:21:34.359+0000
Create Refund
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to tryout the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on a language button to try out the API with code samples.
Please click on the language button above to try out the API.
POST /customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}/refunds
This API is used to initiate a refund. Any payment made using Orbipay 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. The refund types that are supported in Orbipay are payment_and_fee, payment_only, fee_only, other. The amount is optional and needs to be specified only if it's a partial refund i.e., the refund type is other.
The API is used to retrieve the refunds made to a customer against payments processed through Orbipay. 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.
If the requestor_type is customer then the id_customer request parameter is mandatory.
"first_name": "Michael", "last_name": "Smith", "middle_name": "S", "gender": "male", "date_of_birth": "1980-11-11", "ssn": "123456789", "locale": "en_US", "email": "userid@example.com", "registered_email": "userid@example.com", "home_phone": "1234567890", "work_phone": "1234567890", "mobile_phone": "1234567890", "address": {