Common Topics

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
        
        
        

        

            

                POST /payments/v1/payments/record HTTP/1.1
            
        
        

            

                Host: api.orbipay.com
                
Content-Type: application/json
                
Accept: application/json
                
product: orbipay_payments
                
idempotent_request_key: 8b528a6c954a4a92a8555dd3f1862e8d
                
client_key: 987654321
                
channel: Independent Agent
                
timestamp: 2018-06-11 15:29:51.412+0530
                
requestor_type: external_user
                
requestor: 123456
                
Authorization: OPAY1-HMAC-SHA256 Credential=987654321,Signature=f42YQ3U2DAvYbkHFf07NOmjKdvRDtXxc2H7AUgVLm+s=
            
        
        

            

                {"payload":"samplepayload"}
            
        
        
    

        

        

            
Signature Calculation
        
        
        

        

            
method() = "POST"
        
        

            
path() = "/payments/v1/payments/record"
        
        

            
queryString() =
                ""
            
        
        

            
headers() =
                "channel=Independent Agent&client_key=987654321&idempotent_request_key=8b528a6c954a4a92a8555dd3f1862e8d&product=orbipay_payments&requestor=123456&requestor_type=external_user&timestamp=2018-06-11
                15:29:51.412+0530"
            
        
        

            
payload() = "{"payload":"samplepayload"}"
        
        

            

                input = "POST:/payments/v1/payments/record::channel=Independent Agent&client_key=987654321&idempotent_request_key=8b528a6c954a4a92a8555dd3f1862e8d&product=orbipay_payments&requestor=123456&requestor_type=external_user&timestamp=2018-06-11
                15:29:51.412+0530:{"payload":"samplepayload"}"
            
        
	

            

                secret = "1234567890"
                
Base64(HMAC-SHA256(secret,input)) = "f42YQ3U2DAvYbkHFf07NOmjKdvRDtXxc2H7AUgVLm+s="
            
        
        
    

Overview

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

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

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

Item	Description
OPAY1-HMAC-SHA256	The algorithm that is used to calculate the signature.
Credential	The 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 string input is computed as follows.

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

Each of the substrings is explained below.

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

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.

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.

Error Codes

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_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_customer	The request cannot be processed since one or more customers with the same details exist already.
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_tech_difficulties	There is a problem processing this request due to technical difficulties.
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_invalid	The request can not be processed with the given funding account information.
error_customer_invalid	The request can not be processed with the given customer information.

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.

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

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: 50  Reg. 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: 50  Reg. 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: 50  Reg. 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.

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

client_keystring The unique identifier assigned by Orbipay to the client. Max. Length: 50  Reg. Exp.: [a-zA-Z0-9_-]{1,50}

productstring The product identifier corresponding to the API. Valid Values: orbipay_payments

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: 50  Reg. Exp.: [a-zA-Z0-9]{1,50}

timestampstring 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_keystring 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: 50  Reg. Exp.: [a-zA-Z0-9]{1,50}

request_uuidstring The unique ID for the request, generated by Orbipay, that can be used for tracing and audit trail. Max. Length: 50  Reg. Exp.: [a-z0-9]{0,50}

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

response_textstring The 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-Headersstring Intended for the future use.

Auxiliary API

API Endpoints
Production:   https://api.orbipay.com/payments/v1
Sandbox:   https://sbapi.orbipay.com/payments/v1

These API are to support clients to access certain critical, yet non-core capabilities in Orbipay. These API are in addition to those available as part of the Orbipay API. These leverage on the resources available as part of the Orbipay.

Recorded Payment

This section outlines the API required to record their payments.

The Record Payment Object

Recorded Payments are initiated by a Customer or on behalf of a Customer (i.e., by a customer service agent).

Object JSON

