OrbiPay is a highly flexible and configurable electronic bill presentment and payment platform. It enables billers to accept credit, debit, and bank account payments via multiple channels through a single platform.
Organized around REST, the OrbiPay API uses standard HTTP verbs and response codes that can be understood by any HTTP client. All API responses and POST requests are in JSON.
Common Topics
Authentication
Overview
The HTTP Authorization request header is used to provide authentication information. This is how the header should look:
The constituents of the autorization 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.
Signature
The Base 64 encoded value of the signature bytes. Calculating the signature bytes is explained below.
Signature Calculation
The 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. Only parameters with non-null values should be included. Both the parameter names and their values should be trimmed for leading and trailing whitespaces, converted to lowercase and should be in their normal pre-encoded format. 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&…. The headers are to be sorted alphabetically. Only the headers listed by the application and those that are non-empty are to be included. Both the header names and their values must be trimmed for leading and trailing white-space, converted to lowercase and in their normal pre-encoded format
payload()
The raw HTTP body
Errors
HTTP Response Codes
Code
Reason
200 - OK
The request was successfully processed
201 - Created
The object was successfully created
400 - Bad Request
The request was rejected (likely due to invalid parameters)
401, 403 - Unauthorized, Forbidden
Unauthorized or forbidden request
404 - Not Found
The resource does not exist
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; the request could not be processed.
Orbipay Error codes
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_payment_rejected
The error returned if a payment cannot be processed as it violates business rules.
error_invalid_dda
The request can not be completed with the given bank account details.
error_invalid_card
The request can not be completed with the given card account details
error_card_declined
The request can not be completed as the given card is declined by the issuer
error_card_auth
The request can not be completed as the card details providedcan not be validated
error_insufficient_balance
The request can not be completed with the given funding source type. Choose a different type of funding source and try again
error_payment_disallowed
The request can not be processed with the given payment date.
error_customer
The request can not be processed with the given customer/account information.
error_fundsrc
The request can not be processed currently as it is in violation of one or more fund source related business rules.
error_tech_difficulties
The request can not be processed due to incorrect client set-up, issues with card processor set-up, communication issues with card issuer or other technical issues at Orbipay.
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 or 5xx indicates a processing error. In this case, 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.)
Expanding Objects
Expanding objects make the OrbiPay API easy to explore. Objects can be expanded using a request query parameter called “return_expanded_objects” on all API calls. This parameter is not mandatory and can take true or false for values. The default value for “return_expanded_objects” is false.
Custom Fields
Custom fields are useful for storing additional structured information on an object. Orbipay supports custom fields for Customer Accounts and for Payments. 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.
Hypermedia
As per REST guidelines, The OrbiPay API supports hypermedia. This allows for simple and intuitive navigation between Customer, Customer Account, Funding Account and Payment resources, making it easy to fetch associated metadata for any given resource.
Resources
Customers hold 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 Customers billing account.
Request Headers
Every API call includes request headers. These HTTP header parameters are required to define the context in which the API is invoked.
channel
type: integer, required: true
Channel Type identifies the channel of transaction – viz., Online, VRU and Agent (Independent Agent and not through Orbipay Payment Center).
partner
type: string, required: true
Partner Key is a unique identifier assigned to the client by OrbiPay system.
product
type: integer, required: true
Product id for Orbipay is a fixed value of 2.
timestamp
type: string, required: true
Timestamp is of format mm/dd/yyyy HH:mm:ss:SSS z
idempotent_request_key
type: string, required: true
Token sent by the client to identify and trace the request later.
requestor
type: string, required: true
Identifier of the API request sender provided by the Orbipay system. The value to be passed in the requestor field would depend on the requestor type. For customer it would be the Orbipay generated customer id , for user it would be the Orbipay user login id and for external user it would be the client’s ext agent id.
requestor_type
type: string, required: true
Type of the API request sender provided by the Orbipay system – viz., customer, user and external_user.
Response Headers
HTTP header parameters are returned as part of every API response. Most of these parameters match those sent in the request.
channel
type: integer
Channel Type identifies the channel of transaction – viz., Online, VRU and Agent (Independent Agent and not through Orbipay Payment Center).
partner
type: string
Partner Key is a unique identifier assigned to the client by OrbiPay system.
product
type: integer
Product id for Orbipay is a fixed value of 2.
requestor
type: string
Identifier of the API request sender provided by the Orbipay system. The value to be passed in the requestor field would depend on the requestor type. For customer it would be the Orbipay generated customer id , for user it would be the Orbipay user login id and for external user it would be the client’s ext agent id.
requestor_type
type: string
Type of the API request sender provided by the Orbipay system – viz., customer, user and external_user.
timestamp
type: string
Timestamp is of format mm/dd/yyyy HH:mm:ss:SSS z
idempotent_request_key
type: string
Token sent by the client to identify and trace the request later.
request_uuid
type: string
This UUID will be unique to each request and can be used for audit.
response_code
type: integer
A standard response text is provided along with the response code related to limits violation.
response_text
type: string
The response text contains important information about the limits violation and aids customers in modifying the details to successfully make the payment.
PAYMENT API
Customer
This section outlines the APIs 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_id, ssn, email or account number depending on the partner’s choice. If the requestor type is “customer” then one of the attributes that uniquely identifies a customer is mandatory.
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
Id is a unique identifier assigned to the account in OrbiPay system.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
urlstring
This URL fetches the Account details.
custom_fieldsmap
account_holder_namestring
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
The ABA/Routing number of the bank account used for the payment. Must be sent for Bank Accounts.
Exclusive Min.: true  Max. Value: 999999999  
account_subtypestring
Account Sub Type indicates the sub type of a funding account.
Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
currency_code3dstring
3 character ISO currency code should be provided in currencyCode3d field – default to USD.
Max. Length: 3  Reg. Exp.: [a-z0-9]{0,3}  
expiry_datestring
Expiration date of the card in case of Credit/Debit Card
Min. Length: 5  Max. Length: 7  Reg. Exp.: [a-z0-9]{0,7}  
account_holder_typestring
Owner Type field specifies how the account was setup i.e. either personal or corporate account. Valid Values P ( personal) or B (Corporate / Business)
Valid Values: P, B
save_for_future_useboolean
Default: true  
urlstring
This URL fetches the list of Funding accounts of a customer.
paymentsobject
listarray
list[0]object
payment_entry_datestring
Date and Time Payment was created within OrbiPay.
Date Format: YYYY-MM-DD  
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
The ABA/Routing number of the bank account used for the payment. Must be sent for Bank Accounts.
Exclusive Min.: true  Max. Value: 999999999  
account_subtypestring
Account Sub Type indicates the sub type of a funding account.
Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
currency_code3dstring
3 character ISO currency code should be provided in currencyCode3d field – default to USD.
Max. Length: 3  Reg. Exp.: [a-z0-9]{0,3}  
expiry_datestring
Expiration date of the card in case of Credit/Debit Card
Min. Length: 5  Max. Length: 7  Reg. Exp.: [a-z0-9]{0,7}  
account_holder_typestring
Owner Type field specifies how the account was setup i.e. either personal or corporate account. Valid Values P ( personal) or B (Corporate / Business)
Valid Values: P, B
save_for_future_useboolean
Default: true  
customer_accountobject
idstring
Id is a unique identifier assigned to the account in OrbiPay system.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
urlstring
This URL fetches the Account details.
custom_fieldsmap
account_holder_namestring
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
Unique ID assigned by the biller/partner system for a given customer account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
current_balancenumber
The current balance on the customer’s account with the biller.
current_statement_balancenumber
The balance on the customer’s account with the biller as reported on the last statement.
minimum_payment_duenumber
Any minimum payment amount that needs to be made on the customer’s account with the biller.
past_amount_duenumber
Any amount that is past due on the customer’s account with the biller.
payment_due_datestring
The next date a payment needs to be made on the customer’s account with the biller.
Date Format: YYYY-MM-DD  
idstring
Id is the unique identifier assigned by OrbiPay system for the Payment instace and is provided in the response for Create Payment.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
Payment Confirmation Number provided to the customer during payment creation.
Max. Length: 30  Reg. Exp.: [a-z0-9]{0,30}  
custom_fieldsmap
payerobject
urlstring
This URL fetches the Customer details.
customer_idstring
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
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.
Request Object
Attributes
customerrequired
customer_id
first_namerequired
last_namerequired
middle_name
date_of_birth
ssn
language
email
home_phone
work_phone
mobile_phone
address
address_line1required
address_line2
address_cityrequired
address_staterequired
address_countryrequired
address_zip1required
address_zip2
customer_accountsrequired
customer_accounts[0]
comments
custom_fields
account_holder_namerequired
nickname
account_numberrequired
issuer_name
status
address
address_line1required
address_line2
address_cityrequired
address_staterequired
address_countryrequired
address_zip1required
address_zip2
account_id
current_balance
current_statement_balance
minimum_payment_due
past_amount_due
payment_due_date
comments
Returns
The customer created, with the id for the same in Orbipay.
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.
Parameters
ID_CUSTOMER
in: path, type: string, required: true
Id of the customer issued by orbipay system.
Request Object
Attributes
customerrequired
customer_id
first_name
last_name
middle_name
date_of_birth
ssn
language
email
home_phone
work_phone
mobile_phone
address
address_line1required
address_line2
address_cityrequired
address_staterequired
address_countryrequired
address_zip1required
address_zip2
status
comments
customer_accounts
customer_accounts[0]
comments
custom_fields
account_holder_namerequired
nickname
account_numberrequired
issuer_name
status
address
address_line1required
address_line2
address_cityrequired
address_staterequired
address_countryrequired
address_zip1required
address_zip2
account_id
current_balance
current_statement_balance
minimum_payment_due
past_amount_due
payment_due_date
comments
Returns
The customer along with the list of customer accounts available to the customer.
This API is used to retrieve/lookup customers from OrbiPay. Customers can be retrieved matching criteria that includes the customer Id, the SSN, the email or the customer account number.
Parameters
limit
in: query, type: integer, required: false
Using the limit parameter in the request would ensure that a maximum of only that many objects are returned
return_expanded_objects
in: query, type: string, required: false
To get expanded objects in response.
customer_id
in: formData, type: string, required: false
Unique ID assigned by the biller/partner system for a given customer.
ssn
in: formData, type: integer, required: false
ssn of the customer to get details of.
email
in: formData, type: string, required: false
This field contains the customer’s email address within the OrbiPay System.
acct_no
in: formData, type: string, required: false
Customer Account Number of the customer to get details of.
Returns
The list of customers matching the criteria provided, the total results count and the urls to get the next/previous pages.
Funding Account
This section outlines the APIs required to enable customers to manage their funding accounts.
The Funding Account Object
A Customer makes a Payment using a Funding Account. Orbipay supports the use of the following bank and card accounts:
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
The ABA/Routing number of the bank account used for the payment. Must be sent for Bank Accounts.
Exclusive Min.: true  Max. Value: 999999999  
account_subtypestring
Account Sub Type indicates the sub type of a funding account.
Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
currency_code3dstring
3 character ISO currency code should be provided in currencyCode3d field – default to USD.
Max. Length: 3  Reg. Exp.: [a-z0-9]{0,3}  
expiry_datestring
Expiration date of the card in case of Credit/Debit Card
Min. Length: 5  Max. Length: 7  Reg. Exp.: [a-z0-9]{0,7}  
account_holder_typestring
Owner Type field specifies how the account was setup i.e. either personal or corporate account. Valid Values P ( personal) or B (Corporate / Business)
Valid Values: P, B
save_for_future_useboolean
Default: true  
idstring
Id is a unique identifier assigned to the account in OrbiPay system.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
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 is mandatory for bank accounts. Expiry date, address fields and Card CVV are required for card accounts.
Parameters
ID_CUSTOMER
in: path, type: string, required: true
Id of the customer issued by orbipay system.
Request Object
Attributes
ach_eligible_flag
card_cvv_number
comments
account_holder_namerequired
nickname
account_numberrequired
issuer_name
status
address
address_line1required
address_line2
address_cityrequired
address_staterequired
address_countryrequired
address_zip1required
address_zip2
aba_routing_number
account_subtype
currency_code3drequired
expiry_date
account_holder_typerequired
save_for_future_use
Returns
The funding account created, with the id for the same in Orbipay.
POST /customers/{ID_CUSTOMER}/fundingaccounts/retrieve
Retrieve Funding Accounts List of a customer
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 and the account sub-type.
Parameters
ID_CUSTOMER
in: path, type: string, required: true
Id of the customer issued by orbipay system.
limit
in: query, type: integer, required: false
Using the limit parameter in the request would ensure that a maximum of only that many objects are returned
acct_no
in: formData, type: string, required: false
No description
acct_status
in: formData, type: integer, required: false
No description
routing_no
in: formData, type: integer, required: false
The ABA/Routing number of the bank account used for the payment.
acct_type
in: formData, type: integer, required: false
No description
acct_subtype
in: formData, type: integer, required: false
No description
only_saved_accts
in: formData, type: boolean, required: false
No description
Returns
The list of funding accounts matching the criteria provided, the total results count and the urls to get the next/previous pages.
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. 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.
Parameters
ID_ACCOUNT
in: path, type: string, required: true
Id of the Funding/Customer Account issued by orbipay system.
Request Object
Attributes
card_cvv_number
comments
account_holder_namerequired
nickname
account_numberrequired
issuer_name
status
address
address_line1required
address_line2
address_cityrequired
address_staterequired
address_countryrequired
address_zip1required
address_zip2
aba_routing_number
account_subtype
currency_code3drequired
expiry_date
account_holder_typerequired
save_for_future_use
Returns
The updated funding account.
Delete Funding Account
FundingAccount.deleteFundingAccount();
Request JSON
{“comments”: “string”}
Example responses
{“deleted”: true,“id”: “string”}
DELETE /fundingaccounts/{ID_ACCOUNT}
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.
Parameters
ID_ACCOUNT
in: path, type: string, required: true
Id of the Funding/Customer Account issued by orbipay system.
Request Object
Attributes
comments
Returns
The id of the funding account being deleted and the status of the deletion.
Customer Account
This section outlines the APIs required to manage Customer Accounts.
The Customer Account Object
Central to the 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
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
POST /customers/{ID_CUSTOMER}/customeraccounts/retrieve
Retrieve Customer Accounts List of a customer
The API is used to retrieve all the customer accounts associated with a customer. The accounts can be filtered using the account number, status, account sub-type.
Parameters
ID_CUSTOMER
in: path, type: string, required: true
Id of the customer issued by orbipay system.
limit
in: query, type: integer, required: false
Using the limit parameter in the request would ensure that a maximum of only that many objects are returned
acct_no
in: formData, type: string, required: false
No description
acct_status
in: formData, type: integer, required: false
No description
acct_type
in: formData, type: integer, required: false
No description
acct_subtype
in: formData, type: integer, required: false
No description
Returns
List of customer accounts matching the criteria provided, the total results count and the urls to get the next/previous pages.
The Get Customer Account API is used to retrieve the details of a customer account based on the id.
Parameters
ID_ACCOUNT
in: path, type: string, required: true
Id of the Funding/Customer Account issued by orbipay system.
Returns
The customer account.
Payment
This section outlines the APIs required to manage customer 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.
Id is the unique identifier assigned by OrbiPay system for the Payment instace and is provided in the response for Create Payment.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
Payment Confirmation Number provided to the customer during payment creation.
Max. Length: 30  Reg. Exp.: [a-z0-9]{0,30}  
custom_fieldsmap
payerobject
urlstring
This URL fetches the Customer details.
customer_idstring
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
The ABA/Routing number of the bank account used for the payment. Must be sent for Bank Accounts.
Exclusive Min.: true  Max. Value: 999999999  
account_subtypestring
Account Sub Type indicates the sub type of a funding account.
Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
currency_code3dstring
3 character ISO currency code should be provided in currencyCode3d field – default to USD.
Max. Length: 3  Reg. Exp.: [a-z0-9]{0,3}  
expiry_datestring
Expiration date of the card in case of Credit/Debit Card
Min. Length: 5  Max. Length: 7  Reg. Exp.: [a-z0-9]{0,7}  
account_holder_typestring
Owner Type field specifies how the account was setup i.e. either personal or corporate account. Valid Values P ( personal) or B (Corporate / Business)
Valid Values: P, B
save_for_future_useboolean
Default: true  
customer_accountobject
idstring
Id is a unique identifier assigned to the account in OrbiPay system.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
urlstring
This URL fetches the Account details.
custom_fieldsmap
account_holder_namestring
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
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 and by date range. 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 cust_id request parameter is mandatory.
Parameters
cust_id
in: query, type: string, required: false
Id of the Customer, issued by orbipay system
fund_acct
in: query, type: string, required: false
Id of the Funding Account, issued by orbipay system
bill_acct
in: query, type: string, required: false
Id of the Customer Account, issued by orbipay system
conf_no
in: query, type: string, required: false
Payment Confirmation Number provided to the customer during payment creation.
pymnt_status
in: query, type: integer, required: false
No description
pymnt_schld_type
in: query, type: integer, required: false
No description
from_date
in: query, type: string, required: false
No description
to_date
in: query, type: string, required: false
No description
limit
in: query, type: integer, required: false
Using the limit parameter in the request would ensure that a maximum of only that many objects are returned
after_object
in: query, type: integer, required: false
To fetch the next set of objects that start after this object
before_object
in: query, type: integer, required: false
To fetch the previous set of objects that end at this object
return_expanded_objects
in: query, type: string, required: false
To get expanded objects in response.
query_id
in: query, type: string, required: false
query id of the Retrieve/Search Payments lookup.
Returns
List of payments matching the criteria provided, the total results count and the urls to get the next/previous pages.
The API is used to make payments to service a customer account. Client systems can provide the unique identifier of the payment in their system as payment_id.
Fee amount and fee type fields are conditional and should be provided if the details of the fee to be charged are maintained in the client system. The present fee types that are supported are add_to_principal and bill_separately. Alternatively the fee information can be setup in OrbiPay system in which case these fields can be ignored Create and Edit Payment APIs. If fee information is setup in the system, the details of the fee are returned in the response.
Request Object
Attributes
comments
custom_fields
payment_id
currency_code3drequired
amountrequired
payment_daterequired
fee_amount
fee_type
payer
idrequired
payee
idrequired
verification_code
funding_accountrequired
idrequired
customer_accountrequired
idrequired
Returns
The Payment object with confirmation number and id issued by Orbipay system.
The API is used to edit a payment. Only payments in scheduled status can be edited.
Parameters
ID_PAYMENT
in: path, type: string, required: true
Id of the Payment instance,issued by orbipay system
Request Object
Attributes
comments
payment_id
currency_code3drequired
amountrequired
payment_date
fee_amount
fee_type
payer
idrequired
payee
idrequired
verification_code
funding_accountrequired
idrequired
customer_accountrequired
idrequired
Returns
The Payment with the id provided, duly updated.
Delete Payment
Payment.deletePayment();
Request JSON
{“comments”: “string”}
Example responses
{“deleted”: true,“id”: “string”}
DELETE /payments/{ID_PAYMENT}
Delete Payment
The API is used to delete or cancel a payment. Payments in scheduled status can also be cancelled.
Parameters
ID_PAYMENT
in: path, type: string, required: true
Id of the Payment instance,issued by orbipay system
Request Object
Attributes
comments
Returns
The id of the payment being deleted and the status of the deletion.
Recurring Payment
This section outlines the APIs required to enable customers to set up and manage recurring payments 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.
This is required when the payment is of either recurring or autopay types.
payment_schedule_typestring
Payment Schedule Type (pymntSchldType) indicates the schedule type of payments.
Valid Values: one_time_payment, variable_recurring_enrolment, skip_a_payment, autopay_enrollment, autopay_generated_payment, variable_recurring_generated_payment, balance_reload, mobile_payment, invoice_payment
recurring_typestring
Recurring Type (recurringType) indicates the frequency of payments for a recurring payment.
Valid Values: daily, weekly, monthly, bi_monthly, bi_weekly, quarterly, half_yearly, annual
recurring_countinteger
Number of Recurring Payments. This field is only populated for recurring and preauthorized auto debit related payment Detail Records. In case of preauthorized auto debit payment this field will be populated only if number of recurring payments has been defined.
Exclusive Min.: true  Max. Value: 999  
recurring_payment_amount_typestring
Recurring payment amount type indicates the amount type that needs to be used for a pre-authorised debit payment
Valid Values: current_balance, minimum_payment_due, past_payment_due, statement_balance, other
payment_start_datestring
Payment Start Date. ISO8601 full-date format, YYYY-MM-DD. Applicable for payment type Recurring payment.
Date Format: YYYY-MM-DD  
payment_end_datestring
Payment End Date. ISO8601 full-date format, YYYY-MM-DD. Applicable for payment type Recurring payment.
Date Format: YYYY-MM-DD  
payment_limit_amountnumber
payment limit amount
urlstring
This URL fetches the details of payment setup.
idstring
Id is the unique identifier assigned by OrbiPay system for the Payment instace and is provided in the response for Create Payment.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
Payment Confirmation Number provided to the customer during payment creation.
Max. Length: 30  Reg. Exp.: [a-z0-9]{0,30}  
custom_fieldsmap
payerobject
urlstring
This URL fetches the Customer details.
customer_idstring
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
Unique ID assigned by the biller/partner system for a given customer.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
first_namestring
This field contains account holder’s first name and will be sent on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
last_namestring
This field contains the account holder’s last name, and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
middle_namestring
This field contains the account holder’s middle initial and will appear on all types of detail records.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
date_of_birthstring
Date of Birth. ISO8601 full-date format, YYYY-MM-DD
Date Format: YYYY-MM-DD  
ssninteger
This field contains account holder’s SSN or Tax ID number and will appear on all types of detail records.
Exclusive Min.: true  Max. Value: 999999999  
languagestring
Language field should be populated with a five character locale – for e.g., en_us – indicating the customer’s language of preference. This will be used for sending out the customer alerts and notifications from OrbiPay system. If not language indicator is provided it would be defaulted to English.
Max. Length: 5  Reg. Exp.: [a-z0-9]{0,5}  
emailstring
This field contains the customer’s email address within the OrbiPay System.
home_phonestring
Home phone number of the customer
Min. Length: 4  Max. Length: 20  
work_phonestring
Work phone number of the customer
Min. Length: 4  Max. Length: 20  
mobile_phonestring
Mobile phone number of the customer
Min. Length: 4  Max. Length: 20  
Id is the unique identifier assigned by OrbiPay system for the customer and is provided in the response for Create Customer Message (and Check Customer Message).
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
The ABA/Routing number of the bank account used for the payment. Must be sent for Bank Accounts.
Exclusive Min.: true  Max. Value: 999999999  
account_subtypestring
Account Sub Type indicates the sub type of a funding account.
Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
currency_code3dstring
3 character ISO currency code should be provided in currencyCode3d field – default to USD.
Max. Length: 3  Reg. Exp.: [a-z0-9]{0,3}  
expiry_datestring
Expiration date of the card in case of Credit/Debit Card
Min. Length: 5  Max. Length: 7  Reg. Exp.: [a-z0-9]{0,7}  
account_holder_typestring
Owner Type field specifies how the account was setup i.e. either personal or corporate account. Valid Values P ( personal) or B (Corporate / Business)
Valid Values: P, B
save_for_future_useboolean
Default: true  
customer_accountobject
idstring
Id is a unique identifier assigned to the account in OrbiPay system.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
urlstring
This URL fetches the Account details.
custom_fieldsmap
account_holder_namestring
Name on the account.
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
nicknamestring
Any nickname on the account
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
account_numberstring
Customer’s account number with the biller, in case of customer account. Or The account number of the funding source used to fund the payment, in case of Funding account.
Max. Length: 20  Reg. Exp.: [a-z0-9]{0,20}  
issuer_namestring
Name of the account issuer
Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}  
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 schedule type and within a specified date range. 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 cust_id request parameter is mandatory.
Parameters
cust_id
in: query, type: string, required: false
Id of the Customer, issued by orbipay system
fund_acct
in: query, type: string, required: false
Id of the Funding Account, issued by orbipay system
bill_acct
in: query, type: string, required: false
Id of the Customer Account, issued by orbipay system
conf_no
in: query, type: string, required: false
Payment Confirmation Number provided to the customer during payment creation.
pymnt_status
in: query, type: integer, required: false
No description
pymnt_schld_type
in: query, type: integer, required: false
No description
from_date
in: query, type: string, required: false
No description
to_date
in: query, type: string, required: false
No description
limit
in: query, type: integer, required: false
Using the limit parameter in the request would ensure that a maximum of only that many objects are returned
after_object
in: query, type: integer, required: false
To fetch the next set of objects that start after this object
before_object
in: query, type: integer, required: false
To fetch the previous set of objects that end at this object
return_expanded_objects
in: query, type: string, required: false
To get expanded objects in response.
query_id
in: query, type: string, required: false
query id of the Retrieve/Search Payment Setups lookup.
Returns
List of recurring payments setup matching the criteria provided, the total results count and the urls to get the next/previous pages.
The API is used to retrieve the details of a recurring payment setup by id.
Parameters
ID_PAYMENT
in: path, type: string, required: true
Id of the Payment instance,issued by orbipay system
return_expanded_objects
in: query, type: string, required: false
To get expanded objects in response.
Returns
The payment setup with the id provided.
Delete Recurring Payment Setup
RecurringPayment.deleteRecurringPaymentSetup();
Request JSON
{“comments”: “string”}
Example responses
{“deleted”: true,“id”: “string”}
DELETE /payments/recurring/{ID_PAYMENT}
Delete Recurring 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.
Parameters
ID_PAYMENT
in: path, type: string, required: true
Id of the Payment instance,issued by orbipay system
Request Object
Attributes
comments
Returns
The id of the recurring payment setup being deleted and the status of the deletion.