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
GET /payments/v1/payments?page_size=10&id_customer
=123456&from_date= & status = scheduled
&status=processing HTTP/1.1
The constituents of the authorization header are explained in the table below.
Item
Description
OPAY1-HMAC-SHA256
The algorithm that is used to calculate the signature.
Credential
The client key ( Please refer to the Request Headers section for more details ).
Signature
The Base 64 encoded value of the signature bytes. Calculating the signature bytes is explained below.
Signature Calculation
Signature is calculated as follows.
Base64(HMAC-SHA256(secret,input))
The calculation is explained in detail below.
Item
Description
Base64()
The encoding of the signature bytes.
HMAC-SHA256()
The cryptographic function that computes the HMAC by using the SHA256 algorithm with the client secret provided.
secret
The secret key specific to the client that is shared with the client during onboarding.
input
The string value of the canonicalized transform of request data that includes the HTTP method, URL, headers, query parameters and body. The details of computing the input is explained below.
The HTTP method for the given request and evaluates to one of GET, PUT, POST or DELETE.
path()
The absolute path component of the URI—everything starting with the "/" that follows the domain name and up to the end of the string or to the question mark character ("?") if the given URL has query string parameters.
queryString()
A string in the format param1=value1¶m2=value2&…, where the query parameters are sorted in alphabetical order of the parameter names. In case multiple values are present for a parameter, the query parameters are sorted in alphabetical order of the parameter names and subsequently by the parameter values for each such paramter. Both the parameter names and their values should be trimmed for leading and trailing whitespaces, should be in their normal pre-encoded format. Only parameters with non-empty values, after trimming the leading and trailing whitespaces, should be included. If there are no query parameters at all, the queryString() should evaluate to an empty string (“”).
headers()
A string in the format header1=value1&header2=value2&.......&headerN=valueN. The headers are to be sorted alphabetically. Both the header names and their values must be trimmed for leading and trailing white-space, and in their normal pre-encoded format . Only the headers listed by the application and those that are non-empty, after trimming the leading and trailing whitespaces, are to be included.
payload()
The raw HTTP body
HTTP Response Codes
Http Response Codes
Code
Reason
200 - OK
Successfully processed the request
201 - Created
The object was successfully created
400 - Bad Request
The request was rejected, most likely due to invalid parameters
401, 403 - Unauthorized, Forbidden
Unauthorized or forbidden request
404 - Not Found
The resource does not exist
409 - Conflict
This typically occurs when duplicate requests are received even while the original request is being processed.
422 - Unprocessable Entity
The request body contains well-formed (i.e., syntactically correct), but semantically erroneous, instructions.
500 - Internal Server Error
Something went wrong with Orbipay and the request could not be processed.
Orbipay uses standard HTTP response codes to return the status of an API call. Additional information, such as errors, may be useful to a caller. An HTTP response code of 2xx indicates success. In this case, additional information pertaining to the request is sent back in the header parameters. An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Orbipay also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable.)
Custom Fields
Custom fields are useful for storing additional structured information on an object. Please check with the specific Resource definition below to check if it supports custom fields. For example, you could store the customer’s full name and corresponding unique identifier from your system, on a Orbipay Customer object. Custom fields are only captured and stored by Orbipay and not used for processing of any sort. Please contact support@billerpayments.com for any additional requirement you may have on custom fields.
Hypermedia
As per REST guidelines, Orbipay API supports hypermedia. This allows for simple and intuitive navigation between the resources, making it easy to fetch associated metadata for any given resource.
Pagination
The various Retrieve methods listed below, like Retrieve Customers, Retrieve Payments and Retrieve Funding Accounts return a list of results matching the specified filter criteria. However, all the items in the list are not returned at once, but instead are returned in groups called pages. The size of the page can be set by the caller using the request parameter called page_size. The default page size is 10.
Each page of results consists of a list of items, the url to fetch any page in the list along with the from index and the to index of the results on that page. If both from_index and to_index are provided, only from_index is considered.To fetch any page in the list, the appropriate query string has to be appended to the url. This can be done as follows.
<url>?from_index=<new from index>&page_size=<page size>
( or )
<url>?to_index=<new to index>&page_size=<page size>
For e.g., the second page of a list with a page size of 10 would return with from_index 11 and to_index 20. To retrieve the third page, the from_index to be used in the request would be 21 and for the first page would be 1. The third page could be retrieved using any of the following urls.
<url>?from_index=21&page_size=10
( or )
<url>?to_index=30&page_size=10
Error Codes
An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Orbipay also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable). The Payments API specific error codes are described here.
code
message
error_field
The error returned if a mandatory field is missing value or if the value is invalid. This is accompanied by the field that caused the error.
error_customer_missing
The request cannot be processed due to invalid customer details.
error_dda_invalid
The request cannot be processed due to invalid bank details.
error_payment_rejected
The payment is rejected due to business rules violation.
error_payment_disallowed
The payment is disallowed due to business rules violation.
error_duplicate_payment
The payment is rejected as it duplicates an existing one.
error_payment_update_disallowed
The payment cannot be modified due to business rules violation.
error_funding_account_missing
The request cannot be processed due to invalid funding account.
error_duplicate_customer
The request cannot be processed since one or more customers with the same details exist already.
error_card_expiry
The payment is rejected as the card expires before the payment date.
error_card_auth
The card could not be authorized.
error_customer_account_missing
The request can not be processed with the given account information.
error_customer_account_invalid
The request can not be processed with the given account information.
error_duplicate_customer_account
The request cannot be processed since one or more customer accounts with the same details exist already.
error_card_invalid
Invalid card.
error_insufficient_balance
The funding account does not have sufficient balance.
error_card_declined
The card has been declined.
error_funding_account_limit_reached
The funding account cannot be added since it has reached the maximum limit of funding accounts per customer.
error_tech_difficulties
There is a problem processing this request due to technical difficulties.
error_card_cvv_mismatch
The payment is rejected as the card CVV details mismatch with cardholders bank.
error_card_avs_mismatch
The payment is rejected as the card AVS details mismatch with cardholders bank.
error_funding_account_update_disallowed
The funding account cannot be modified due to business rules violation.
error_duplicate_funding_account
The funding account is rejected as it duplicates an existing one.
error_unsupported_card
The request cannot be processed as the card is not supported for the client.
error_fee_amount_disallowed
The fee amount cannot be accepted as it's configured to be calculated by Orbipay.
error_customer_account_limit_reached
The request cannot be processed since it has reached the maximum limit of customer accounts per customer. This generally occurs when a new customer account is trying to be added for an existing customer or multiple customer accounts are trying to be added for a new customer and multiple customer accounts are not supported for the client.
error_customer_forbidden
The request cannot be processed as the customer may be suspended or revoked. In such cases the customer is forbidden from performing actions like making payments and adding funding accounts.
error_funding_account_unusable
The request cannot be processed as the funding account is unusable. Funding accounts that are in statuses like inactive, suspended and deleted cannot be used for making payments.
error_funding_account_blocked
The request cannot be processed as the funding account is blocked.
error_funding_account_disallowed
The request cannot be processed as the funding account status does not allow it. Funding accounts that are in statuses like inactive, suspended and frozen cannot be updated. New funding accounts cannot be created if another one with the same details is in one of the above statuses.
error_funding_account_address_disallowed
The request cannot be processed as the funding account with the given address is not allowed. This generally occurs when funding accounts with overseas addresses are used and the client has not opted for the same.
error_payment_not_schedulable
The payment cannot be scheduled for the date provided since it might be a holiday or past cut-off time.
error_payment_setup_disallowed
The payment setup is disallowed due to business rules violation.
error_refund_disallowed
The refund is disallowed due to business rules violation.
error_payment_setup_limit_amount_disallowed
The maximum payment limit amount cannot be accepted for the payment setup as it is not configured by the client with Orbipay.
Resources
Customers holds Customer Accounts. A Payment is always made against a Customer Account by/on behalf of a Customer using an associated Funding Account. Each of these resources is labeled with its own id in Orbipay.
Customer
The individual or entity associated with a Customer Account.
Customer Account
The billing account against which a customer makes payments.
Funding Account
The credit, debit, or bank account being used to make a payment.
Payment
The process through which funds from an associated Funding Account are applied towards a balance due on a Customer's billing account.
Payment Setup
The process through which funds from an associated Funding Account are applied towards a balance due on a Customer's billing account on a recurring basis as per a template specified by the customer.
Refund
The process which enable customers to get refunded for a payment that they made.
Duplicate Requests & Retries
We support idempotency for the HTTP methods POST, PUT, DELETE and PATCH using the header parameter, namely, idempotent_request_key.
In other words, any POST, PUT, DELETE and PATCH request will be considered as a duplicate request or retry and not reprocessed by Orbipay if all the request parameters, including the path and query parameters, the request headers and the request body, match with an earlier request. In case of duplicate requests or retries, the API response will be that of the original request.The only exceptions to this are the Retrieve API even though they may use HTTP POST. We do not consider duplicate requests for Retrieve API like Retrieve Customers, Retrieve Customer Accounts and Retrieve Funding Accounts as idempotent requests.
The idempotent_request_key is valid only for a duration of one hour from the time of the original request. Any duplicate request or retries after a gap of one hour from the original request will be considered as a fresh request and reprocessed by Orbipay.
Orbipay does not support retry of GET requests and these are processed every time, irrespective of the idempotent_request_key.
Request Headers
Every API call includes request headers. These HTTP header parameters are required to define the context in which the API is invoked.
channelstringrequired
The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
client_keystringrequired
The unique identifier assigned by Orbipay to the client.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9_-]{1,50}
productstringrequired
The product identifier corresponding to the API.
Valid Values: orbipay_payments
timestampstringrequired
The timestamp for the moment when the API call is made, in the format, yyyy-MM-dd HH:mm:ss.SSSZ For e.g., 2018-07-13 11:41:17.422+00:00 Please ensure that consecutive spaces are not used in the timestamp.
idempotent_request_keystringrequired
The unique token that clients can generate and maintain in order to identify an API request. This is used by Orbipay to identify duplicate requests and retrials. Please refer to the "Duplicate Requests & Retrials" section for more details.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
requestor_typestringrequired
If an API is being requested from an application that is being used directly by a customer, like the customer portal and IVR, the requestor_type should be set to "customer". If an API is being requested from an application that is being used by an agent or a customer service representative belonging to the biller/client organization, then the requestor_type should be set to "client_agent". It should be noted that there should be a user in the EBPP Portal (or Payment Center) corresponding to this user.If an API is being requested from an application that is being used by third party agents 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.
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 "client_agent", the requestor should be the login id for the client agent user to the Orbipay EBPP Portal / Payment Center. If the requestor_type is "external_user", the requestor can be any unique identifier that the client may have for the external agent.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
X-OPAY-Headersstring
Intended for the future use.
Response Headers
HTTP header parameters are returned as part of every API response. Most of these parameters match those sent in the request.
channelstringThe channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.
client_keystringThe unique identifier assigned by Orbipay to the client.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9_-]{1,50}
productstringThe product identifier corresponding to the API.
Valid Values: orbipay_payments
requestor_typestringIf an API is being requested from an application that is being used directly by a customer, like the customer portal and IVR, the requestor_type should be set to "customer". If an API is being requested from an application that is being used by an agent or a customer service representative belonging to the biller/client organization, then the requestor_type should be set to "client_agent". It should be noted that there should be a user in the EBPP Portal (or Payment Center) corresponding to this user.If an API is being requested from an application that is being used by third party agents 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.
requestorstringThe identifier for the requestor of the API, in Orbipay. The value to be passed in the requestor field would depend on the requestor_type. If the requestor_type is "customer", the requestor should be the Orbipay generated customer id. In the case of self registration, where there is no Orbipay generated customer id yet, the requestor should be set to 'guest'. If the requestor_type is "client_agent", the requestor should be the login id for the client agent user to the Orbipay EBPP Portal / Payment Center. If the requestor_type is "external_user", the requestor can be any unique identifier that the client may have for the external agent.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
timestampstringThe timestamp for the moment when the API call is made, in the format, yyyy-MM-dd HH:mm:ss.SSSZ For e.g., 2018-07-13 11:41:17.422+00:00 Please ensure that consecutive spaces are not used in the timestamp.
idempotent_request_keystringThe unique token that clients can generate and maintain in order to identify an API request. This is used by Orbipay to identify duplicate requests and retrials. Please refer to the "Duplicate Requests & Retrials" section for more details.
Max. Length: 50Reg. Exp.: [a-zA-Z0-9]{1,50}
request_uuidstringThe unique ID for the request, generated by Orbipay, that can be used for tracing and audit trail.
Max. Length: 50Reg. Exp.: [a-z0-9]{0,50}
response_codesstringCodes corresponding to any additional information or warning, pertaining to the API call, in a comma separated format, that are returned in the response.
response_textstringThe text detailing any additional information or warning, pertaining to the API call, in a pipe separated format, that is returned in the response.
X-OPAY-HeadersstringIntended for the future use.
Payments API
API EndpointsProduction: https://api.orbipay.com/payments/v1Sandbox: https://sbapi.orbipay.com/payments/v1
The Payments API enables businesses to accept credit, debit, and bank account payments.
Customer
This section outlines the API required to exchange and manage customer information, such as customer account details.
The Customer Object
A Customer holds Customer Accounts. Customer Accounts are always associated with a Customer. A Customer can be an individual, or an entity - such as an organization or a business. A customer can be uniquely identified using any one of its attributes, namely, customer_reference, ssn, email or account number depending on the client's choice. If the requestor type is "customer" then one of the attributes that uniquely identifies a customer is mandatory.
The date of birth of the customer. It should be in the full-date format as per ISO8601, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
ssnstring
The SSN of the customer if the account holder is an individual or the tax ID, if the customer is a business.
Min. Length: 9Max. Length: 9Reg. Exp.: [0-9]{9}
localestring
The language in which the customer wants the alerts and notifications from Orbipay. This is to be specified in the format, < ISO-639-1 language code >_< ISO ALPHA-2 Country Code >. For e.g., en_US indicates the language preference as US English, which is also the default value.
Min. Length: 5Max. Length: 5Reg. Exp.: ^[a-z]{2}_[A-Z]{2}$
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
customer_referencestring
The unique identifier in the client system for the customer.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
customer_account_referencestring
The unique identifier in the client system for the customer account.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
account_numberstring
The number or reference that a customer uses to identify the customer's account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}.]+
current_balancestring
The current balance on the customer's account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
current_statement_balancestring
The balance on the customer’s account with the biller as reported on the last statement.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
minimum_payment_duestring
The minimum payment amount, as specified by the biller, that needs to be made against the customer’s account.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
past_amount_duestring
The amount that is due from the past bills/statements on the customer’s account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
payment_due_datestring
The date by which the customer needs to clear the dues against the customer's account with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
statement_datestring
The date on which the biller generates the statement for the customer's account. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
idstring
Id is a unique identifier assigned to the customer account in Orbipay.
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
urlstring
This URL fetches the list of Customer accounts of a customer.
funding_accountsobject
urlstring
This URL fetches the list of Funding accounts of a customer.
paymentsobject
urlstring
This URL fetches the list of payments of a customer.
payment_setupsobject
urlstring
This URL fetches the list of payment setups of a customer.
Create Customer
CustomerAccounts customerAccounts = new CustomerAccounts();
List<CustomerAccount> list = new ArrayList<CustomerAccount>();
list.add(new CustomerAccount(accountHolderName, nickname, ... customFields));
customerAccounts.setList(list );
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
Customer createCustomer = new Customer(customerReference, ... customFields, gender)
.withAddress(new Address(addr1, ... country))
.withMemo(comments)
.forClient(clientKey)
.createdBy(requestorId, requestorType)
.videChannel(channel)
.withAccounts(customerAccounts)
.create(invocationContext);
The Create Customer API is used to register a customer with a biller in Orbipay. It is also mandatory to create a customer account for the customer. So, at least one customer account should be provided in order to register a customer. There is no limit on the number of accounts that can be associated with the customer. Either first_name or last_name is required to create a customer.
The customer created, with the id for the same in Orbipay.
Get Customer
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
Customer getCustomer = new Customer(id)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.forClient(clientKey)
.get( invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$customerRequest = new Customer(ID_CUSTOMER);
$response = $customerRequest
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);
Customer customer = new Customer(ID_CUSTOMER)
.ForClient(client_key)
.RetrievedBy(requestor, requestor_type)
.VideChannel(channel)
.Get(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.Customer(ID_CUSTOMER)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, customer) {
// asynchronously called
});
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.
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
first_name
last_name
middle_name
gender
date_of_birth
ssn
locale
email
home_phone
work_phone
mobile_phone
address
address_line1
address_line2
address_city
address_state
address_country
address_zip1
address_zip2
custom_fields
status
customer_accounts
customer_accounts[n]
account_holder_name
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
status
comments
Returns
The customer along with the list of customer accounts updated for the customer.
Retrieve Customers
// To retrieve the first page of results
MultiMap<CustomerFilter> customerFilterMap = new MultiMap<CustomerFilter>();
customerFilterMap.put(CustomerFilter.CUSTOMER_REFERENCE, "");
customerFilterMap.put(CustomerFilter.SSN, "");
customerFilterMap.put(CustomerFilter.EMAIL, "");
customerFilterMap.put(CustomerFilter.ACCOUNT_NUMBER, "");
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
Customers customers = new Customers()
.findBy(customerFilterMap)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.forClient(clientKey)
.get(invocationContext);
// To retrieve any page with results from start index or to end index
Customers customers = new Customers()
.findBy(queryId, fromIndex, toIndex, pageSize)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.forClient(clientKey)
.getPage(invocationContext);
// To retrieve the first page of results
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(CustomerFilter::EMAIL, email);
$filter->put(CustomerFilter::SSN, ssn);
$filter->put(CustomerFilter::CUSTOMER_REFERENCE, customer_reference);
$filter->put(CustomerFilter::PAGE_SIZE, page_size);
$filter->put(CustomerFilter::ACCOUNT_NUMBER, account_number);
$customersRequest = new Customers();
$response = $customersRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
// To retrieve any page with results from start index or to end index
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(CustomerFilter::QUERY_ID, query_id);
$filter->put(CustomerFilter::FROM_INDEX, from_index);
$filter->put(CustomerFilter::TO_INDEX, to_index);
$filter->put(CustomerFilter::PAGE_SIZE, page_size);
$customersRequest = new Customers();
$response = $customersRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
var Orbipay = require('orbipay-paymentsapi-client');
// To retrieve the first page of resultsvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.CustomerFilterEnum.email, email);
filter.put(Orbipay.CustomerFilterEnum.ssn, ssn);
filter.put(Orbipay.CustomerFilterEnum.customer_reference, customer_reference);
filter.put(Orbipay.CustomerFilterEnum.page_size, page_size);
filter.put(Orbipay.CustomerFilterEnum.account_number, account_number);
new Orbipay.Customers()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext,function(exception, customers) {
// asynchronously called
});
// To retrieve any page with results from start index or to end indexvar invocationContext = new InvocationContext(idempotent_request_key, secret, attributes);
var filter = new MultiMap();
filter.put(Orbipay.CustomerFilterEnum.query_id, query_id);
filter.put(Orbipay.CustomerFilterEnum.from_index, from_index);
filter.put(Orbipay.CustomerFilterEnum.to_index, to_index);
filter.put(Orbipay.CustomerFilterEnum.page_size, page_size);
new Orbipay.Customers()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, customers) {
// asynchronously called
});
This API is used to retrieve/lookup customers from Orbipay. Customers can be retrieved matching criteria that includes the customer_reference, the ssn, the email or the customer account number.
Customer Account Number of the customer to get details of.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}.]+
Returns
The list of customers matching the criteria provided, the total results count and the urls to get the next/previous pages.
Customer Account
This section outlines the API required to manage Customer Accounts.
The Customer Account Object
Central to Orbipay Payment API, a Customer Account is the virtual destination against which a Payment is made. A Customer Account has balance, inflow and outflow like any bank or card account. Examples of Customer Accounts include: Billing Accounts - against which bill payments can be made Vendor Accounts - against which invoice payments can be made
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
customer_account_referencestring
The unique identifier in the client system for the customer account.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
account_numberstring
The number or reference that a customer uses to identify the customer's account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}.]+
current_balancestring
The current balance on the customer's account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
current_statement_balancestring
The balance on the customer’s account with the biller as reported on the last statement.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
minimum_payment_duestring
The minimum payment amount, as specified by the biller, that needs to be made against the customer’s account.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
past_amount_duestring
The amount that is due from the past bills/statements on the customer’s account with the biller.
Min. Length: 1Max. Length: 18Reg. Exp.: (\+|\-)?([0-9]{1,14}(\.[0-9][0-9]?)?)
payment_due_datestring
The date by which the customer needs to clear the dues against the customer's account with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
statement_datestring
The date on which the biller generates the statement for the customer's account. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
idstring
Id is a unique identifier assigned to the customer account in Orbipay.
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
Retrieve Customer Accounts
// To retrieve the first page of results
MultiMap<CustomerAccountFilter> customerAccountFilterMap = new MultiMap<CustomerAccountFilter>();
customerAccountFilterMap.put(CustomerAccountFilter.ACCOUNT_NUMBER, "");
customerAccountFilterMap.put(CustomerAccountFilter.STATUS, "");
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
CustomerAccounts customerAccounts = new CustomerAccounts()
.findBy(customerAccountFilterMap)
.forCustomer(id)
.forClient(clientKey)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.get(invocationContext);
// To retrieve any page with results from start index or to end index
CustomerAccounts customerAccounts = new CustomerAccounts()
.findBy(queryId, fromIndex, toIndex, pageSize)
.forCustomer(id)
.forClient(clientKey)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.getPage(invocationContext);
// To retrieve the first page of results
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(CustomerAccountFilter::ACCOUNT_NUMBER, account_number);
$filter->put(CustomerAccountFilter::STATUS, status);
$filter->put(CustomerAccountFilter::PAGE_SIZE, page_size);
$customerAccountsRequest = new CustomerAccounts();
$response = $customerAccountsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
// To retrieve any page with results from start index or to end index
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(CustomerAccountFilter::QUERY_ID, query_id);
$filter->put(CustomerAccountFilter::FROM_INDEX, from_index);
$filter->put(CustomerAccountFilter::TO_INDEX, to_index);
$filter->put(CustomerAccountFilter::PAGE_SIZE, page_size);
$customerAccountsRequest = new CustomerAccounts();
$response = $customerAccountsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);
FilterData filter = new FilterData();
filter.SetAccountNumber(account_number);
filter.SetStatus(status); // status is type of CustomerAccountStatus or HashSet<CustomerAccountStatus>
filter.SetQueryId(query_id);
filter.SetFromIndex(from_index);
filter.SetToIndex(to_index);
filter.SetPageSize(page_size);
CustomerAccounts customerAccounts = new CustomerAccounts()
.FindBy(filter)
.ForCustomer(ID_CUSTOMER)
.ForClient(client_key)
.RetrievedBy(requestor, requestor_type)
.VideChannel(channel)
.Get(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
// To retrieve the first page of resultsvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.CustomerAccountFilterEnum.account_number, account_number);
filter.put(Orbipay.CustomerAccountFilterEnum.status, status);
filter.put(Orbipay.CustomerAccountFilterEnum.page_size, page_size);
new Orbipay.CustomerAccounts()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, customerAccounts) {
// asynchronously called
});
// To retrieve any page with results from start index or to end indexvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.CustomerAccountFilterEnum.query_id, query_id);
filter.put(Orbipay.CustomerAccountFilterEnum.from_index, from_index);
filter.put(Orbipay.CustomerAccountFilterEnum.to_index, to_index);
filter.put(Orbipay.CustomerAccountFilterEnum.page_size, page_size);
new Orbipay.CustomerAccounts()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, customerAccounts) {
// asynchronously called
});
invocation_context = InvocationContext(secret, idempotent_request_key,
x_opay_headers)
response = CustomerAccounts()
.find_by(account_number='', status=[], page_size='')
.for_customer(id_customer)
.for_client(client_key)
.vide_channel(channel)
.retrieved_by(requestor, requestor_type)
.get(invocation_context)
# To retrieve any page with results from start index or to end index
response = CustomerAccounts()
.find_by(page_size='', query_id='', from_index='', to_index='')
.for_customer(id_customer)
.for_client(client_key)
.retrieved_by(requestor, requestor_type)
.vide_channel(channel)
.get_page(invocation_context)
invocation_context = InvocationContext.new(secret:"", idempotent_request_key:"", x_opay_headers:"")
response = CustomerAccounts.new
.find_by(account_number:"", status: [], page_size:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get(invocation_context: invocation_context)
# To retrieve any page with results from start index or to end index
response = CustomerAccounts.new
.find_by(page_size:"", query_id:"", from_index:"", to_index:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get_page(invocation_context: invocation_context)
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 2Max. Length: 10Reg. Exp.: [a-zA-Z0-9 -]{2,10}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
aba_routing_numberstring
The ABA/Routing number for the bank account.
Min. Length: 9Max. Length: 9Reg. Exp.: [0-9]{9}
issuer_namestring
The name of the authority that has issued the account. This is relevant only in the case of bank accounts.
The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by Orbipay. This defaults to USD.
Min. Length: 3Max. Length: 3Reg. Exp.: [A-Z]{3}
expiry_datestring
The expiry date for the card. This is to be in the format MM/yy. Only applicable for cards accounts.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{2}/[0-9]{2}
account_holder_typestring
The type of ownership for the funding account. This is applicable only in the case of bank accounts and it is defaults to personal.
Valid Values: personal, business
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account. For e.g., a savings account, a checking account.
Id is a unique identifier assigned to the funding account in Orbipay. A new Id is generated for the funding account when the account number is updated.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
urlstring
This URL fetches the Account details.
ach_eligible_flagstring
Indicates if the funding account can be debited vide ACH, in case the funding account is a Demand Deposit Account (DDA).
Valid Values: yes, no
atm_eligible_flagstring
Indicates if the funding account can be debited vide the ATM Rail network, in case the funding account is a Debit Card.
Valid Values: yes, no
card_cvv_numberstring
This is never returned by Orbipay. This needs to be passed to Orbipay when adding or editing a card funding account.
This API is used to add a funding account for the customer. The funding account is available for servicing all the customer accounts the customer holds. An exhaustive set of account types are supported as funding accounts as indicated in the field account_subtype. ABA routing number and account sub-type are mandatory for bank accounts. Expiry date, address fields and Card CVV are required for card accounts.
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
account_holder_namerequired
nickname
address
address_line1
address_line2
address_city
address_state
address_country
address_zip1
address_zip2
account_numberrequired
aba_routing_number
expiry_date
account_holder_type
custom_fields
account_subtype
card_cvv_number
comments
Returns
The funding account created, with the id for the same in Orbipay.
Retrieve Funding Accounts
// To retrieve the first page of results
MultiMap<FundingAccountFilter> fundingAccountFilterMap = new MultiMap<FundingAccountFilter>();
fundingAccountFilterMap.put(FundingAccountFilter.ACCOUNT_NUMBER, "");
fundingAccountFilterMap.put(FundingAccountFilter.STATUS, "");
fundingAccountFilterMap.put(FundingAccountFilter.ABA_ROUTING_NUMBER, "");
fundingAccountFilterMap.put(FundingAccountFilter.ACCOUNT_TYPE, "");
fundingAccountFilterMap.put(FundingAccountFilter.ACCOUNT_SUBTYPE, "");
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
FundingAccounts fundingAccounts = new FundingAccounts()
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.findBy(fundingAccountFilterMap)
.forClient(clientKey)
.forCustomer(id)
.get(invocationContext);
// To retrieve any page with results from start index or to end index
FundingAccounts fundingAccounts = new FundingAccounts()
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.findBy(queryId, fromIndex, toIndex, pageSize)
.forClient(clientKey)
.forCustomer(id)
.getPage(invocationContext);
// To retrieve the first page of results
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(FundingAccountFilter::ACCOUNT_NUMBER, account_number);
$filter->put(FundingAccountFilter::ABA_ROUTING_NUMBER, aba_routing_number);
$filter->put(FundingAccountFilter::STATUS, status);
$filter->put(FundingAccountFilter::ACCOUNT_SUBTYPE, account_subtype);
$filter->put(FundingAccountFilter::ACCOUNT_TYPE, account_type);
$filter->put(FundingAccountFilter::PAGE_SIZE, page_size);
$fundingAccountsRequest = new FundingAccounts();
$response = $fundingAccountsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
// To retrieve any page with results from start index or to end index
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(FundingAccountFilter::QUERY_ID, query_id);
$filter->put(FundingAccountFilter::FROM_INDEX, from_index);
$filter->put(FundingAccountFilter::TO_INDEX, to_index);
$filter->put(FundingAccountFilter::PAGE_SIZE, page_size);
$fundingAccountsRequest = new FundingAccounts();
$response = $fundingAccountsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
FilterData filter = new FilterData();
filter.SetAccountNumber(account_number);
filter.SetStatus(status); // status is type of FundingAccountStatus or HashSet<FundingAccountStatus>
filter.SetAbaRoutingNumber(aba_routing_number);
filter.SetAccountType(account_type); // account_type is type of HashSet<FundingAccountType>
filter.SetAccountSubtype(account_subtype); // account_subtype is type of FundingAccountSubtype
filter.SetQueryId(query_id);
filter.SetFromIndex(from_index);
filter.SetToIndex(to_index);
filter.SetPageSize(page_size);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);
FundingAccounts fundingAccounts = new FundingAccounts()
.RetrievedBy(requestor, requestor_type)
.VideChannel(channel)
.FindBy(filter)
.ForClient(client_key)
.ForCustomer(ID_CUSTOMER)
.Get(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
// To retrieve the first page of resultsvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.FundingAccountFilterEnum.account_number, account_number);
filter.put(Orbipay.FundingAccountFilterEnum.aba_routing_number, aba_routing_number);
filter.put(Orbipay.FundingAccountFilterEnum.status, status);
filter.put(Orbipay.FundingAccountFilterEnum.account_subtype, account_subtype);
filter.put(Orbipay.FundingAccountFilterEnum.account_type, account_type);
filter.put(Orbipay.FundingAccountFilterEnum.page_size, page_size);
new Orbipay.FundingAccounts()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext);
// To retrieve any page with results from start index or to end indexvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.FundingAccountFilterEnum.query_id, query_id);
filter.put(Orbipay.FundingAccountFilterEnum.from_index, from_index);
filter.put(Orbipay.FundingAccountFilterEnum.to_index, to_index);
filter.put(Orbipay.FundingAccountFilterEnum.page_size, page_size);
new Orbipay.FundingAccounts()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, fundingAccount) {
// asynchronously called
});
invocation_context = InvocationContext(secret, idempotent_request_key,
x_opay_headers)
response = FundingAccounts()
.find_by(aba_routing_number='', account_type=[],
account_subtype='', account_number='', status=[], page_size='')
.for_customer(id_customer)
.for_client(client_key)
.retrieved_by(requestor, requestor_type)
.vide_channel(channel)
.get(invocation_context)
# To retrieve any page with results from start index or to end index
response = FundingAccounts()
.find_by(page_size='', query_id='', from_index='', to_index='')
.for_customer(id_customer)
.for_client(client_key)
.vide_channel(channel)
.retrieved_by(requestor, requestor_type)
.get_page(invocation_context)
invocation_context = InvocationContext.new(secret:"", idempotent_request_key:"", x_opay_headers:"")
response = FundingAccounts.new
.find_by(aba_routing_number:"", account_type: [],
account_subtype:"", account_number:"", status: [], page_size:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get(invocation_context: invocation_context)
# To retrieve any page with results from start index or to end index
response = FundingAccounts.new
.find_by(page_size:"", query_id:"", from_index:"", to_index:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get_page(invocation_context: invocation_context)
POST /customers/{ID_CUSTOMER}/fundingaccounts/lists
This API is used to retrieve all the funding accounts associated with a customer. Accounts can be filtered using the account number, the ABA routing number (for bank accounts), the account status, account type, account sub-type and others mentioned below.
The type of the funding account. This can take multiple values in the format key=value1&key=value2....
Valid Values: bank, debit_card, credit_card
account_subtypestringin: formData
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
PUT /customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}
The API is used to edit the funding account details. The type of the funding account cannot be changed. In other words, a card account cannot be changed to a bank account and vice versa. The sub-type of a bank account can be changed. For e.g., a saving account can be updated to a money market account. However, the sub-type cannot be updated for a card account. CVV is mandatory to make any change to a card account. The Id of the funding account gets updated to a new value if the account number is updated. Editing a funding account updates the account information on all pending payments made using that account but does not change the details on payments that have been completed.
The Delete Funding Account API is used to delete the funding account of a customer. All pending payments made with that account are cancelled upon deletion of the funding account.
The unique identifier assigned by Orbipay to the Funding Account.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
ID_CUSTOMERstringin: pathrequired
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
comments
Returns
The id of the funding account being deleted and the status of the deletion.
Payment
This section outlines the API required to enable customers to manage their payments.
The Payment Object
A Payment is always made using a Funding Account. Payments are initiated by a Customer or on behalf of a Customer (i.e., by a customer service agent).Payments follow a "good funds" model, which means the customer must ensure the funds required to make a payment are available in the funding account before initiating the transaction. Payments can be scheduled for the same day or a later date. The actual settlement of the funds will depend on the payment method used (i.e., credit card, ACH etc.) and other factors.
The unique identifier assigned by Orbipay to the payment.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
urlstring
This URL fetches the details of payment.
feeobject
fee_typestring
The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.
Valid Values: add_to_principal, bill_separately
fee_amountstring
The fee amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
idstring
The unique identifier assigned by Orbipay to the fee. In case of split fee.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of fee as a payment resource. In case of split fee.
The confirmation number or reference provided to the customer for the payment.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
currency_code3dstring
The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by Orbipay. This defaults to USD.
Min. Length: 3Max. Length: 3Reg. Exp.: [A-Z]{3}
amountstring
The amount being paid. In case the payment_amount_type is 'discounted_amount', 'penalty_amount' or 'other', the amount needs to be specified. In other cases, this is derived from the payment_amount_type.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
card_cvv_numberstring
This is never returned by Orbipay. This needs to be passed to Orbipay when making or editing a payment with a card funding account.
Min. Length: 3Max. Length: 4Reg. Exp.: [0-9]{3,4}
payment_datestring
The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_schedule_typestring
The schedule type for the payment. This defaults to one_time_payment.
The date on which the biller wants the payment to be settled. It must be in ISO8601 full-date format, namely, YYYY-MM-DD. This is applicable only if the client has opted for it.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_amount_typestring
The type of amount, as per the bill/statement, that is being paid. The payment amount is derived from the amount type selected for the payment. This defaults to other.
Valid Values: current_balance, minimum_payment_due, past_payment_due, statement_balance, discounted_amount, penalty_amount, other
payment_referencestring
The unique identifier in the client system for the payment.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
expected_payment_settlement_datestring
The date on which the payment is expected to be settled with the biller. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_entry_datestring
The date on which the payment is captured in Orbipay. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_return_datestring
The date on which the ACH returns is received by Orbipay.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
return_codestring
The ACH return code or the chargeback code received from Visa/Mastercard, in the event of returned payments.
Max. Length: 10Reg. Exp.: [a-z0-9]{0,10}
customerobject
The customer making the payment
idstring
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
The URL that can be used to fetch the details of the customer.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
funding_accountobject
The customer's funding account with which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the Account details.
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
account_typestring
The type of the funding account.
Valid Values: bank, debit_card, credit_card
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
The customer account against which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the Account details.
Retrieve Payments
// To retrieve the first page of results
MultiMap<PaymentFilter> paymentFilterMap = new MultiMap<PaymentFilter>();
paymentFilterMap.put(PaymentFilter.ID_CUSTOMER, "");
paymentFilterMap.put(PaymentFilter.ID_FUNDING_ACCOUNT, "");
paymentFilterMap.put(PaymentFilter.ID_CUSTOMER_ACCOUNT, "");
paymentFilterMap.put(PaymentFilter.CONFIRMATION_NUMBER, "");
paymentFilterMap.put(PaymentFilter.STATUS, "");
paymentFilterMap.put(PaymentFilter.PAYMENT_SCHEDULE_TYPE, "");
paymentFilterMap.put(PaymentFilter.FROM_DATE, "");
paymentFilterMap.put(PaymentFilter.TO_DATE, "");
paymentFilterMap.put(PaymentFilter.PAGE_SIZE, "");
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
Payments payments = new Payments()
.findBy(paymentFilterMap)
.forClient(clientKey)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.get(invocationContext);
// To retrieve any page with results from start index or to end index
Payments payments = new Payments()
.findBy(queryId, fromIndex, toIndex, pageSize)
.forCustomer(id)
.forClient(clientKey)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.getPage(invocationContext);
// To retrieve the first page of results
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(PaymentFilter::ID_CUSTOMER, id_customer);
$filter->put(PaymentFilter::ID_FUNDING_ACCOUNT, id_funding_account);
$filter->put(PaymentFilter::ID_CUSTOMER_ACCOUNT, id_customer_account);
$filter->put(PaymentFilter::CONFIRMATION_NUMBER, confirmation_number);
$filter->put(PaymentFilter::STATUS, status);
$filter->put(PaymentFilter::PAYMENT_SCHEDULE_TYPE, payment_schedule_type);
$filter->put(PaymentFilter::FROM_DATE, from_date);
$filter->put(PaymentFilter::TO_DATE, to_date);
$filter->put(PaymentFilter::PAGE_SIZE, page_size);
$paymentsRequest = new Payments();
$response = $paymentsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
// To retrieve any page with results from start index or to end index
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(PaymentFilter::QUERY_ID, query_id);
$filter->put(PaymentFilter::FROM_INDEX, from_index);
$filter->put(PaymentFilter::TO_INDEX, to_index);
$filter->put(PaymentFilter::PAGE_SIZE, page_size);
$paymentsRequest = new Payments();
$response = $paymentsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);
FilterData filter = new FilterData();
filter.SetIdCustomer(id_customer);
filter.SetIdCustomerAccount(id_customer_account);
filter.SetIdFundingAccount(id_funding_account);
filter.SetConfirmationNumber(confirmation_number);
filter.SetStatus(status); // status is type of PaymentStatus or HashSet<PaymentStatus>
filter.SetPaymentScheduleType(payment_schedule_type);
filter.SetFromDate(from_date);
filter.SetToDate(to_date);
filter.SetQueryId(query_id);
filter.SetFromIndex(from_index);
filter.SetToIndex(to_index);
filter.SetPageSize(page_size);
Payments payments = new Payments()
.FindBy(filter)
.ForClient(client_key)
.RetrievedBy(requestor, requestor_type)
.VideChannel(channel)
.Get(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
// To retrieve the first page of resultsvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.PaymentFilterEnum.id_customer, id_customer);
filter.put(Orbipay.PaymentFilterEnum.id_funding_account, id_funding_account);
filter.put(Orbipay.PaymentFilterEnum.id_customer_account, id_customer_account);
filter.put(Orbipay.PaymentFilterEnum.confirmation_number, confirmation_number);
filter.put(Orbipay.PaymentFilterEnum.status, status);
filter.put(Orbipay.PaymentFilterEnum.payment_schedule_type, payment_schedule_type);
filter.put(Orbipay.PaymentFilterEnum.from_date, from_date);
filter.put(Orbipay.PaymentFilterEnum.to_date, to_date);
filter.put(Orbipay.PaymentFilterEnum.page_size, page_size);
new Orbipay.Payments()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, payments) {
// asynchronously called
});
// To retrieve any page with results from start index or to end indexvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.PaymentFilterEnum.query_id, query_id);
filter.put(Orbipay.PaymentFilterEnum.from_index, from_index);
filter.put(Orbipay.PaymentFilterEnum.to_index, to_index);
filter.put(Orbipay.PaymentFilterEnum.page_size, page_size);
new Orbipay.Payments()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, payments) {
// asynchronously called
});
invocation_context = InvocationContext(secret, idempotent_request_key,
x_opay_headers)
response = Payments()
.find_by(id_funding_account='', id_customer_account='', confirmation_number='',
payment_schedule_type=[], from_date='', to_date='', status=[], page_size='')
.for_customer(id_customer)
.for_client(client_key)
.vide_channel(channel)
.retrieved_by(requestor, requestor_type)
.get(invocation_context)
# To retrieve any page with results from start index or to end index
response = Payments()
.find_by(page_size='', query_id='', from_index='', to_index='')
.for_customer(id_customer)
.for_client(client_key)
.retrieved_by(requestor, requestor_type)
.vide_channel(channel)
.get(invocation_context)
invocation_context = InvocationContext.new(secret:"", idempotent_request_key:"", x_opay_headers:"")
response = Payments.new
.find_by(id_funding_account:"", id_customer_account:"", confirmation_number:"",
payment_schedule_type: [], from_date:"", to_date:"", status: [], page_size:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get(invocation_context: invocation_context)
# To retrieve any page with results from start index or to end index
response = Payments.new
.find_by(page_size:"", query_id:"", from_index:"", to_index:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get(invocation_context: invocation_context)
The API is used to retrieve the payments made by a customer. Payments can be filtered using the confirmation number, customer account, funding account, status and payment schedule type, by date range and others mentioned below. If no dates are provided for retrieval, payments in the last six months and all the payments scheduled for a future date are returned. In case a payment has failed due to ACH returns, then the payment return date and the return code will be available in the response.
If the requestor type is customer then the id_customer request parameter is mandatory.
Response content type: application/json
Request Parameters
id_customerstringin: query
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_funding_accountstringin: query
The unique identifier assigned by Orbipay to the funding account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_customer_accountstringin: query
The unique identifier assigned by Orbipay to the customer account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
confirmation_numberstringin: query
The confirmation number or reference provided to the customer for the successful payment.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
statusstringin: query
The status of the payment. This can take multiple values in the format key=value1&key=value2....
The API is used to make payments to service a customer account. Client systems can provide the unique identifier for the payment in their system as payment_reference.
Fee amount and fee type are conditional and should be provided if the details of the fee to be charged are maintained in the client system. The fee types that are supported in Orbipay are add_to_principal and bill_separately. Alternatively, the fee information can be setup in Orbipay, in which case, these fields are ignored. If fee information is setup in the system, the details of the fee are returned in the response.
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.Payment(ID_PAYMENT);
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, payment) {
// asynchronously called
});
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.Payment(ID_PAYMENT);
.forClient(client_key)
.deleteBy(requestor, requestor_type)
.videChannel(channel)
.delete(invocationContext, function(exception, payment) {
// asynchronously called
});
The unique identifier assigned by Orbipay to the payment.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
ID_CUSTOMERstringin: pathrequired
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
comments
Returns
The id of the payment being deleted and the status of the deletion.
Payment Setup
This section outlines the API required to enable customers to set up and manage payment setups for their Customer Accounts.
The Payment Setup Object
Payments can be scheduled on a recurring basis – monthly, quarterly, bi-annually, or annually. Customers can designate a fixed amount to pay for each billing cycle, or set the payment amount to automatically adjust to the current balance due based on a feed sent to Orbipay (this feature requires additional setup). Please contact support@billerpayments.com for more details.
The unique identifier assigned by Orbipay to the payment setup.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
urlstring
This URL fetches the details of payment setup.
feeobject
fee_typestring
The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.
Valid Values: add_to_principal, bill_separately
fee_amountstring
The fee amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
idstring
The unique identifier assigned by Orbipay to the fee. In case of split fee.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of fee as a payment resource. In case of split fee.
The confirmation number or reference provided to the customer for the payment setup.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
currency_code3dstring
The three-letter currency code in the ISO4217 format, in uppercase, for the card account. It must be a currency supported by Orbipay. This defaults to USD.
Min. Length: 3Max. Length: 3Reg. Exp.: [A-Z]{3}
amountstring
The amount being paid. In case the payment_amount_type is 'discounted_amount', 'penalty_amount' or 'other', the amount needs to be specified. In other cases, this is derived from the payment_amount_type.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
card_cvv_numberstring
This is never returned by Orbipay. This needs to be passed to Orbipay when making or editing a payment setup with a card funding account.
Min. Length: 3Max. Length: 4Reg. Exp.: [0-9]{3,4}
next_payment_datestring
The date on which the payment is scheduled to be made. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_setup_referencestring
The unique identifier in the client system for the payment setup.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
payment_scheduleobject
The schedule for the payments that are created as part of a payment setup like recurring payment or autopay.
payment_recurring_typestring
The frequency of the payments created as part of a payment setup. This is applicable only for recurring payment setup, in which case it is mandatory.
The maximum number of payments that can be created as part of a recurring payment setup. This cannot be specified for autopay setups.
Min. Length: 1Max. Length: 3Reg. Exp.: [0-9]+
payment_amount_typestring
The amount type that is used to set the amount for payments created as part of a recurring payment or autopay setup. In the case of a recurring payment setup, the payment amount can be specified by the customer. In that case, the payment_amount_type should not be sent as it would default to 'other'. In the case of an autopay setup, the payment amount type is mandatory and it cannot be specified as 'other'. In this case, the payment amount should not be sent.
Valid Values: current_balance, minimum_payment_due, past_payment_due, statement_balance, discounted_amount, penalty_amount, other
payment_start_datestring
The date on which the first payment will be drafted as part of a recurring payment setup. This is to be specified in the ISO8601 full-date format, namely, YYYY-MM-DD. This is mandatory for recurring payment setup. This cannot be specified for autopay setups.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_end_datestring
The date by which the last payment will be drafted as part of a recurring payment setup. This is to be specified in the ISO8601 full-date format, namely, YYYY-MM-DD. This cannot be specified for autopay setups.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
payment_limit_amountstring
The upper limit for the payment amount in the case of recurring or autopay payments. Any amount above the limit will not be paid automatically as part of recurring payments and autopay.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
payment_plan_idstring
The reference to the payment plan, offered by the biller, that is used to set up the recurring payment. The list of payment plans offered is published as part of the biller set-up.
Max. Length: 9Reg. Exp.: [0-9]{0,9}
payment_defer_daysstring
The number of days from the bill due date that the customer wishes to delay the autopay payment by. By default an autopay payment is drafted on the bill due date.
Min. Length: 1Max. Length: 2Reg. Exp.: [0-9]+
payment_setup_entry_datestring
The date on which the payment setup is captured in Orbipay. It must be in ISO8601 full-date format, namely, YYYY-MM-DD.
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
customerobject
The customer making the payment
idstring
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
The URL that can be used to fetch the details of the customer.
Min. Length: 2Max. Length: 2Reg. Exp.: [a-zA-Z]{2}
address_countrystring
The 3 letter country code as per ISO 3166-1 (alpha-3).
Min. Length: 3Max. Length: 3Reg. Exp.: [a-zA-Z]{3}
address_zip1string
The first part of the postal code for the address as per the system followed in the appropriate country where it belongs. In the case of US, it's the 5 digit postal code used by the US Postal Service.
Min. Length: 5Max. Length: 5Reg. Exp.: [0-9]{5}
address_zip2string
The 4 digit add-on code used, in addition to the 5 digit postal code, by the US Postal Service.This is not applicable and will be ignored in the case of non-US addresses.
Min. Length: 4Max. Length: 4Reg. Exp.: [0-9]{4}
funding_accountobject
The customer's funding account with which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the Account details.
account_numberstring
The number or reference that a customer uses to identify the funding account.
Min. Length: 4Max. Length: 32Reg. Exp.: [a-zA-Z0-9]+
account_typestring
The type of the funding account.
Valid Values: bank, debit_card, credit_card
account_subtypestring
The sub type of the funding account. This is derived by Orbipay in the case of card funding accounts. It needs to be passed when adding or editing a DDA/bank account.
The customer account against which the payment is being made.
idstring
Id is a unique identifier assigned to the account in Orbipay.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the Account details.
Retrieve Payment Setups
// To retrieve the first page of results
MultiMap<PaymentSetupFilter> paymentSetupFilterMap = new MultiMap<PaymentSetupFilter>();
paymentSetupFilterMap.put(PaymentSetupFilter.ID_CUSTOMER, "");
paymentSetupFilterMap.put(PaymentSetupFilter.ID_FUNDING_ACCOUNT, "");
paymentSetupFilterMap.put(PaymentSetupFilter.ID_CUSTOMER_ACCOUNT, "");
paymentSetupFilterMap.put(PaymentSetupFilter.CONFIRMATION_NUMBER, "");
paymentSetupFilterMap.put(PaymentSetupFilter.STATUS, "");
paymentSetupFilterMap.put(PaymentSetupFilter.PAYMENT_SETUP_SCHEDULE_TYPE, "");
paymentSetupFilterMap.put(PaymentSetupFilter.FROM_DATE, "");
paymentSetupFilterMap.put(PaymentSetupFilter.TO_DATE, "");
paymentSetupFilterMap.put(PaymentSetupFilter.PAGE_SIZE, "");
InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);
PaymentSetups retrievePaymentsSetup = new PaymentSetups()
.findBy(paymentSetupFilterMap)
.forClient(clientKey)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.get(invocationContext);
// To retrieve any page with results from start index or to end index
PaymentSetups retrievePaymentsSetup = new PaymentSetups()
.findBy(queryId, fromIndex, toIndex, pageSize)
.forCustomer(id)
.forClient(clientKey)
.retrievedBy(requestorId, requestorType)
.videChannel(channel)
.getPage(invocationContext);
// To retrieve the first page of results
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(PaymentSetupFilter::ID_CUSTOMER, id_customer);
$filter->put(PaymentSetupFilter::ID_FUNDING_ACCOUNT, id_funding_account);
$filter->put(PaymentSetupFilter::ID_CUSTOMER_ACCOUNT, id_customer_account);
$filter->put(PaymentSetupFilter::CONFIRMATION_NUMBER, confirmation_number);
$filter->put(PaymentSetupFilter::STATUS, status);
$filter->put(PaymentSetupFilter::PAYMENT_SETUP_SCHEDULE_TYPE, payment_setup_schedule_type);
$filter->put(PaymentSetupFilter::FROM_DATE, from_date);
$filter->put(PaymentSetupFilter::TO_DATE, to_date);
$filter->put(PaymentSetupFilter::PAGE_SIZE, page_size);
$paymentSetupsRequest = new PaymentSetups();
$response = $paymentSetupsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
// To retrieve any page with results from start index or to end index
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$filter = new MultiMap();
$filter->put(PaymentSetupFilter::QUERY_ID, query_id);
$filter->put(PaymentSetupFilter::FROM_INDEX, from_index);
$filter->put(PaymentSetupFilter::TO_INDEX, to_index);
$filter->put(PaymentSetupFilter::PAGE_SIZE, page_size);
$paymentSetupsRequest = new PaymentSetups();
$response = $paymentSetupsRequest
->findBy($filter)
->forClient(client_key)
->retrievedBy(requestor, requestor_type)
->videChannel(channel)
->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);
FilterData filter = new FilterData();
filter.SetIdCustomer(id_customer);
filter.SetIdCustomerAccount(id_customer_account);
filter.SetIdFundingAccount(id_funding_account);
filter.SetConfirmationNumber(confirmation_number);
filter.SetStatus(status); // status is type of PaymentSetupStatus or HashSet<PaymentSetupStatus>
filter.SetPaymentSetupScheduleType(payment_setup_schedule_type);
filter.SetFromDate(from_date);
filter.SetToDate(to_date);
filter.SetQueryId(query_id);
filter.SetFromIndex(from_index);
filter.SetToIndex(to_index);
filter.SetPageSize(page_size);
PaymentSetups paymentSetups = new PaymentSetups()
.FindBy(filter)
.ForClient(client_key)
.RetrievedBy(requestor, requestor_type)
.VideChannel(channel)
.Get(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
// To retrieve the first page of resultsvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.PaymentSetupFilterEnum.id_customer, id_customer);
filter.put(Orbipay.PaymentSetupFilterEnum.id_funding_account, id_funding_account);
filter.put(Orbipay.PaymentSetupFilterEnum.id_customer_account, id_customer_account);
filter.put(Orbipay.PaymentSetupFilterEnum.confirmation_number, confirmation_number);
filter.put(Orbipay.PaymentSetupFilterEnum.status, status);
filter.put(Orbipay.PaymentSetupFilterEnum.payment_setup_schedule_type, payment_setup_schedule_type);
filter.put(Orbipay.PaymentSetupFilterEnum.from_date, from_date);
filter.put(Orbipay.PaymentSetupFilterEnum.to_date, to_date);
filter.put(Orbipay.PaymentSetupFilterEnum.page_size, page_size);
new Orbipay.PaymentSetups()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, paymentsetups) {
// asynchronously called
});
// To retrieve any page with results from start index or to end indexvar invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
var filter = new Orbipay.MultiMap();
filter.put(Orbipay.PaymentSetupFilterEnum.query_id, query_id);
filter.put(Orbipay.PaymentSetupFilterEnum.from_index, from_index);
filter.put(Orbipay.PaymentSetupFilterEnum.to_index, to_index);
filter.put(Orbipay.PaymentSetupFilterEnum.page_size, page_size);
new Orbipay.PaymentSetups()
.findBy(filter)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, paymentsetups) {
// asynchronously called
});
invocation_context = InvocationContext(secret, idempotent_request_key,
x_opay_headers)
response = PaymentSetups()
.find_by( id_funding_account='', id_customer_account='', confirmation_number='',
payment_setup_schedule_type=[], from_date='', to_date='', status=[], page_size='')
.for_customer(id_customer)
.for_client(client_key)
.vide_channel(channel)
.retrieved_by(requestor, requestor_type)
.get(invocation_context)
# To retrieve any page with results from start index or to end index
response = PaymentSetups()
.find_by(page_size='', query_id='', from_index='', to_index='')
.for_customer(id_customer)
.for_client(client_key)
.vide_channel(channel)
.retrieved_by(requestor, requestor_type)
.get(invocation_context)
invocation_context = InvocationContext.new(secret:"", idempotent_request_key:"", x_opay_headers:"")
response = PaymentSetups.new
.find_by(id_funding_account:"", id_customer_account:"", confirmation_number:"",
payment_setup_schedule_type: [], from_date:"", to_date:"", status: [], page_size:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get(invocation_context: invocation_context)
# To retrieve any page with results from start index or to end index
response = PaymentSetups.new
.find_by(page_size:"", query_id:"", from_index:"", to_index:"")
.for_customer(id_customer:"")
.for_client(client_key:"")
.vide_channel(channel:"")
.retrieved_by(requestor:"", requestor_type:"")
.get(invocation_context: invocation_context)
The API is used to retrieve the recurring and autopay payments setup made against a customer account. The setup can be filtered using the confirmation number, customer account, funding account, status and payment setup schedule type, by date range and others mentioned below. If no dates are provided for retrieval, recurring payments set up in the last six months and all the ones in future are returned. If the requestor type is customer then the id_customer request parameter is mandatory.
Response content type: application/json
Request Parameters
id_customerstringin: query
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_funding_accountstringin: query
The unique identifier assigned by Orbipay to the funding account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
id_customer_accountstringin: query
The unique identifier assigned by Orbipay to the customer account
Max. Length: 20Reg. Exp.: [0-9]{1,20}
confirmation_numberstringin: query
The confirmation number or reference provided to the customer for the successful payment.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
statusstringin: query
The status of the payment. This can take multiple values in the format key=value1&key=value2....
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.PaymentSetup(ID_PAYMENT_SETUP)
.forClient(client_key)
.retrievedBy(requestor, requestor_type)
.videChannel(channel)
.get(invocationContext, function(exception, paymentsetup) {
// asynchronously called
});
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.PaymentSetup(ID_PAYMENT_SETUP)
.forClient(client_key)
.deletedBy(requestor, requestor_type)
.videChannel(channel)
.delete(invocationContext, function(exception, paymentsetup) {
// asynchronously called
});
The API is used to delete or cancel a recurring payment setup. Cancelling a payment setup will also cancel all the pending and future payments under the setup.
The unique identifier assigned by Orbipay to the payment setup.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
ID_CUSTOMERstringin: pathrequired
The unique identifier assigned by Orbipay to the customer.
Max. Length: 20Reg. Exp.: [0-9]{1,20}
Request Object
Attributes
comments
Returns
The id of the recurring payment setup being deleted and the status of the deletion.
Refund
This section outlines the API required to enable customers to get refunded for the payments made via Orbipay.
The Refund Object
Payments made using Orbipay can be fully or partially refunded as one or more refund transactions. Credits are posted to the funding source associated with the payment being refunded. Both ACH and card payment methods are supported for refunds. Only payments in the 'processed' status can be refunded.
The unique identifier in the client system for the refund.
Max. Length: 50Reg. Exp.: [0-9a-zA-Z._-]{0,50}
idstring
The unique identifier assigned by Orbipay to the refund.
Max. Length: 20Reg. Exp.: [0-9]{0,20}
urlstring
This URL fetches the details of refund.
refund_typestring
The portion of the payment amount that is to be or has been refunded. The original payment can be refunded fully including the amount and the fee components, or partially, for just the amount or the fee component. Refund can also be initiated for an arbitrary amount limited by the original payment amount.
Valid Values: payment_and_fee, payment_only, fee_only, other
refund_amountstring
The refund amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
fee_refundobject
fee_refund_amountstring
The refunded fee amount upto 2 decimal places.
Min. Length: 1Max. Length: 17Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$
fee_typestring
The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.
The confirmation number or reference provided to the customer for the refund.
Max. Length: 30Reg. Exp.: [a-zA-Z0-9]+
expected_refund_settlement_datestring
The date by which the credits would be posted to the original funding account. ISO8601 full-date format, YYYY-MM-DD
Min. Length: 10Max. Length: 10Date Format: YYYY-MM-DD
custom_fieldsmap
The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.
POST /customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}/refunds
This API is used to initiate a refund. Any payment made using Orbipay can be refunded. Customer cannot initiate a refund request. In other words, the Create Refund request will fail if the associated requestor_type is customer. The refund types that are supported in Orbipay are payment_and_fee, payment_only, fee_only, other. The amount is optional and needs to be specified only if it's a partial refund i.e., the refund type is other.
"first_name": "Michael", "last_name": "Smith", "middle_name": "S", "gender": "male", "date_of_birth": "1980-11-11", "ssn": "123456789", "locale": "en_US", "email": "userid@example.com", "home_phone": "1234567890", "work_phone": "1234567890", "mobile_phone": "1234567890", "address": {