{
    "id": "123456789", 
    "url": "/recordedpayments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "101.05"
    }, 
    "status": "processed", 
    "payment_method": "cash", 
    "token": "string", 
    "confirmation_number": "string", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "payment_date": "2020-09-07", 
    "payment_schedule_type": "one_time_payment", 
    "payment_amount_type": "statement_balance", 
    "payment_reference": "string", 
    "payment_entry_date": "2020-09-07", 
    "payment_return_date": "2020-09-07", 
    "return_code": "string", 
    "customer": {
        "first_name": "string", 
        "last_name": "string", 
        "middle_name": "string", 
        "gender": "male", 
        "date_of_birth": "2020-09-07", 
        "ssn": "123456789", 
        "locale": "en_US", 
        "email": "userid@example.com", 
        "registered_email": "userid@example.com", 
        "home_phone": "1234567890", 
        "work_phone": "1234567890", 
        "mobile_phone": "1234567890", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }, 
        "custom_fields": { }, 
        "customer_reference": "string", 
        "id": "12684515", 
        "status": "active", 
        "url": "/customers/{ID_CUSTOMER}"
    }, 
    "funding_account": {
        "account_number": "string", 
        "issuer_name": "string"
    }, 
    "customer_account": {
        "account_holder_name": "string", 
        "nickname": "string", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }, 
        "customer_account_reference": "string", 
        "account_number": "string", 
        "current_balance": "101.05", 
        "current_statement_balance": "101.05", 
        "minimum_payment_due": "101.05", 
        "past_amount_due": "101.05", 
        "payment_due_date": "2020-09-07", 
        "statement_date": "2020-09-07", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
        "status": "active", 
        "custom_fields": { }
    }, 
    "audit_info": {
        "created": {
            "channel": "Independent Agent", 
            "requestor_type": "external_user", 
            "requestor": "1234567", 
            "timestamp": "2019-08-13T09:21:34.359+0000"
        }, 
        "last_modified": {
            "channel": "Independent Agent", 
            "requestor_type": "external_user", 
            "requestor": "1234567", 
            "timestamp": "2019-08-13T09:21:34.359+0000"
        }
    }
}

Attributes
idstring The unique identifier assigned by Orbipay to the payment. Max. Length: 20  Reg. 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
fee_amountstring The fee amount upto 2 decimal places. Min. Length: 1  Max. Length: 17  Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
statusstring The status of the payment. Valid Values: processing, processed, cancelled, returned, refunded
payment_methodstring The non fulfillment method for the payment. Valid Values: cash, swiped_card, scanned_check
tokenstring The token is used to uniquely identify the payment, such as the POS token. Max. Length: 64  Reg. Exp.: [0-9a-zA-Z._-]{0,64}
confirmation_numberstring The confirmation number or reference provided to the customer for the payment. Max. Length: 30  Reg. 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.
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: 3  Max. Length: 3  Reg. Exp.: [A-Z]{3}
amountstring The amount being paid. In case the payment_amount_type is 'other', the amount needs to be specified. In other cases, this is derived from the payment_amount_type. Min. Length: 1  Max. Length: 17  Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
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: 10  Max. Length: 10  Date Format: YYYY-MM-DD
payment_schedule_typestring The schedule type for the payment. This defaults to one_time_payment. Valid Values: one_time_payment
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, other
payment_referencestring The unique identifier in the client system for the payment. Max. Length: 50  Reg. Exp.: [0-9a-zA-Z._-]{0,50}
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: 10  Max. Length: 10  Date Format: YYYY-MM-DD
payment_return_datestring The date on which the ACH returns is received by Orbipay. Min. Length: 10  Max. Length: 10  Date 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: 10  Reg. Exp.: [a-z0-9]{0,10}
customerobject The customer making the payment
first_namestring The first name of the customer. Max. Length: 60  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
last_namestring The last name of the customer. Max. Length: 60  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
middle_namestring The middle name of the customer. Max. Length: 60  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
genderstring The gender of the customer. Valid Values: male, female
date_of_birthstring The date of birth of the customer. It should be in the full-date format as per ISO8601, namely, YYYY-MM-DD. Min. Length: 10  Max. Length: 10  Date 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: 9  Max. Length: 9  Reg. Exp.: [0-9]{9}
localestring The language in which the payee 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: 5  Max. Length: 5  Reg. Exp.: ^[a-z]{2}_[A-Z]{2}$
emailstring The email address of the customer. Max. Length: 100  Reg. Exp.: [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]+
registered_emailstring 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. Max. Length: 100  Reg. Exp.: [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]+
home_phonestring The home phone number of the customer. Min. Length: 10  Max. Length: 10  Reg. Exp.: [0-9]{10}
work_phonestring The work phone number of the customer. Min. Length: 10  Max. Length: 10  Reg. Exp.: [0-9]{10}
mobile_phonestring The mobile phone number of the customer. Min. Length: 10  Max. Length: 10  Reg. Exp.: [0-9]{10}
addressobject
address_line1string Max. Length: 100  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
address_line2string Max. Length: 100  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
address_citystring Max. Length: 20  Reg. Exp.: [0-9a-zA-Z ,.-]+
address_statestring The 2-letter state code used by the US Postal Service. Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}
address_countrystring The 3 digit ISO country code. Min. Length: 3  Max. Length: 3  Reg. Exp.: [a-zA-Z]{3}
address_zip1string The 5 digit postal code used by the US Postal Service. Min. Length: 5  Max. Length: 5  Reg. 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. Min. Length: 4  Max. Length: 4  Reg. 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.
customer_referencestring The unique identifier in the client system for the customer. Max. Length: 100  Reg. Exp.: ^$|[0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\s\\"]+
idstring The unique identifier assigned by Orbipay to the customer. Max. Length: 20  Reg. Exp.: [0-9]{0,20}
statusstring The status of the customer in Orbipay. Valid Values: active, disabled, voluntary_cancellation, revoked, suspended, inactive
urlstring The URL that can be used to fetch the details of the customer.
funding_accountobject
account_numberstring The number or reference that a customer uses to identify the funding account. or last 4 digits of account number. Min. Length: 4  Max. Length: 16  Reg. Exp.: [a-zA-Z0-9]+
issuer_namestring The name of the authority that has issued the account. Max. Length: 30  Reg. Exp.: [a-zA-Z ]+
customer_accountobject The customer account against which the payment is being made.
account_holder_namestring The name as specified on the account. Max. Length: 60  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
nicknamestring The nickname by which a customer might want to identify the account. Max. Length: 50  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
addressobject
address_line1string Max. Length: 100  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
address_line2string Max. Length: 100  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+
address_citystring Max. Length: 20  Reg. Exp.: [0-9a-zA-Z ,.-]+
address_statestring The 2-letter state code used by the US Postal Service. Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}
address_countrystring The 3 digit ISO country code. Min. Length: 3  Max. Length: 3  Reg. Exp.: [a-zA-Z]{3}
address_zip1string The 5 digit postal code used by the US Postal Service. Min. Length: 5  Max. Length: 5  Reg. 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. Min. Length: 4  Max. Length: 4  Reg. Exp.: [0-9]{4}
customer_account_referencestring The unique identifier in the client system for the customer account. Max. Length: 50  Reg. 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: 1  Max. Length: 32  Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}.]+
current_balancestring The current balance on the customer's account with the biller. Min. Length: 1  Max. Length: 18  Reg. 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: 1  Max. Length: 18  Reg. 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: 1  Max. Length: 18  Reg. 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: 1  Max. Length: 18  Reg. 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: 10  Max. Length: 10  Date 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: 10  Max. Length: 10  Date Format: YYYY-MM-DD
idstring Id is a unique identifier assigned to the account in Orbipay. Max. Length: 20  Reg. Exp.: [0-9]{0,20}
urlstring This URL fetches the customer account details.
statusstring The status of the customer's account in Orbipay. Valid Values: active, inactive, suspended, deleted, unverified, unusable
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.
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: 50  Reg. 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: 50  Reg. 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

Record Payment

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.

Request JSON

{
    "amount": "101.05", 
    "payment_date": "2020-09-07", 
    "payment_amount_type": "statement_balance", 
    "payment_method": "cash", 
    "token": "string", 
    "fee": {
        "fee_amount": "101.05"
    }, 
    "customer": {
        "customer_reference": "string", 
        "first_name": "string", 
        "last_name": "string", 
        "middle_name": "string", 
        "gender": "male", 
        "date_of_birth": "2020-09-07", 
        "ssn": "123456789", 
        "locale": "en_US", 
        "email": "userid@example.com", 
        "registered_email": "userid@example.com", 
        "home_phone": "1234567890", 
        "work_phone": "1234567890", 
        "mobile_phone": "1234567890", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }, 
        "custom_fields": { }
    }, 
    "funding_account": {
        "account_number": "string", 
        "issuer_name": "string"
    }, 
    "customer_account": {
        "account_holder_name": "string", 
        "nickname": "string", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }, 
        "customer_account_reference": "string", 
        "account_number": "string", 
        "current_balance": "101.05", 
        "current_statement_balance": "101.05", 
        "minimum_payment_due": "101.05", 
        "past_amount_due": "101.05", 
        "payment_due_date": "2020-09-07", 
        "statement_date": "2020-09-07", 
        "custom_fields": { }
    }, 
    "payment_reference": "string", 
    "comments": "string", 
    "custom_fields": { }
}

Example responses

{
    "id": "123456789", 
    "url": "/recordedpayments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "101.05"
    }, 
    "status": "processed", 
    "payment_method": "cash", 
    "token": "string", 
    "confirmation_number": "string", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "payment_date": "2020-09-07", 
    "payment_schedule_type": "one_time_payment", 
    "payment_amount_type": "statement_balance", 
    "payment_reference": "string", 
    "payment_entry_date": "2020-09-07", 
    "payment_return_date": "2020-09-07", 
    "return_code": "string", 
    "customer": {
        "first_name": "string", 
        "last_name": "string", 
        "middle_name": "string", 
        "gender": "male", 
        "date_of_birth": "2020-09-07", 
        "ssn": "123456789", 
        "locale": "en_US", 
        "email": "userid@example.com", 
        "registered_email": "userid@example.com", 
        "home_phone": "1234567890", 
        "work_phone": "1234567890", 
        "mobile_phone": "1234567890", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }, 
        "custom_fields": { }, 
        "customer_reference": "string", 
        "id": "12684515", 
        "status": "active", 
        "url": "/customers/{ID_CUSTOMER}"
    }, 
    "funding_account": {
        "account_number": "string", 
        "issuer_name": "string"
    }, 
    "customer_account": {
        "account_holder_name": "string", 
        "nickname": "string", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }, 
        "customer_account_reference": "string", 
        "account_number": "string", 
        "current_balance": "101.05", 
        "current_statement_balance": "101.05", 
        "minimum_payment_due": "101.05", 
        "past_amount_due": "101.05", 
        "payment_due_date": "2020-09-07", 
        "statement_date": "2020-09-07", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
        "status": "active", 
        "custom_fields": { }
    }, 
    "audit_info": {
        "created": {
            "channel": "Independent Agent", 
            "requestor_type": "external_user", 
            "requestor": "1234567", 
            "timestamp": "2019-08-13T09:21:34.359+0000"
        }, 
        "last_modified": {
            "channel": "Independent Agent", 
            "requestor_type": "external_user", 
            "requestor": "1234567", 
            "timestamp": "2019-08-13T09:21:34.359+0000"
        }
    }
}

POST /recordedpayments

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

Request content type: application/json Response content type: application/json

Request Object

Attributes
amount
payment_daterequired
payment_amount_type
payment_methodrequired
token
fee
fee_amount
customerrequired
customer_reference
first_name
last_name
middle_name
gender
date_of_birth
ssn
locale
email
registered_email
home_phone
work_phone
mobile_phone
address
address_line1
address_line2
address_city
address_state
address_country
address_zip1
address_zip2
custom_fields
funding_account
account_number
issuer_name
customer_accountrequired
account_holder_namerequired
nickname
address
address_line1
address_line2
address_city
address_state
address_country
address_zip1
address_zip2
customer_account_reference
account_numberrequired
current_balance
current_statement_balance
minimum_payment_due
past_amount_due
payment_due_date
statement_date
custom_fields
payment_reference
comments
custom_fields

Returns

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

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

Example responses

{
    "list": [
        {
            "id": "123456789", 
            "url": "/recordedpayments/{ID_PAYMENT}", 
            "fee": {
                "fee_type": "add_to_principal", 
                "fee_amount": "101.05"
            }, 
            "status": "processed", 
            "payment_method": "cash", 
            "token": "string", 
            "confirmation_number": "string", 
            "custom_fields": { }, 
            "currency_code3d": "USD", 
            "amount": "101.05", 
            "payment_date": "2020-09-07", 
            "payment_schedule_type": "one_time_payment", 
            "payment_amount_type": "statement_balance", 
            "payment_reference": "string", 
            "payment_entry_date": "2020-09-07", 
            "payment_return_date": "2020-09-07", 
            "return_code": "string", 
            "customer": {
                "id": "12684515", 
                "url": "/customers/{ID_CUSTOMER}", 
                "customer_reference": "IkdphX8DsEtOeOI_73823121", 
                "first_name": "string", 
                "last_name": "string", 
                "middle_name": "string", 
                "email": "userid@example.com", 
                "home_phone": "1234567890", 
                "address": {
                    "address_line1": "string", 
                    "address_line2": "string", 
                    "address_city": "Piscataway", 
                    "address_state": "AK", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }
            }, 
            "funding_account": {
                "account_number": "string", 
                "issuer_name": "string"
            }, 
            "customer_account": {
                "account_number": "478E4385e604B685", 
                "id": "123456789", 
                "url": "/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
            }, 
            "audit_info": {
                "created": {
                    "channel": "Independent Agent", 
                    "requestor_type": "external_user", 
                    "requestor": "1234567", 
                    "timestamp": "2019-08-13T09:21:34.359+0000"
                }, 
                "last_modified": {
                    "channel": "Independent Agent", 
                    "requestor_type": "external_user", 
                    "requestor": "1234567", 
                    "timestamp": "2019-08-13T09:21:34.359+0000"
                }
            }
        }
    ], 
    "total_results_count": "10", 
    "has_more_results": "true", 
    "url": "/recordedpayments?query_id=cakbhjaksgasdv6uiv6", 
    "from_index": "1", 
    "to_index": "10", 
    "query_id": "cakbhjaksgasdv6uiv6"
}

GET /recordedpayments

The API is used to retrieve the payments made by a customer. Payments can be filtered using the confirmation number, customer account, status, 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.

Response content type: application/json

Request Parameters

id_customerstringin: query required The unique identifier assigned by Orbipay to the customer. Max. Length: 20  Reg. Exp.: [0-9]{1,20}

id_customer_accountstringin: query The unique identifier assigned by Orbipay to the customer account Max. Length: 20  Reg. Exp.: [0-9]{1,20}

confirmation_numberstringin: query The confirmation number or reference provided to the customer for the successful payment. Max. Length: 30  Reg. Exp.: [a-zA-Z0-9]+

payment_methodstringin: query The non fulfillment method for the payment. This can take multiple values in the format key=value1&key=value2.... Valid Values: cash, swiped_card, scanned_check

statusstringin: query The status of the payment. This can take multiple values in the format key=value1&key=value2.... Valid Values: scheduled, processing, processed, cancelled, returned, refunded

from_datestringin: query The date from which payments, matching the criteria specified, need to be retrieved. Date Format: YYYY-MM-DD

to_datestringin: query The date upto which payments, matching the criteria specified, need to be retrieved. Date Format: YYYY-MM-DD

page_sizestringin: query The maximum number of objects returned in the query. Min. Length: 1  Max. Length: 2  Reg. Exp.: [0-9]+

Returns

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

Get Recorded Payment

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.

Example responses

{
    "id": "123456789", 
    "url": "/recordedpayments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "101.05"
    }, 
    "status": "processed", 
    "payment_method": "cash", 
    "token": "string", 
    "confirmation_number": "string", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "payment_date": "2020-09-07", 
    "payment_schedule_type": "one_time_payment", 
    "payment_amount_type": "statement_balance", 
    "payment_reference": "string", 
    "payment_entry_date": "2020-09-07", 
    "payment_return_date": "2020-09-07", 
    "return_code": "string", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "customer_reference": "IkdphX8DsEtOeOI_73823121", 
        "first_name": "string", 
        "last_name": "string", 
        "middle_name": "string", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "string", 
            "address_line2": "string", 
            "address_city": "Piscataway", 
            "address_state": "AK", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "account_number": "string", 
        "issuer_name": "string"
    }, 
    "customer_account": {
        "account_number": "478E4385e604B685", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }, 
    "audit_info": {
        "created": {
            "channel": "Independent Agent", 
            "requestor_type": "external_user", 
            "requestor": "1234567", 
            "timestamp": "2019-08-13T09:21:34.359+0000"
        }, 
        "last_modified": {
            "channel": "Independent Agent", 
            "requestor_type": "external_user", 
            "requestor": "1234567", 
            "timestamp": "2019-08-13T09:21:34.359+0000"
        }
    }
}

GET /recordedpayments/{ID_PAYMENT}

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

Response content type: application/json

Request Parameters

ID_PAYMENTstringin: path required The unique identifier assigned by Orbipay to the payment. Max. Length: 20  Reg. Exp.: [0-9]{1,20}

Returns

The Payment with the id provided.

Delete Recorded Payment

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.

DELETE /recordedpayments/{ID_PAYMENT}

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

Response content type: application/json

Request Parameters

ID_PAYMENTstringin: path required The unique identifier assigned by Orbipay to the payment. Max. Length: 20  Reg. Exp.: [0-9]{1,20}

Returns

Fee

This section outlines the API required to evaluate the fee for a payment being processed in Orbipay. The fee is evaluated based on the configuration provided by the biller.

The Fee Object

Fee can be applied to a Payment being processed by Orbipay. Fee can be added to the payment amount and processed along with the payment or as a separate transaction. The fee to be charged for a payment can be passed along with the payment request in the fee section. Alternatively, it can be calculated by Orbipay based on the configuration provided by the biller. Different fee structures, like flat fee, percentage fee and combination fee can be configured against paramters like channel, payment method and payment type. In addition to these fee can also be configured against the customer's state, card type, if the payment is made using a card or the routing number, if the payment is made using a bank account.

Object JSON

{
    "fee_type": "add_to_principal", 
    "fee_amount": "101.05", 
    "fee_config": {
        "fee_structure": "flat_fee", 
        "fee_config_details": [
            {
                "fee_config_type": "fixed", 
                "fee_config_params": { }
            }
        ]
    }
}

Attributes
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
fee_amountstring The fee amount upto 2 decimal places. Min. Length: 1  Max. Length: 17  Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
fee_configobject Configuration for the biller that is used to calculate fee. A biller can have multiple fee configurations. The one that matches the best for a payment is applied.
fee_structurestring The fee structure of the fee configured for the biller in Orbipay. Valid Values: flat_fee, percentage_fee_without_limits, percentage_fee_with_limits, combination_fee_without_limits, combination_fee_with_limits
fee_config_detailsarray
fee_config_details[n]object The fee config details of fee configured for the biller in Orbipay.
fee_config_typestring The fee config type of the fee configured for the biller in Orbipay. Valid Values: fixed, percentage
fee_config_paramsmap The fee config params for the fee configured for the biller in Orbipay.

Calculate Fee

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.

Example responses

{
    "fee_type": "add_to_principal", 
    "fee_amount": "101.05", 
    "fee_config": {
        "fee_structure": "flat_fee", 
        "fee_config_details": [
            {
                "fee_config_type": "fixed", 
                "fee_config_params": { }
            }
        ]
    }
}

POST /feecalculators

This API is used to retrieve the fee calculated based on the request parameters.

Request content type: application/x-www-form-urlencoded Response content type: application/json

Request Parameters

amountstringin: formData required The amount for the payment. Min. Length: 1  Max. Length: 17  Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$

payment_schedule_typestringin: formData required The schedule type for the payment. Valid Values: one_time_payment, autopay_generated_payment, variable_recurring_generated_payment, payment_plan_generated

id_customerstringin: formData The unique identifier assigned by Orbipay to the customer. Max. Length: 20  Reg. Exp.: [0-9]{1,20}

address_statestringin: formData The state or province code of the customer in the ISO_3166-2 format. For e.g.,... This is not required to be sent if the ID of the customer is available. Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}

id_funding_accountstringin: formData The unique identifier assigned by Orbipay to the funding account Max. Length: 20  Reg. Exp.: [0-9]{1,20}

account_numberstringin: formData The account number of the funding account being used for the payment. This is not required to be sent if the ID of the funding account is available. Min. Length: 4  Max. Length: 32  Reg. Exp.: [a-zA-Z0-9]+

aba_routing_numberstringin: formData The aba routing number of the funding account being used for the payment. This is not required to be sent if the ID of the funding account is available. Min. Length: 9  Max. Length: 9  Reg. Exp.: [0-9]{9}

account_typestringin: formData The account type of the funding account being used for the payment. This is not required to be sent if the ID of the funding account is available. Valid Values: bank, card

account_subtypestringin: formData The account sub type of the funding account being used for the payment. This is not required to be sent if the ID of the funding account is available. Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit

Returns

The fee amount calculated for the payment along with the details of the fee structure used for the fee calculation.