NAV
Java Python PHP Ruby Node .NET
COMMON TOPICS

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
GET /payments/v1/payments?page_size=10&id_customer =123456&from_date=      &   status   =   scheduled    &status=processing HTTP/1.1
Host: api.orbipay.com
Accept: application/json
product: orbipay_payments
idempotent_request_key: 8b528a6c954a4a92a8555dd3f1862e8d
client_key: 987654321
channel: Agent
timestamp: 2018-06-11 15:29:51.412+0530
requestor_type: client_agent
requestor: 123456
Authorization: OPAY1-HMAC-SHA256 Credential=987654321,Signature=f42YQ3U2DAvYbkHFf07NOmjKdvRDtXxc2H7AUgVLm+s=
Signature Calculation
method() = "GET"
path() = "/payments/v1/payments"
queryString() = "id_customer=123456&page_size=10&status=processing&status=scheduled"
headers() = "channel=Agent&client_key=987654321&idempotent_request_key=8b528a6c954a4a92a8555dd3f1862e8d&product=orbipay_payments&requestor=123456&requestor_type=client_agent&timestamp=2018-06-11 15:29:51.412+0530"
payload() = ""
input = "GET:/payments/v1/payments:id_customer=123456&page_size=10&status=processing&status=scheduled:channel=Agent&client_key=987654321&idempotent_request_key=8b528a6c954a4a92a8555dd3f1862e8d&product=orbipay_payments&requestor=123456&requestor_type=client_agent&timestamp=2018-06-11 15:29:51.412+0530:"
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.

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: 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 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.
  • Valid Values: customer, client_agent, 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 "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: 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.

  • 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 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.
  • Valid Values: customer, client_agent, 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 "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: 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.

Payments API

API Endpoints Production: https://api.orbipay.com/payments/v1 Sandbox: 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.

Object JSON

{
    "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": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "custom_fields": { }, 
    "customer_reference": "IkdphX8DsEtOeOI_73823121", 
    "id": "123456789", 
    "status": "active", 
    "url": "/customers/{ID_CUSTOMER}", 
    "customer_accounts": {
        "list": [
            {
                "account_holder_name": "Michael Smith", 
                "nickname": "Smith", 
                "address": {
                    "address_line1": "1551 South Washington Ave", 
                    "address_line2": "Suite 130 Piscataway", 
                    "address_city": "Piscataway", 
                    "address_state": "NJ", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }, 
                "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
                "account_number": "478E4385e604B685", 
                "current_balance": "110.05", 
                "current_statement_balance": "100.05", 
                "minimum_payment_due": "100.05", 
                "past_amount_due": "", 
                "payment_due_date": "2018-11-11", 
                "statement_date": "2018-11-01", 
                "id": "123456789", 
                "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
                "status": "active", 
                "custom_fields": { }
            }
        ], 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts"
    }, 
    "funding_accounts": {
        "url": "/customers/{ID_CUSTOMER}/fundingaccounts"
    }, 
    "payments": {
        "url": "/customers/{ID_CUSTOMER}/payments"
    }, 
    "payment_setups": {
        "url": "/customers/{ID_CUSTOMER}/paymentsetups"
    }
}
Attributes
first_namestring

The first name of the customer. Either first_name or last_name is required to create a customer.

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

The last name of the customer. Either first_name or last_name is required to create a 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 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: 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._]+  
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 state or province code as per ISO_3166-2.

Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}  
address_countrystring

The 3 letter country code as per ISO 3166-1 (alpha-3).

Min. Length: 3  Max. Length: 3  Reg. 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: 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.This is not applicable and will be ignored in the case of non-US addresses.

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]{1,20}  
statusstring

The status of the customer in Orbipay.

Valid Values: active, disabled, voluntary_cancellation, revoked, suspended, inactive
urlstring

This URL fetches the Customer details.

customer_accountsobject
listarray
Min. Items: 1  
list[n]object
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: 32  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 state or province code as per ISO_3166-2.

Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}  
address_countrystring

The 3 letter country code as per ISO 3166-1 (alpha-3).

Min. Length: 3  Max. Length: 3  Reg. 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: 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.This is not applicable and will be ignored in the case of non-US addresses.

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: 4  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 customer account in Orbipay.

Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
urlstring

This URL fetches the 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.

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);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);

$customerAccount = new CustomerAccount();
$customerAccount->withDetails(account_holder_name, statement_date)
				    ->withBalances(current_balance, current_statement_balance)
				    ->withReference(customer_account_reference)
				    ->withAddress(new Address(address_line1, ..., address_zip2))
				    ->withCustomFields(custom_fields);

$customerAccounts = new CustomerAccounts();
$customerAccounts->add($customerAccount)

$customerRequest = new Customer();
$response = $customerRequest
			    ->withDetails(first_name, ..., gender)
			    ->withLocale(language, country)
			    ->withReference(customer_reference)
			    ->withAccounts($customerAccounts)
			    ->withAddress(new Address(address_line1, ..., address_zip2))
			    ->withContactInfo(email, ..., mobile_phone)
			    ->withMemo(comments)
			    ->withCustomFields(custom_fields)
			    ->forClient(client_key)
			    ->createdBy(requestor, requestor_type)
			    ->videChannel(channel)
			    ->create($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

CustomerAccount customerAccout = new CustomerAccount ()
                                                                            .WithReference(customer_account_reference )
                                                                            .WithDetails(account_holder_name , nickname , account_number, minimum_payment_due , past_amount_due , payment_due_date , statement_date)
                                                                            .WithAddress(new Address(address_line1, address_line2, address_city, address_state, address_country, address_zip1, address_zip2))
                                                                            .WithBalances(current_balance , current_statement_balance)
                                                                            .WithCustomFields(custom_fields);

CustomerAccounts customer_accounts = new CustomerAccounts ();
customer_accounts .Add(customerAccout );

Customer customer = new Customer()
                                                        .WithReference(customer_reference)
                                                       .WithDetails(first_name,last_name, middle_name,date_of_birth, ssn, gender)
                                                       .WithContactInfo(email, home_phone,work_phone, mobile_phone)
                                                       .WithLocale(locale)
                                                       .WithAddress(new Address(address_line1, address_line2, address_city, address_state, address_country, address_zip1, address_zip2))
                                                       .WithCustomFields(custom_fields)
                                                       .WithMemo(comments)
                                                       .WithAccounts(customer_accounts)
                                                       .ForClient(client_key)
                                                       .CreatedBy(requestor, requestor_type)
                                                       .VideChannel(channel)
                                                       .Create(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);

var customerAccount = new Orbipay.CustomerAccount()
                                    .withDetails(account_holder_name, statement_date)
				    .withBalances(current_balance, current_statement_balance)
				    .withReference(customer_account_reference)
				    .withAddress(new Orbipay.Address(address_line1, ..., address_zip2))
				    .withCustomFields(custom_fields);

var customerAccounts = new Orbipay.CustomerAccounts();
customerAccounts.add(customerAccount);

new Orbipay.Customer()
			    .withDetails(first_name, ..., gender)
			    .withLocale(language, country)
			    .withReference(customer_reference)
			    .withAccounts(customerAccounts)
			    .withAddress(new Orbipay.Address(address_line1, ..., address_zip2))
			    .withContactInfo(email, ..., mobile_phone)
			    .withMemo(comments)
			    .withCustomFields(custom_fields)
			    .forClient(client_key)
			    .createdBy(requestor, requestor_type)
			    .videChannel(channel)
			    .create(invocationContext, function(exception, customer) {
			  	// asynchronously called
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

customer_accounts = CustomerAccounts()
customer_account = CustomerAccount()
						.with_details(account_holder_name, nickname, 
						  account_number, minimum_payment_due, past_amount_due, 
						  payment_due_date, statement_date)
						.with_balances(current_balance, current_statement_balance)
						.with_reference(customer_account_reference)
						.with_address(Address(address_line1, address_line2, 
						  address_city, address_state, address_country, address_zip1, 
						  address_zip2))
						.with_custom_fields(custom_fields)
customer_accounts.set_list([customer_account, ])

response = Customer()
					.with_details(first_name, last_name, middle_name, date_of_birth, 
								ssn, gender)
					.with_reference(customer_reference)
					.with_contact_info(email, home_phone, work_phone, mobile_phone)
					.with_locale(locale)
					.with_accounts(customer_accounts)
					.with_address(Address(address_line1, address_line2, address_city, 
					  address_state, address_country, address_zip1, address_zip2))
					.with_custom_fields(custom_fields)
					.with_memo(comments)
					.for_client(client_key)
					.vide_channel(channel)
					.created_by(requestor, requestor_type)
					.create(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")

customer_accounts = CustomerAccounts.new
list = []
customer_account = CustomerAccount.new
				.with_details(account_holder_name: "", nickname: "", 
				  account_number: "", minimum_payment_due: "", past_amount_due: "", 
				  payment_due_date: "", statement_date: "")
				.with_balances(current_balance: "", current_statement_balance: "")
				.with_reference(customer_account_reference: "")
				.with_address(Address.new(address_line1: "", address_line2: "", 
				  address_city: "", address_state: "", address_country: "", address_zip1: "", 
				  address_zip2: ""))
				.with_custom_fields(custom_fields: {})
list.push(customer_account)
customer_accounts.set_list(list)

response = Customer.new
		.with_details(first_name: "", last_name: "", middle_name: "", date_of_birth: "", 
					ssn: "", gender: "")
		.with_reference(customer_reference: "")
		.with_contact_info(email: "", home_phone: "", work_phone: "", mobile_phone: "")
		.with_locale(locale: "")
		.with_accounts(customer_accounts: customer_accounts)
		.with_address(Address.new(address_line1: "", address_line2: "", address_city: "", 
		  address_state: "", address_country: "", address_zip1: "", address_zip2: ""))
		.with_custom_fields(custom_fields: {})
		.with_memo(comments: "")
		.for_client(client_key: "")
		.vide_channel(channel: "")
		.created_by(requestor: "", requestor_type: "")
		.create(invocation_context: invocation_context)

Request JSON

{
    "customer_accounts": [
        {
            "account_holder_name": "Michael Smith", 
            "nickname": "Smith", 
            "address": {
                "address_line1": "1551 South Washington Ave", 
                "address_line2": "Suite 130 Piscataway", 
                "address_city": "Piscataway", 
                "address_state": "NJ", 
                "address_country": "USA", 
                "address_zip1": "12345", 
                "address_zip2": "1234"
            }, 
            "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
            "account_number": "478E4385e604B685", 
            "current_balance": "110.05", 
            "current_statement_balance": "100.05", 
            "minimum_payment_due": "10.05", 
            "past_amount_due": "", 
            "payment_due_date": "2018-11-11", 
            "statement_date": "2018-11-01", 
            "custom_fields": { }
        }
    ], 
    "comments": "creating customer Smith", 
    "customer_reference": "IkdphX8DsEtOeOI_73823121", 
    "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": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "custom_fields": { }
}

Example responses

{
    "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": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "custom_fields": { }, 
    "customer_reference": "IkdphX8DsEtOeOI_73823121", 
    "id": "123456789", 
    "status": "active", 
    "url": "/customers/{ID_CUSTOMER}", 
    "customer_accounts": {
        "list": [
            {
                "account_holder_name": "Michael Smith", 
                "nickname": "Smith", 
                "address": {
                    "address_line1": "1551 South Washington Ave", 
                    "address_line2": "Suite 130 Piscataway", 
                    "address_city": "Piscataway", 
                    "address_state": "NJ", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }, 
                "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
                "account_number": "478E4385e604B685", 
                "current_balance": "110.05", 
                "current_statement_balance": "100.05", 
                "minimum_payment_due": "100.05", 
                "past_amount_due": "", 
                "payment_due_date": "2018-11-11", 
                "statement_date": "2018-11-01", 
                "id": "123456789", 
                "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
                "status": "active", 
                "custom_fields": { }
            }
        ], 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts"
    }, 
    "funding_accounts": {
        "url": "/customers/{ID_CUSTOMER}/fundingaccounts"
    }, 
    "payments": {
        "url": "/customers/{ID_CUSTOMER}/payments"
    }, 
    "payment_setups": {
        "url": "/customers/{ID_CUSTOMER}/paymentsetups"
    }
}

POST /customers

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.

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

Request Object

Attributes
customer_accountsrequired
customer_accounts[n]
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
comments
customer_reference
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

Returns

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
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
                  x_opay_headers)

response = 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 = Customer.new(id_customer: "")
		.for_client(client_key: "")
		.vide_channel(channel: "")
		.retrieved_by(requestor: "", requestor_type: "")
		.get(invocation_context: invocation_context)

Example responses

{
    "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": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "custom_fields": { }, 
    "customer_reference": "IkdphX8DsEtOeOI_73823121", 
    "id": "123456789", 
    "status": "active", 
    "url": "/customers/{ID_CUSTOMER}", 
    "customer_accounts": {
        "list": [
            {
                "account_holder_name": "Michael Smith", 
                "nickname": "Smith", 
                "address": {
                    "address_line1": "1551 South Washington Ave", 
                    "address_line2": "Suite 130 Piscataway", 
                    "address_city": "Piscataway", 
                    "address_state": "NJ", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }, 
                "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
                "account_number": "478E4385e604B685", 
                "current_balance": "110.05", 
                "current_statement_balance": "100.05", 
                "minimum_payment_due": "100.05", 
                "past_amount_due": "", 
                "payment_due_date": "2018-11-11", 
                "statement_date": "2018-11-01", 
                "id": "123456789", 
                "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
                "status": "active", 
                "custom_fields": { }
            }
        ], 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts"
    }, 
    "funding_accounts": {
        "url": "/customers/{ID_CUSTOMER}/fundingaccounts"
    }, 
    "payments": {
        "url": "/customers/{ID_CUSTOMER}/payments"
    }, 
    "payment_setups": {
        "url": "/customers/{ID_CUSTOMER}/paymentsetups"
    }
}

GET /customers/{ID_CUSTOMER}

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

Response content type: application/json

Request Parameters

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

Returns

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

Update Customer

List customerAccounts = new ArrayList<CustomerAccount>();
customerAccounts.add(new CustomerAccount(accountHolderName,  nickname, ... customFields));

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

Customer updateCustomer = new Customer(id)
									  .withDetails(firstName, ... customFields, gender)
									  .withAddress(new Address(addr1, ... country))
                                                                          .withMemo(comments)
                                                                          .forClient(clientKey)
									  .updatedBy(requestorId, requestorType)
                                                                          .videChannel(channel)
                                                                          .withAccounts(customerAccounts)
									  .update(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);

$customerAccount = new CustomerAccount();
$customerAccount->withDetails(account_holder_name, statement_date)
			    ->withBalances(current_balance, current_statement_balance)
			    ->withReference(customer_account_reference)
			    ->withStatus(status)
			    ->withAddress(new Address(address_line1, ..., address_zip2))
			    ->withCustomFields(custom_fields);

$customerAccounts = new CustomerAccounts();
$customerAccounts->add($customerAccount)

$customerRequest = new Customer();
$response = $customerRequest
			    ->withDetails(first_name, ..., gender)
			    ->withLocale(language, country)
			    ->withStatus(status)
			    ->withAccounts($customerAccounts)
			    ->withAddress(new Address(address_line1, ..., address_zip2))
			    ->withContactInfo(email, ..., mobile_phone)
			    ->withMemo(comments)
			    ->withCustomFields(custom_fields)
			    ->forClient(client_key)
			    ->updatedBy(requestor, requestor_type)
			    ->videChannel(channel)
			    ->update($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

CustomerAccount customerAccout = new CustomerAccount ()
                                                                            .WithReference(customer_account_reference )
                                                                            .WithDetails(account_holder_name , nickname , account_number, minimum_payment_due , past_amount_due , payment_due_date , statement_date)
                                                                            .WithAddress(new Address(address_line1, address_line2, address_city, address_state, address_country, address_zip1, address_zip2))
                                                                            .WithBalances(current_balance , current_statement_balance)
                                                                            .WithCustomFields(custom_fields)
                                                                            .WithStatus(status);

CustomerAccounts customer_accounts = new CustomerAccounts ();
customer_accounts .Add(customerAccout );

Customer customer = new Customer(ID_CUSTOMER)
                                                       .WithDetails(first_name,last_name, middle_name,date_of_birth, ssn, gender)
                                                       .WithContactInfo(email, home_phone,work_phone, mobile_phone)
                                                       .WithLocale(locale)
                                                       .WithAddress(new Address(address_line1, address_line2, address_city, address_state, address_country, address_zip1, address_zip2))
                                                       .WithCustomFields(custom_fields)
                                                       .WithStatus(status)
                                                       .WithMemo(comments)
                                                       .WithAccounts(customer_accounts)
                                                       .ForClient(client_key)
                                                       .UpdatedBy(requestor, requestor_type)
                                                       .VideChannel(channel)
                                                       .Update(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);

var customerAccount = new Orbipay.CustomerAccount()
                                    .withDetails(account_holder_name, statement_date)
                                    .withStatus(status)
				    .withBalances(current_balance, current_statement_balance)
				    .withReference(customer_account_reference)
				    .withAddress(new Address(address_line1, ..., address_zip2))
				    .withCustomFields(custom_fields);

var customerAccounts = new Orbipay.CustomerAccounts();
customerAccounts.add(customerAccount)

new Orbipay.Customer()
			    .withDetails(first_name, ..., gender)
			    .withLocale(language, country)
			    .withStatus(status)
			    .withAccounts(customerAccounts)
			    .withAddress(new Address(address_line1, ..., address_zip2))
			    .withContactInfo(email, ..., mobile_phone)
			    .withMemo(comments)
			    .withCustomFields(custom_fields)
			    .forClient(client_key)
			    .updatedBy(requestor, requestor_type)
			    .videChannel(channel)
			    .update(invocationContext, function(exception, customer) {
			  	// asynchronously called
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

customer_accounts = CustomerAccounts()

customer_account = CustomerAccount()
						.with_details(account_holder_name, nickname, 
						  account_number, minimum_payment_due, past_amount_due,
			 			  payment_due_date, statement_date)
						.with_balances(current_balance, current_statement_balance)
						.with_reference(customer_account_reference)
						.with_address(Address(address_line1, address_line2, 
						  address_city, address_state, address_country, address_zip1, 
						  address_zip2))
						.with_status(status)
						.with_custom_fields(custom_fields)

customer_accounts.set_list([customer_account, ])

customer = Customer(id_customer)
					.with_details(first_name, last_name, middle_name, date_of_birth, 
								ssn, gender)
					.with_accounts(customer_accounts)
					.with_reference(customer_reference)
					.with_status(status)
					.with_contact_info(email, home_phone, work_phone, mobile_phone)
					.with_locale(locale)
					.with_address(Address(address_line1, address_line2, address_city, 
					  address_state, address_country, address_zip1, address_zip2))
					.with_custom_fields(custom_fields)
					.with_memo(comments)
					.for_client(client_key)
					.vide_channel(channel)
                			.updated_by(requestor, requestor_type)
					.update(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")


customer_accounts = CustomerAccounts.new
list = []
customer_account = CustomerAccount.new
				.with_details(account_holder_name: "", nickname: "", 
				  account_number: "", minimum_payment_due: "", past_amount_due: "", 
				  payment_due_date: "", statement_date: "")
				.with_balances(current_balance: "", current_statement_balance: "")
				.with_reference(customer_account_reference: "")
				.with_address(Address.new(address_line1: "", address_line2: "", 
				  address_city: "", address_state: "", address_country: "", address_zip1: "", 
				  address_zip2: ""))
				.with_status(status: "")
				.with_custom_fields(custom_fields: {})
list.push(customer_account)
customer_accounts.set_list(list)

response = Customer.new
		.with_details(first_name: "", last_name: "", middle_name: "", date_of_birth: "", 
					ssn: "", gender: "")
		.with_contact_info(email: "", home_phone: "", work_phone: "", mobile_phone: "")
		.with_locale(locale: "")
		.with_status(status: "")
		.with_accounts(customer_accounts: customer_accounts)
		.with_address(Address.new(address_line1: "", address_line2: "", address_city: "", 
		  address_state: "", address_country: "", address_zip1: "", address_zip2: ""))
		.with_custom_fields(custom_fields: {})
		.with_memo(comments: "")
		.for_client(client_key: "")
		.vide_channel(channel: "")
		.updated_by(requestor: "", requestor_type: "")
		.update(invocation_context: invocation_context)

Request JSON

{
    "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": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "custom_fields": { }, 
    "status": "active", 
    "customer_accounts": [
        {
            "account_holder_name": "Michael Smith", 
            "nickname": "Smith", 
            "address": {
                "address_line1": "1551 South Washington Ave", 
                "address_line2": "Suite 130 Piscataway", 
                "address_city": "Piscataway", 
                "address_state": "NJ", 
                "address_country": "USA", 
                "address_zip1": "12345", 
                "address_zip2": "1234"
            }, 
            "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
            "account_number": "478E4385e604B685", 
            "current_balance": "110.05", 
            "current_statement_balance": "100.05", 
            "minimum_payment_due": "10.05", 
            "past_amount_due": "", 
            "payment_due_date": "2018-11-11", 
            "statement_date": "2018-11-01", 
            "custom_fields": { }, 
            "status": "active"
        }
    ], 
    "comments": "updating customer Smith"
}

Example responses

{
    "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": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "custom_fields": { }, 
    "customer_reference": "IkdphX8DsEtOeOI_73823121", 
    "id": "123456789", 
    "status": "active", 
    "url": "/customers/{ID_CUSTOMER}", 
    "customer_accounts": {
        "list": [
            {
                "account_holder_name": "Michael Smith", 
                "nickname": "Smith", 
                "address": {
                    "address_line1": "1551 South Washington Ave", 
                    "address_line2": "Suite 130 Piscataway", 
                    "address_city": "Piscataway", 
                    "address_state": "NJ", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }, 
                "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
                "account_number": "478E4385e604B685", 
                "current_balance": "110.05", 
                "current_statement_balance": "100.05", 
                "minimum_payment_due": "100.05", 
                "past_amount_due": "", 
                "payment_due_date": "2018-11-11", 
                "statement_date": "2018-11-01", 
                "id": "123456789", 
                "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
                "status": "active", 
                "custom_fields": { }
            }
        ], 
        "url": "/customers/{ID_CUSTOMER}/customeraccounts"
    }, 
    "funding_accounts": {
        "url": "/customers/{ID_CUSTOMER}/fundingaccounts"
    }, 
    "payments": {
        "url": "/customers/{ID_CUSTOMER}/payments"
    }, 
    "payment_setups": {
        "url": "/customers/{ID_CUSTOMER}/paymentsetups"
    }
}

PUT /customers/{ID_CUSTOMER}

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

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

Request Parameters

  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. 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);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

FilterData filter = new FilterData();

            filter.SetCustomerReference(customer_reference);
            filter.SetSsn(ssn);
            filter.SetEmail(email);
            filter.SetAccountNumber(account_number);

            filter.SetQueryId(query_id);
            filter.SetFromIndex(from_index);
            filter.SetToIndex(to_index);
            filter.SetPageSize(page_size);

Customers customers = new Customers()
                                                 .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 results

var 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 index

var 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
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = Customers()
                .find_by(customer_reference='', ssn='', email='', account_number='')
		.retrieved_by(requestor, requestor_type)
		.vide_channel(channel)
		.for_client(client_key)
		.get(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")

response = Customers.new
                .find_by(customer_reference: "", ssn: "", email: "", account_number: "")
		.vide_channel(channel: "")
		.for_client(client_key: "")
		.retrieved_by(requestor: "", requestor_type: "")
		.get(invocation_context: invocation_context)

Example responses

{
    "list": [
        {
            "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": {
                "address_line1": "1551 South Washington Ave", 
                "address_line2": "Suite 130 Piscataway", 
                "address_city": "Piscataway", 
                "address_state": "NJ", 
                "address_country": "USA", 
                "address_zip1": "12345", 
                "address_zip2": "1234"
            }, 
            "custom_fields": { }, 
            "customer_reference": "IkdphX8DsEtOeOI_73823121", 
            "id": "123456789", 
            "status": "active", 
            "url": "/customers/{ID_CUSTOMER}", 
            "customer_accounts": {
                "list": [
                    {
                        "account_holder_name": "Michael Smith", 
                        "nickname": "Smith", 
                        "address": {
                            "address_line1": "1551 South Washington Ave", 
                            "address_line2": "Suite 130 Piscataway", 
                            "address_city": "Piscataway", 
                            "address_state": "NJ", 
                            "address_country": "USA", 
                            "address_zip1": "12345", 
                            "address_zip2": "1234"
                        }, 
                        "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
                        "account_number": "478E4385e604B685", 
                        "current_balance": "110.05", 
                        "current_statement_balance": "100.05", 
                        "minimum_payment_due": "100.05", 
                        "past_amount_due": "", 
                        "payment_due_date": "2018-11-11", 
                        "statement_date": "2018-11-01", 
                        "id": "123456789", 
                        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
                        "status": "active", 
                        "custom_fields": { }
                    }
                ], 
                "url": "/customers/{ID_CUSTOMER}/customeraccounts"
            }, 
            "funding_accounts": {
                "url": "/customers/{ID_CUSTOMER}/fundingaccounts"
            }, 
            "payments": {
                "url": "/customers/{ID_CUSTOMER}/payments"
            }, 
            "payment_setups": {
                "url": "/customers/{ID_CUSTOMER}/paymentsetups"
            }
        }
    ], 
    "total_results_count": "1", 
    "has_more_results": "false", 
    "url": "/customers/lists?query_id=cakbhjaksgasdfauw61r27", 
    "from_index": "1", 
    "to_index": "1"
}

POST /customers/lists

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.

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

Request Parameters

  • page_sizestringin: query
  • The maximum number of objects returned in the query.
  • Min. Length: 1  Max. Length: 2  Reg. Exp.: [0-9]+  
  • customer_referencestringin: formData
  • Unique ID assigned by the biller/client system for a given customer.
  • Max. Length: 100  Reg. Exp.: ^$|[0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\s\\"]+  
  • ssnstringin: formData
  • 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}  
  • emailstringin: formData
  • This field contains the customer’s email address within Orbipay.
  • Max. Length: 100  Reg. Exp.: [a-zA-Z0-9!#$%&'*+-/=?^._`{|}~]+@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9._]+  
  • account_numberstringin: formData
  • Customer Account Number of the customer to get details of.
  • Min. Length: 4  Max. Length: 32  Reg. 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

Object JSON

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
    "account_number": "478E4385e604B685", 
    "current_balance": "110.05", 
    "current_statement_balance": "100.05", 
    "minimum_payment_due": "100.05", 
    "past_amount_due": "", 
    "payment_due_date": "2018-11-11", 
    "statement_date": "2018-11-01", 
    "id": "123456789", 
    "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
    "status": "active", 
    "custom_fields": { }
}
Attributes
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: 32  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 state or province code as per ISO_3166-2.

Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}  
address_countrystring

The 3 letter country code as per ISO 3166-1 (alpha-3).

Min. Length: 3  Max. Length: 3  Reg. 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: 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.This is not applicable and will be ignored in the case of non-US addresses.

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: 4  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 customer account in Orbipay.

Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
urlstring

This URL fetches the 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.

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 results

var 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 index

var 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)

Example responses

{
    "list": [
        {
            "account_holder_name": "Michael Smith", 
            "nickname": "Smith", 
            "address": {
                "address_line1": "1551 South Washington Ave", 
                "address_line2": "Suite 130 Piscataway", 
                "address_city": "Piscataway", 
                "address_state": "NJ", 
                "address_country": "USA", 
                "address_zip1": "12345", 
                "address_zip2": "1234"
            }, 
            "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
            "account_number": "478E4385e604B685", 
            "current_balance": "110.05", 
            "current_statement_balance": "100.05", 
            "minimum_payment_due": "100.05", 
            "past_amount_due": "", 
            "payment_due_date": "2018-11-11", 
            "statement_date": "2018-11-01", 
            "id": "123456789", 
            "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
            "status": "active", 
            "custom_fields": { }
        }
    ], 
    "total_results_count": "1", 
    "has_more_results": "false", 
    "url": "/customers/{ID_CUSTOMER}/customeraccounts/lists?query_id=cakbhjaksgasdlk78986rd", 
    "from_index": "1", 
    "to_index": "1"
}

POST /customers/{ID_CUSTOMER}/customeraccounts/lists

The API is used to retrieve all the customer accounts associated with a customer. The accounts can be filtered using the account number, status.

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

Request Parameters

  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • page_sizestringin: query
  • The maximum number of objects returned in the query.
  • Min. Length: 1  Max. Length: 2  Reg. Exp.: [0-9]+  
  • account_numberstringin: formData
  • The Account Number to get details of.
  • Min. Length: 4  Max. Length: 32  Reg. Exp.: [a-zA-Z0-9-_/!@#$%&*{}.]+  
  • statusstringin: formData
  • The status of the customer's account in Orbipay. This can take multiple values in the format key=value1&key=value2....
  • Valid Values: active, inactive, suspended, deleted, unverified, unusable

Returns

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

Get Customer Account

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

CustomerAccount getcustomerAccount = new CustomerAccount(id)
                                                                                                  .forCustomer(id)
									  			  .retrievedBy(requestorId, requestorType)
                                                                                                  .videChannel(channel)
									  			  .forClient(clientKey)
									  			  .get(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$customerAccountRequest = new CustomerAccount(ID_CUSTOMER_ACCOUNT);
$response = $customerAccountRequest
			    ->forClient(client_key)
			    ->retrievedBy(requestor, requestor_type)
			    ->videChannel(channel)
			    ->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

CustomerAccount customerAccount = new CustomerAccount(ID_CUSTOMER_ACCOUNT)
                                                                               .ForClient(client_key)
                                                                               .ForCustomer(ID_CUSTOMER)
                                                                               .VideChannel(channel)
                                                                               .RetrievedBy(requestor, requestor_type)
                                                                               .Get(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.CustomerAccount(ID_CUSTOMER_ACCOUNT)
			    .forCustomer(ID_CUSTOMER)
			    .forClient(client_key)
			    .retrievedBy(requestor, requestor_type)
			    .videChannel(channel)
			    .get(invocationContext, function(exception, customerAccount) {
			  	// asynchronously called
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = CustomerAccount(id_customer_account)
				.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 = CustomerAccount.new(id_customer_account: "")
				.for_customer(id_customer: "")
				.for_client(client_key: "")
				.vide_channel(channel: "")
				.retrieved_by(requestor: "", requestor_type: "")
				.get(invocation_context: invocation_context)

Example responses

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "customer_account_reference": "EruOehjef1ByeQ9JWM2D", 
    "account_number": "478E4385e604B685", 
    "current_balance": "110.05", 
    "current_statement_balance": "100.05", 
    "minimum_payment_due": "100.05", 
    "past_amount_due": "", 
    "payment_due_date": "2018-11-11", 
    "statement_date": "2018-11-01", 
    "id": "123456789", 
    "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}", 
    "status": "active", 
    "custom_fields": { }
}

GET /customers/{ID_CUSTOMER}/customeraccounts/{ID_CUSTOMER_ACCOUNT}

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

Response content type: application/json

Request Parameters

  • ID_CUSTOMER_ACCOUNTstringin: path required
  • The unique identifier assigned by Orbipay to the Customer Account.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  

Returns

The customer account.

Funding Account

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

The Funding Account Object

A Customer makes a Payment using a Funding Account. Orbipay supports the use of the following bank and card accounts:

BankCreditDebit
Savings AccountVisaVisa
Current AccountMastercardMastercard
Money Market AccountAmerican ExpressDiscover
Discover

Object JSON

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "account_number": "xxxxx0206", 
    "aba_routing_number": "123456789", 
    "issuer_name": "BANK ISSUER NAME", 
    "currency_code3d": "USD", 
    "expiry_date": "", 
    "account_holder_type": "personal", 
    "custom_fields": { }, 
    "account_subtype": "savings", 
    "id": "123456789", 
    "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
    "ach_eligible_flag": "yes", 
    "atm_eligible_flag": "no", 
    "card_cvv_number": "", 
    "account_type": "bank", 
    "status": "active"
}
Attributes
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: 32  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 state or province code as per ISO_3166-2.

Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}  
address_countrystring

The 3 letter country code as per ISO 3166-1 (alpha-3).

Min. Length: 3  Max. Length: 3  Reg. 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: 2  Max. Length: 10  Reg. 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: 4  Max. Length: 4  Reg. Exp.: [0-9]{4}  
account_numberstring

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

Min. Length: 4  Max. Length: 32  Reg. Exp.: [a-zA-Z0-9]+  
aba_routing_numberstring

The ABA/Routing number for the bank account.

Min. Length: 9  Max. Length: 9  Reg. 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.

Max. Length: 32  Reg. Exp.: [0-9a-zA-Z #,.'&/\-@!$%*()_+={}|:;`\[\]\^\~\\"]+  
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}  
expiry_datestring

The expiry date for the card. This is to be in the format MM/yy. Only applicable for cards accounts.

Min. Length: 5  Max. Length: 5  Reg. 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.

Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
idstring

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

Min. Length: 3  Max. Length: 4  Reg. Exp.: [0-9]+  
account_typestring

The type of the funding account.

Valid Values: bank, debit_card, credit_card
statusstring

The status of the funding account in Orbipay.

Valid Values: active, inactive, frozen, deleted, suspended, unverified, unusable

Add Funding Account

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

FundingAccount addFundingAccount =  new FundingAccount(cardCVVNumber,  accountHolderName, ... customFields)
									  			  .forCustomer(id)
									  			  .withAddress(new Address(addr1, ... country))
                                                                                                  .withMemo(comments)
									  			  .createdBy(requestorId, requestorType)
                                                                                                  .videChannel(channel)
									  			  .forClient(clientKey)
									  			  .create(invocationContext);
$fundingAccount = new FundingAccount();
$response = $fundingAccount
			    ->withDetails(account_holder_name, ..., account_holder_type)
		            ->withReference(funding_account_reference)
			    ->forCustomer(ID_CUSTOMER)
			    ->withAddress(new Address(address_line1, ..., address_zip2))
			    ->withMemo(comments)
			    ->withCustomFields(custom_fields)
			    ->forClient(client_key)
			    ->createdBy(requestor, requestor_type)
			    ->videChannel(channel)
			    ->create($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

FundingAccount fundingAccount = new FundingAccount()
                                                                        .WithDetails(account_holder_name, nickname,account_number, account_subtype, aba_routing_number,card_cvv_number, expiry_date, account_holder_type)
                                                                         .WithAddress(new Address(address_line1, address_line2, address_city, address_state, address_country, address_zip1, address_zip2))
                                                                         .WithCustomFields(custom_fields)
                                                                         .WithMemo(comments)
                                                                         .ForClient(client_key)
                                                                         .ForCustomer(ID_CUSTOMER)
                                                                         .VideChannel(channel)
                                                                         .CreatedBy(requestor, requestor_type)
                                                                         .Create(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.FundingAccount()
			    .withDetails(account_holder_name, ..., account_holder_type)
		            .withReference(funding_account_reference)
			    .forCustomer(ID_CUSTOMER)
			    .withAddress(new Orbipay.Address(address_line1, ..., address_zip2))
			    .withMemo(comments)
			    .withCustomFields(custom_fields)
			    .forClient(client_key)
			    .createdBy(requestor, requestor_type)
			    .videChannel(channel)
			    .create(invocationContext, function(exception, fundingAccount) {
			  	// asynchronously called
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response= FundingAccount()
                 			.with_details(account_holder_name, nickname, 
		    						account_number, account_subtype, aba_routing_number, 
		    						card_cvv_number, expiry_date, account_holder_type)
					.for_customer(id_customer)
					.with_address(Address(address_line1, address_line2, 
		    			address_city, address_state, address_country, address_zip1, 
		    			address_zip2))
					.with_custom_fields(custom_fields)
					.with_memo(comments)
					.for_client(client_key)
					.vide_channel(channel)
                			.created_by(requestor, requestor_type)
					.create(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")

response= FundingAccount.new
 			.with_details(account_holder_name: "", nickname: "", 
    			  account_number: "", account_subtype: "", aba_routing_number: "", 
    			  card_cvv_number: "", expiry_date: "", account_holder_type: "")
			.for_customer(id_customer: "")
			.with_address(Address.new(address_line1: "", address_line2: "", 
    			address_city: "", address_state: "", address_country: "", address_zip1: "", 
    			address_zip2: ""))
			.with_custom_fields(custom_fields: {})
			.with_memo(comments: "")
			.for_client(client_key: "")
			.vide_channel(channel: "")
			.created_by(requestor: "", requestor_type: "")
			.create(invocation_context: invocation_context)

Request JSON

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "account_number": "123450206", 
    "aba_routing_number": "123456789", 
    "expiry_date": "", 
    "account_holder_type": "personal", 
    "custom_fields": { }, 
    "account_subtype": "savings", 
    "card_cvv_number": "", 
    "comments": "Adding fund source"
}

Example responses

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "account_number": "xxxxx0206", 
    "aba_routing_number": "123456789", 
    "issuer_name": "BANK ISSUER NAME", 
    "currency_code3d": "USD", 
    "expiry_date": "", 
    "account_holder_type": "personal", 
    "custom_fields": { }, 
    "account_subtype": "savings", 
    "id": "123456789", 
    "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
    "ach_eligible_flag": "yes", 
    "atm_eligible_flag": "no", 
    "card_cvv_number": "", 
    "account_type": "bank", 
    "status": "active"
}

POST /customers/{ID_CUSTOMER}/fundingaccounts

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.

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

Request Parameters

  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. 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 results

var 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 index

var 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)

Example responses

{
    "list": [
        {
            "account_holder_name": "Michael Smith", 
            "nickname": "Smith", 
            "address": {
                "address_line1": "1551 South Washington Ave", 
                "address_line2": "Suite 130 Piscataway", 
                "address_city": "Piscataway", 
                "address_state": "NJ", 
                "address_country": "USA", 
                "address_zip1": "12345", 
                "address_zip2": "1234"
            }, 
            "account_number": "xxxxx0206", 
            "aba_routing_number": "123456789", 
            "issuer_name": "BANK ISSUER NAME", 
            "currency_code3d": "USD", 
            "expiry_date": "", 
            "account_holder_type": "personal", 
            "custom_fields": { }, 
            "account_subtype": "savings", 
            "id": "123456789", 
            "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
            "ach_eligible_flag": "yes", 
            "atm_eligible_flag": "no", 
            "card_cvv_number": "", 
            "account_type": "bank", 
            "status": "active"
        }
    ], 
    "total_results_count": "1", 
    "has_more_results": "false", 
    "url": "/customers/{ID_CUSTOMER}/fundingaccounts/lists?query_id=cakbhjaksgasdjy5r67rfuf", 
    "from_index": "1", 
    "to_index": "1"
}

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.

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

Request Parameters

  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • page_sizestringin: query
  • The maximum number of objects returned in the query.
  • Min. Length: 1  Max. Length: 2  Reg. Exp.: [0-9]+  
  • account_numberstringin: formData
  • The Account Number to get details of.
  • Min. Length: 4  Max. Length: 32  Reg. Exp.: [a-zA-Z0-9]+  
  • statusstringin: formData
  • The status of the funding account in Orbipay. This can take multiple values in the format key=value1&key=value2....
  • Valid Values: active, inactive, frozen, deleted, suspended, unverified, unusable
  • aba_routing_numberstringin: formData
  • The ABA/Routing number for the bank account.
  • Min. Length: 9  Max. Length: 9  Reg. Exp.: [0-9]{9}  
  • account_typestringin: formData
  • 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.
  • Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit

Returns

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

Get Funding Account

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

FundingAccount getFundingAccount =  new FundingAccount(id)
                                                                                            .forCustomer(id)
									  	            .retrievedBy(requestorId, requestorType)
                                                                                            .videChannel(channel)
									  		    .forClient(clientKey)
									  		    .get(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$fundingAccountRequest = new FundingAccount(ID_FUNDING_ACCOUNT);
$response = $fundingAccountRequest
			    ->forClient(client_key)
			    ->retrievedBy(requestor, requestor_type)
			    ->videChannel(channel)
			    ->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

FundingAccount fundingAccount = new FundingAccount(ID_FUNDING_ACCOUNT)
                                                                        .ForClient(client_key)
                                                                        .ForCustomer(ID_CUSTOMER)
                                                                        .VideChannel(channel)
                                                                        .RetrievedBy(requestor, requestor_type)
                                                                        .Get(invocationContext, invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.FundingAccount(ID_FUNDING_ACCOUNT)
			    .forCustomer(ID_CUSTOMER)
			    .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 = FundingAccount(id_funding_account)
                .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 = FundingAccount.new(id_funding_account: "")
                .for_customer(id_customer: "")
		.for_client(client_key: "")
		.vide_channel(channel: "")
		.retrieved_by(requestor: "", requestor_type: "")
		.get(invocation_context: invocation_context)

Example responses

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "account_number": "xxxxx0206", 
    "aba_routing_number": "123456789", 
    "issuer_name": "BANK ISSUER NAME", 
    "currency_code3d": "USD", 
    "expiry_date": "", 
    "account_holder_type": "personal", 
    "custom_fields": { }, 
    "account_subtype": "savings", 
    "id": "123456789", 
    "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
    "ach_eligible_flag": "yes", 
    "atm_eligible_flag": "no", 
    "card_cvv_number": "", 
    "account_type": "bank", 
    "status": "active"
}

GET /customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}

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

Response content type: application/json

Request Parameters

  • ID_FUNDING_ACCOUNTstringin: path required
  • The unique identifier assigned by Orbipay to the Funding Account.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  

Returns

The funding account with the id provided.

Update Funding Account

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

FundingAccount updateFundingAccount = new FundingAccount(id)
									  			  .withDetails(cardCVVNumber,  accountHolderName, ... customFields)
                                                                                                  .forCustomer(id)
									  			  .withAddress(new Address(addr1, ... country))
                                                                                                  .withMemo(memo)
									  			  .updatedBy(requestorId, requestorType)
                                                                                                  .videChannel(channel)
									  			  .forClient(clientKey)
									  			  .update(invocationContext);
$fundingAccount = new FundingAccount(ID_FUNDING_ACCOUNT);
$response = $fundingAccount
				    ->withDetails(account_holder_name, ..., account_holder_type)
				    ->forCustomer(ID_CUSTOMER)
				    ->withStatus(status)
				    ->withAddress(new Address(address_line1, ..., address_zip2))
				    ->withMemo(comments)
				    ->withCustomFields(custom_fields)
				    ->forClient(client_key)
				    ->updatedBy(requestor, requestor_type)
				    ->videChannel(channel)
				    ->update($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

FundingAccount fundingAccount = new FundingAccount(ID_FUNDING_ACCOUNT)
                                                                        .WithDetails(account_holder_name, nickname,account_number, account_subtype, aba_routing_number,card_cvv_number, expiry_date, account_holder_type)
                                                                         .WithAddress(new Address(address_line1, address_line2, address_city, address_state, address_country, address_zip1, address_zip2))
                                                                         .WithCustomFields(custom_fields)
                                                                         .WithMemo(comments)
                                                                         .WithStatus(status)
                                                                         .ForClient(client_key)
                                                                         .ForCustomer(ID_CUSTOMER)
                                                                         .VideChannel(channel)
                                                                         .UpdatedBy(requestor, requestor_type)
                                                                         .Update(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.FundingAccount()
			    .withDetails(account_holder_name, ..., account_holder_type)
		            .withStatus(status)
			    .forCustomer(ID_CUSTOMER)
			    .withAddress(new Orbipay.Address(address_line1, ..., address_zip2))
			    .withMemo(comments)
			    .withCustomFields(custom_fields)
			    .forClient(client_key)
			    .updatedBy(requestor, requestor_type)
			    .videChannel(channel)
			    .update(invocationContext, function(exception, fundingAccount) {
			  	// asynchronously called
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = FundingAccount(id_funding_account)
                                                .with_details(account_holder_name, 
		                                  nickname, account_number, account_subtype, aba_routing_number, 
		                                  card_cvv_number, expiry_date, account_holder_type)
                                                .for_customer(id_customer)
                                                .withStatus(status)
                                                .with_address(Address(address_line1, address_line2, 
		                                  address_city, address_state, address_country, address_zip1, 
		                                  address_zip2))
                                                .with_custom_fields(custom_fields)
                                                .with_memo(comments)
                                                .for_client(client_key)
                                                .vide_channel(channel)
                                                .updated_by(requestor, requestor_type)
                                                .update(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")

response = FundingAccount.new(id_funding_account: "")
                                .with_details(account_holder_name: "", 
                                  nickname: "", account_number: "", account_subtype: "", aba_routing_number: "", 
                                  card_cvv_number: "", expiry_date: "", account_holder_type: "")
                                .for_customer(id_customer: "")
                                .with_status(status: "")
                                .with_address(Address.new(address_line1: "", address_line2: "", 
                                  address_city: "", address_state: "", address_country: "", address_zip1: "", 
                                  address_zip2: ""))
                                .with_custom_fields(custom_fields: {})
                                .with_memo(comments: "")
                                .for_client(client_key: "")
                                .vide_channel(channel: "")
                                .updated_by(requestor: "", requestor_type: "")
                                .update(invocation_context: invocation_context)

Request JSON

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "account_number": "123450206", 
    "aba_routing_number": "123456789", 
    "expiry_date": "", 
    "account_holder_type": "personal", 
    "custom_fields": { }, 
    "account_subtype": "savings", 
    "status": "active", 
    "card_cvv_number": "", 
    "comments": "updating fund source"
}

Example responses

{
    "account_holder_name": "Michael Smith", 
    "nickname": "Smith", 
    "address": {
        "address_line1": "1551 South Washington Ave", 
        "address_line2": "Suite 130 Piscataway", 
        "address_city": "Piscataway", 
        "address_state": "NJ", 
        "address_country": "USA", 
        "address_zip1": "12345", 
        "address_zip2": "1234"
    }, 
    "account_number": "xxxxx0206", 
    "aba_routing_number": "123456789", 
    "issuer_name": "BANK ISSUER NAME", 
    "currency_code3d": "USD", 
    "expiry_date": "", 
    "account_holder_type": "personal", 
    "custom_fields": { }, 
    "account_subtype": "savings", 
    "id": "123456789", 
    "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
    "ach_eligible_flag": "yes", 
    "atm_eligible_flag": "no", 
    "card_cvv_number": "", 
    "account_type": "bank", 
    "status": "active"
}

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.

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

Request Parameters

  • ID_FUNDING_ACCOUNTstringin: path required
  • The unique identifier assigned by Orbipay to the Funding Account.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  

Request Object

Attributes
account_holder_name
nickname
address
address_line1
address_line2
address_city
address_state
address_country
address_zip1
address_zip2
account_number
aba_routing_number
expiry_date
account_holder_type
custom_fields
account_subtype
status
card_cvv_number
comments

Returns

The updated funding account.

Delete Funding Account

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

FundingAccount deleteFundingAccount = new FundingAccount(id)
                                                                                                  .forCustomer(id)
									  			  .deletedBy(requestorId, requestorType)
                                                                                                  .videChannel(channel)
									  			  .withMemo(comments)
									  			  .forClient(clientKey)
									  			  .delete(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$fundingAccountRequest = new FundingAccount(ID_FUNDING_ACCOUNT);
$response = $fundingAccountRequest
			    ->forClient(client_key)
			    ->deletedBy(requestor, requestor_type)
			    ->videChannel(channel)
			    ->delete($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

 FundingAccount fundingAccount = new FundingAccount(ID_FUNDING_ACCOUNT)
                                                                                   .ForCustomer(ID_CUSTOMER)
                                                                                   .DeleteddBy(requestor, requestor_type)
                                                                                   .VideChannel(channel)
                                                                                   .WithMemo(comments)
                                                                                   .ForClient(client_key)
                                                                                   .Delete(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new FundingAccount(ID_FUNDING_ACCOUNT)
			    .forCustomer(ID_CUSTOMER)
			    .forClient(client_key)
			    .deletedBy(requestor, requestor_type)
			    .videChannel(channel)
			    .delete(invocationContext, function(exception, fundingAccount) {
			  	// asynchronously called
			    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = FundingAccount(id_funding_account)
				.with_memo(comments)
				.for_customer(id_customer)
				.for_client(client_key)
				.vide_channel(channel)
				.deleted_by(requestor, requestor_type)
				.delete(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")

response = FundingAccount.new(id_funding_account: "")
				.for_customer(id_customer: "")
				.with_memo(comments: "")
				.for_client(client_key: "")
				.vide_channel(channel: "")
				.deleted_by(requestor: "", requestor_type: "")
				.delete(invocation_context: invocation_context)

Request JSON

{
    "comments": "deleting fund source"
}

Example responses

{
    "deleted": "true", 
    "id": "string"
}

DELETE /customers/{ID_CUSTOMER}/fundingaccounts/{ID_FUNDING_ACCOUNT}

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

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

Request Parameters

  • ID_FUNDING_ACCOUNTstringin: path required
  • The unique identifier assigned by Orbipay to the Funding Account.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. 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.

Object JSON

{
    "id": "123456789", 
    "url": "/payments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "payment_date": "2019-12-03", 
    "payment_schedule_type": "one_time_payment", 
    "payment_request_date": "", 
    "payment_amount_type": "other", 
    "payment_reference": "PBruOrpMLl1dsBQ-1234567", 
    "expected_payment_settlement_date": "", 
    "payment_entry_date": "2019-12-03", 
    "payment_return_date": "", 
    "return_code": "", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}
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, bill_separately
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]?)?$  
idstring

The unique identifier assigned by Orbipay to the fee. In case of split fee.

Max. Length: 20  Reg. Exp.: [0-9]{0,20}  
urlstring

This URL fetches the details of fee as a payment resource. In case of split fee.

statusstring

The status of the payment.

Valid Values: scheduled, cancelled, processing, processed, returned, declined, disputed, refunded
payment_methodstring

The fulfillment method for the payment.

Valid Values: ach, check, visa_debit, pinless_debit, master_debit, amex_credit, discover_credit, visa_credit, master_credit, cash, discover_debit
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 '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: 1  Max. Length: 17  Reg. 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: 3  Max. Length: 4  Reg. 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: 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, autopay_generated_payment, variable_recurring_generated_payment, payment_plan_generated
payment_request_datestring

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: 10  Max. Length: 10  Date 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: 50  Reg. 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: 10  Max. Length: 10  Date 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: 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

idstring

The unique identifier assigned by Orbipay to the customer.

Max. Length: 20  Reg. Exp.: [0-9]{0,20}  
urlstring

The URL that can be used to fetch the details of the customer.

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 initial of the customer.

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

The email address of the customer.

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}  
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 state or province code as per ISO_3166-2.

Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}  
address_countrystring

The 3 letter country code as per ISO 3166-1 (alpha-3).

Min. Length: 3  Max. Length: 3  Reg. 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: 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.This is not applicable and will be ignored in the case of non-US addresses.

Min. Length: 4  Max. Length: 4  Reg. 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: 20  Reg. 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: 4  Max. Length: 32  Reg. 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.

Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
aba_routing_numberstring

The ABA/Routing number for the bank account.

Min. Length: 9  Max. Length: 9  Reg. Exp.: [0-9]{9}  
customer_accountobject

The customer account against which the payment is being made.

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

var 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 index

var 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)

Example responses

{
    "list": [
        {
            "id": "123456789", 
            "url": "/payments/{ID_PAYMENT}", 
            "fee": {
                "fee_type": "add_to_principal", 
                "fee_amount": "5.00", 
                "id": "123456789", 
                "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
            }, 
            "status": "scheduled", 
            "payment_method": "ach", 
            "confirmation_number": "A12N12I12L", 
            "custom_fields": { }, 
            "currency_code3d": "USD", 
            "amount": "101.05", 
            "card_cvv_number": "", 
            "payment_date": "2019-12-03", 
            "payment_schedule_type": "one_time_payment", 
            "payment_request_date": "", 
            "payment_amount_type": "other", 
            "payment_reference": "PBruOrpMLl1dsBQ-1234567", 
            "expected_payment_settlement_date": "", 
            "payment_entry_date": "2019-12-03", 
            "payment_return_date": "", 
            "return_code": "", 
            "customer": {
                "id": "12684515", 
                "url": "/customers/{ID_CUSTOMER}", 
                "first_name": "Michael", 
                "last_name": "Smith", 
                "middle_name": "S", 
                "email": "userid@example.com", 
                "home_phone": "1234567890", 
                "address": {
                    "address_line1": "1551 South Washington Ave", 
                    "address_line2": "Suite 130 Piscataway", 
                    "address_city": "Piscataway", 
                    "address_state": "NJ", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }
            }, 
            "funding_account": {
                "id": "123456789", 
                "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
                "account_number": "xxxxx0206", 
                "account_type": "bank", 
                "account_subtype": "savings", 
                "aba_routing_number": "123456789"
            }, 
            "customer_account": {
                "id": "123456789", 
                "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
            }
        }
    ], 
    "total_results_count": "1", 
    "has_more_results": "false", 
    "url": "/payments?query_id=cakbhjaksgasdv6uiv6", 
    "from_index": "1", 
    "to_index": "1"
}

GET /payments

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: 20  Reg. Exp.: [0-9]{1,20}  
  • id_funding_accountstringin: query
  • The unique identifier assigned by Orbipay to the funding account
  • 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]+  
  • statusstringin: query
  • The status of the payment. This can take multiple values in the format key=value1&key=value2....
  • Valid Values: scheduled, cancelled, processing, processed, returned, declined, disputed, refunded
  • payment_schedule_typestringin: query
  • The schedule type for the payment setup. This can take multiple values in the format key=value1&key=value2....
  • Valid Values: one_time_payment, autopay_generated_payment, variable_recurring_generated_payment, payment_plan_generated
  • 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.

Create Payment

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

Payment payment = new Payment(paymentReference,  amount,  currencyCode3d, ... paymentRequestDate)
                                                      .withFee(new Fee(feeAmount))
                                                      .forCustomer(id)
						      .fromAccount(new FundingAccount(id))
						      .toAccount(new CustomerAccount(id))
						      .createdBy(requestorId, requestorType)
                                                      .videChannel(channel)
                                                      .withMemo(comments)
						      .forClient(clientKey)
						      .create(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentRequest = new Payment();
$response = $paymentRequest
		    ->withDetails(amount, .., payment_schedule_type)
		    ->withReference(payment_reference)
		    ->forCustomer(ID_CUSTOMER)
		    ->fromAccount(new FundingAccount(ID_FUNDING_ACCOUNT))
		    ->toAccount(new CustomerAccount(ID_CUSTOMER_ACCOUNT))
		    ->withMemo(comments)
		    ->forClient(client_key)
		    ->createdBy(requestor, requestor_type)
		    ->videChannel(channel)
		    ->create($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

 Payment payment = new Payment()
                                                     .WithReference(payment_reference)
                                                     .WithDetails(payment_amount_type, amount,payment_date, payment_request_date,card_cvv_number)
                                                     .WithFee(new Fee(fee_amount))
                                                     .WithMemo(comments)
                                                     .WithCustomFields(custom_fields)
                                                     .FromAccount(new FundingAccount(id))
                                                     .ToAccount(new CustomerAccount(id))
                                                    .ForClient(client_key)
                                                   .ForCustomer(ID_CUSTOMER)
                                                   .VideChannel(channel)
                                                  .CreatedBy(requestor, requestor_type)
                                                  .Create(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);
new Orbipay.Payment()
		    .withDetails(amount, .., payment_schedule_type)
		    .withReference(payment_reference)
		    .forCustomer(ID_CUSTOMER)
                    .fromAccount(new Orbipay.FundingAccount(ID_FUNDING_ACCOUNT))
                    .toAccount(new Orbipay.CustomerAccount(ID_CUSTOMER_ACCOUNT))
		    .withMemo(comments)
		    .forClient(client_key)
		    .createdBy(requestor, requestor_type)
		    .videChannel(channel)
		    .create(invocationContext, function(exception, payment) {
			  	// asynchronously called
	            });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = Payment()
				.with_details(payment_amount_type, amount, payment_date, 
				  payment_request_date, card_cvv_number)
				.for_customer(id_customer)
				.with_reference(payment_reference)
				.from_account(FundingAccount(id_funding_account))
				.to_account(CustomerAccount(id_customer_account))
				.with_memo(comments)
				.with_fee(Fee(fee_amount))
				.with_custom_fields(custom_fields)
				.for_client(client_key)
				.vide_channel(channel)
				.created_by(requestor, requestor_type)
				.create(invocation_context)
invocation_context = InvocationContext.new(secret: "", idempotent_request_key: "", x_opay_headers: "")

response = Payment.new
				.with_details(payment_amount_type: "", amount: "", payment_date: "", 
				  payment_request_date: "", card_cvv_number: "")
				.for_customer(id_customer: "")
				.with_reference(payment_reference: "")
				.from_account(FundingAccount.new(id_funding_account: ""))
				.to_account(CustomerAccount.new(id_customer_account: ""))
				.with_memo(comments: "")
				.with_fee(Fee.new(fee_amount: ""))
				.with_custom_fields(custom_fields: {})
				.for_client(client_key: "")
				.vide_channel(channel: "")
				.created_by(requestor: "", requestor_type: "")
				.create(invocation_context: invocation_context)

Request JSON

{
    "amount": "101.05", 
    "card_cvv_number": "", 
    "payment_date": "2019-12-03", 
    "payment_request_date": "", 
    "payment_amount_type": "other", 
    "fee": {
        "fee_amount": "5.00"
    }, 
    "customer": {
        "id": "12684515"
    }, 
    "funding_account": {
        "id": "123456789"
    }, 
    "customer_account": {
        "id": "123456789"
    }, 
    "payment_reference": "PBruOrpMLl1dsBQ-1234567", 
    "comments": "making a payment", 
    "custom_fields": { }
}

Example responses

{
    "id": "123456789", 
    "url": "/payments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "payment_date": "2019-12-03", 
    "payment_schedule_type": "one_time_payment", 
    "payment_request_date": "", 
    "payment_amount_type": "other", 
    "payment_reference": "PBruOrpMLl1dsBQ-1234567", 
    "expected_payment_settlement_date": "", 
    "payment_entry_date": "2019-12-03", 
    "payment_return_date": "", 
    "return_code": "", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}

POST /customers/{ID_CUSTOMER}/payments

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.

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

Request Parameters

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

Request Object

Attributes
amount
card_cvv_number
payment_date
payment_request_date
payment_amount_type
fee
fee_amount
customerrequired
idrequired
funding_accountrequired
idrequired
customer_accountrequired
idrequired
payment_reference
comments
custom_fields

Returns

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

Get Payment

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

Payment getPayment = new Payment(id)
                                                           .forCustomer(id)
						           .retrievedBy(requestorId, requestorType)
                                                           .videChannel(channel)
						           .forClient(clientKey)
						           .get(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentRequest = new Payment(ID_PAYMENT);
$response = $paymentRequest
	    ->forClient(client_key)
	    ->retrievedBy(requestor, requestor_type)
	    ->videChannel(channel)
	    ->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

Payment payment = new Payment(ID_PAYMENT)
                                          .ForCustomer(ID_CUSTOMER)
                                          .ForClient(client_key)
                                          .VideChannel(channel)
                                          .RetrievedBy(requestor, requestor_type)
                                          .Get(invocationContext , invocation_mode, url);
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
            });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = Payment(id_payment)
		.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 = Payment.new(id_payment: "")
			.for_customer(id_customer: "")
			.for_client(client_key: "")
			.vide_channel(channel: "")
			.retrieved_by(requestor: "", requestor_type: "")
			.get(invocation_context: invocation_context)

Example responses

{
    "id": "123456789", 
    "url": "/payments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "payment_date": "2019-12-03", 
    "payment_schedule_type": "one_time_payment", 
    "payment_request_date": "", 
    "payment_amount_type": "other", 
    "payment_reference": "PBruOrpMLl1dsBQ-1234567", 
    "expected_payment_settlement_date": "", 
    "payment_entry_date": "2019-12-03", 
    "payment_return_date": "", 
    "return_code": "", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}

GET /customers/{ID_CUSTOMER}/payments/{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}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  

Returns

The Payment with the id provided.

Update Payment

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

Payment updatePayment = new Payment(id)
							           .withDetails(amount,  currencyCode3d, ... customFields)
                                                                   .withFee(new Fee(feeAmount))
                                                                   .forCustomer(id)
						                   .fromAccount(new FundingAccount(id))
							           .updatedBy(requestorId, requestorType)
                                                                   .videChannel(channel)
                                                                   .withMemo(comments)
							           .forClient(clientKey)
							           .update(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentRequest = new Payment(ID_PAYMENT);
$response = $paymentRequest
		    ->withDetails(amount, .., payment_schedule_type)
		    ->withStatus(status)
		    ->fromAccount(new FundingAccount(ID_FUNDING_ACCOUNT))
		    ->withMemo(comments)
		    ->forClient(client_key)
		    ->updatedBy(requestor, requestor_type)
		    ->videChannel(channel)
		    ->update($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

 Payment payment = new Payment(ID_PAYMENT)
                                                     .WithDetails(payment_amount_type, amount,payment_date, payment_request_date,card_cvv_number)
                                                     .WithFee(new Fee(fee_amount))
                                                     .WithMemo(comments)
                                                     .WithCustomFields(custom_fields)
                                                     .FromAccount(new FundingAccount(id))
                                                    .ForClient(client_key)
                                                   .ForCustomer(ID_CUSTOMER)
                                                   .VideChannel(channel)
                                                  .UpdatedBy(requestor, requestor_type)
                                                  .Update(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');
var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);

new Orbipay.Payment(ID_PAYMENT)
		    .withDetails(amount, .., payment_schedule_type)
		    .withStatus(status)
		    .fromAccount(new Orbipay.FundingAccount(ID_FUNDING_ACCOUNT))
		    .withMemo(comments)
		    .forClient(client_key)
		    .updatedBy(requestor, requestor_type)
		    .videChannel(channel)
		    .update(invocationContext, function(exception, payment) {
			  	// asynchronously called
                    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = Payment(id_payment)
				.with_details(payment_amount_type, amount, 
				  payment_date, payment_request_date, card_cvv_number)
				.for_customer(id_customer)
				.from_account(FundingAccount(id_funding_account))
				.to_account(CustomerAccount(id_customer_account))
				.with_memo(comments)
				.with_fee(Fee(fee_amount))
				.with_custom_fields(custom_fields)
				.for_client(client_key)
				.vide_channel(channel)
				.updated_by(requestor, requestor_type)
				.update(invocation_context)
invocation_context = InvocationContext.new(secret: "",  idempotent_request_key: "", x_opay_headers: "")

response = Payment.new(id_payment: "")
			.with_details(payment_amount_type: "", amount: "",
			  payment_date: "", payment_request_date: "", card_cvv_number: "")
			.for_customer(id_customer: "")
			.from_account(FundingAccount.new(id_funding_account: ""))
			.to_account(CustomerAccount.new(id_customer_account: ""))
			.with_memo(comments: "")
			.with_fee(Fee.new(fee_amount: ""))
			.with_custom_fields(custom_fields: {})
			.for_client(client_key: "")
			.vide_channel(channel: "")
			.updated_by(requestor: "", requestor_type: "")
			.update(invocation_context: invocation_context)

Request JSON

{
    "comments": "updating payment", 
    "custom_fields": { }, 
    "fee": {
        "fee_amount": "5.00"
    }, 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "payment_date": "2019-12-03", 
    "payment_request_date": "", 
    "payment_amount_type": "other", 
    "funding_account": {
        "id": "123456789"
    }
}

Example responses

{
    "id": "123456789", 
    "url": "/payments/{ID_PAYMENT}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "payment_date": "2019-12-03", 
    "payment_schedule_type": "one_time_payment", 
    "payment_request_date": "", 
    "payment_amount_type": "other", 
    "payment_reference": "PBruOrpMLl1dsBQ-1234567", 
    "expected_payment_settlement_date": "", 
    "payment_entry_date": "2019-12-03", 
    "payment_return_date": "", 
    "return_code": "", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}

PUT /customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}

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

Request content type: application/json 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}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  

Request Object

Attributes
comments
custom_fields
fee
fee_amount
amount
card_cvv_number
payment_date
payment_request_date
payment_amount_type
funding_account
id

Returns

The Payment with the id provided, duly updated.

Delete Payment

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

Payment deletePayment = new Payment(id)
                                                                 .forCustomer(id)
							         .deletedBy(requestorId, requestorType)
                                                                 .videChannel(channel)
							         .withMemo(comments)
							         .forClient(clientKey)
							         .delete(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentRequest = new Payment(ID_PAYMENT);
$response = $paymentRequest
	    ->forClient(client_key)
	    ->deletedBy(requestor, requestor_type)
	    ->videChannel(channel)
	    ->delete($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

Payment payment = new Payment(ID_PAYMENT)
                                          .ForCustomer(ID_CUSTOMER)
                                          .ForClient(client_key)
                                          .VideChannel(channel)
                                          .DeleteddBy(requestor, requestor_type)
                                          .Delete(invocationContext , invocation_mode, url);
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
            });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)
		
response = Payment(id_payment)
				.with_memo(comments)
				.for_customer(id_customer)
				.for_client(client_key)
				.vide_channel(channel)
				.deleted_by(requestor, requestor_type)
				.delete(invocation_context)
invocation_context = InvocationContext.new(secret: "",  idempotent_request_key: "", x_opay_headers: "")

response = Payment.new(id_payment: "")
		.with_memo(comments: "")
		.for_customer(id_customer: "")
		.for_client(client_key: "")
		.vide_channel(channel: "")
		.deleted_by(requestor: "", requestor_type: "")
		.delete(invocation_context: invocation_context)

Request JSON

{
    "comments": "deleting payment"
}

Example responses

{
    "deleted": "true", 
    "id": "string"
}

DELETE /customers/{ID_CUSTOMER}/payments/{ID_PAYMENT}

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

Request content type: application/json 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}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. 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.

Object JSON

{
    "id": "123456789", 
    "url": "/paymentsetups/{ID_PAYMENT_SETUP}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "payment_setup_schedule_type": "variable_recurring_enrollment", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "next_payment_date": "2019-12-03", 
    "payment_setup_reference": "1aQVAZ3kXTF0ocGgi_1212121", 
    "payment_schedule": {
        "payment_recurring_type": "monthly", 
        "payment_recurring_count": "10", 
        "payment_amount_type": "other", 
        "payment_start_date": "2019-12-03", 
        "payment_end_date": "", 
        "payment_limit_amount": "1000000", 
        "payment_plan_id": "", 
        "payment_defer_days": ""
    }, 
    "payment_setup_entry_date": "2019-12-03", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}
Attributes
idstring

The unique identifier assigned by Orbipay to the payment setup.

Max. Length: 20  Reg. 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: 1  Max. Length: 17  Reg. 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: 20  Reg. Exp.: [0-9]{0,20}  
urlstring

This URL fetches the details of fee as a payment resource. In case of split fee.

statusstring

The status of the payment.

Valid Values: scheduled, cancelled, processing, processed, returned, declined, disputed, refunded
payment_methodstring

The fulfillment method for the payment.

Valid Values: ach, check, visa_debit, pinless_debit, master_debit, amex_credit, discover_credit, visa_credit, master_credit, cash, discover_debit
payment_setup_schedule_typestring

The schedule type for the payment setup.

Valid Values: variable_recurring_enrollment, autopay_enrollment, payment_plan
confirmation_numberstring

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

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 '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: 1  Max. Length: 17  Reg. 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: 3  Max. Length: 4  Reg. 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: 10  Max. Length: 10  Date Format: YYYY-MM-DD  
payment_setup_referencestring

The unique identifier in the client system for the payment setup.

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

Valid Values: daily, weekly, monthly, bi_monthly, bi_weekly, quarterly, half_yearly, annual
payment_recurring_countstring

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: 1  Max. Length: 3  Reg. 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: 10  Max. Length: 10  Date 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: 10  Max. Length: 10  Date 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: 1  Max. Length: 17  Reg. 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: 9  Reg. 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: 1  Max. Length: 2  Reg. 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: 10  Max. Length: 10  Date Format: YYYY-MM-DD  
customerobject

The customer making the payment

idstring

The unique identifier assigned by Orbipay to the customer.

Max. Length: 20  Reg. Exp.: [0-9]{0,20}  
urlstring

The URL that can be used to fetch the details of the customer.

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 initial of the customer.

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

The email address of the customer.

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}  
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 state or province code as per ISO_3166-2.

Min. Length: 2  Max. Length: 2  Reg. Exp.: [a-zA-Z]{2}  
address_countrystring

The 3 letter country code as per ISO 3166-1 (alpha-3).

Min. Length: 3  Max. Length: 3  Reg. 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: 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.This is not applicable and will be ignored in the case of non-US addresses.

Min. Length: 4  Max. Length: 4  Reg. 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: 20  Reg. 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: 4  Max. Length: 32  Reg. 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.

Valid Values: savings, checking, money_market, visa_credit, mastercard_credit, american_express_credit, discover_credit, visa_debit, mastercard_debit, discover_debit
aba_routing_numberstring

The ABA/Routing number for the bank account.

Min. Length: 9  Max. Length: 9  Reg. Exp.: [0-9]{9}  
customer_accountobject

The customer account against which the payment is being made.

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

var 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 index

var 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)

Example responses

{
    "list": [
        {
            "id": "123456789", 
            "url": "/paymentsetups/{ID_PAYMENT_SETUP}", 
            "fee": {
                "fee_type": "add_to_principal", 
                "fee_amount": "5.00", 
                "id": "123456789", 
                "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
            }, 
            "status": "scheduled", 
            "payment_method": "ach", 
            "payment_setup_schedule_type": "variable_recurring_enrollment", 
            "confirmation_number": "A12N12I12L", 
            "custom_fields": { }, 
            "currency_code3d": "USD", 
            "amount": "101.05", 
            "card_cvv_number": "", 
            "next_payment_date": "2019-12-03", 
            "payment_setup_reference": "1aQVAZ3kXTF0ocGgi_1212121", 
            "payment_schedule": {
                "payment_recurring_type": "monthly", 
                "payment_recurring_count": "10", 
                "payment_amount_type": "other", 
                "payment_start_date": "2019-12-03", 
                "payment_end_date": "", 
                "payment_limit_amount": "1000000", 
                "payment_plan_id": "", 
                "payment_defer_days": ""
            }, 
            "payment_setup_entry_date": "2019-12-03", 
            "customer": {
                "id": "12684515", 
                "url": "/customers/{ID_CUSTOMER}", 
                "first_name": "Michael", 
                "last_name": "Smith", 
                "middle_name": "S", 
                "email": "userid@example.com", 
                "home_phone": "1234567890", 
                "address": {
                    "address_line1": "1551 South Washington Ave", 
                    "address_line2": "Suite 130 Piscataway", 
                    "address_city": "Piscataway", 
                    "address_state": "NJ", 
                    "address_country": "USA", 
                    "address_zip1": "12345", 
                    "address_zip2": "1234"
                }
            }, 
            "funding_account": {
                "id": "123456789", 
                "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
                "account_number": "xxxxx0206", 
                "account_type": "bank", 
                "account_subtype": "savings", 
                "aba_routing_number": "123456789"
            }, 
            "customer_account": {
                "id": "123456789", 
                "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
            }
        }
    ], 
    "total_results_count": "1", 
    "has_more_results": "false", 
    "url": "/paymentsetups?query_id=vu68cakbhjaksgasd", 
    "from_index": "1", 
    "to_index": "1"
}

GET /paymentsetups

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: 20  Reg. Exp.: [0-9]{1,20}  
  • id_funding_accountstringin: query
  • The unique identifier assigned by Orbipay to the funding account
  • 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]+  
  • statusstringin: query
  • The status of the payment. This can take multiple values in the format key=value1&key=value2....
  • Valid Values: scheduled, cancelled, processing, processed, returned, declined, disputed, refunded
  • payment_setup_schedule_typestringin: query
  • The schedule type for the payment setup. This can take multiple values in the format key=value1&key=value2....
  • Valid Values: variable_recurring_enrollment, autopay_enrollment, payment_plan
  • from_datestringin: query
  • The date from which recurring payments setup, matching the criteria specified, need to be retrieved.
  • Date Format: YYYY-MM-DD  
  • to_datestringin: query
  • The date upto which recurring payments setup, 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 recurring payments setup matching the criteria provided, the total results count and the urls to get the next/previous pages.

Create Payment Setup

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

PaymentSetup paymentSetup = new PaymentSetup(amount, cardCVVNumber, ... paymentSetupScheduleType)
                                                                              .withFee(new Fee(feeAmount))
									      .withPaymentSchedule(new PaymentSchedule(paymentRecurringType, ... paymentDeferDays))
                                                                              .forCustomer(id)
									      .fromAccount(new FundingAccount(id))
									      .toAccount(new CustomerAccount(id))
									      .createdBy(requestorId, requestorType)
                                                                              .videChannel(channel)
                                                                              .withMemo(comments)
									      .forClient(clientKey)
									      .create(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentSetupRequest = new PaymentSetup();
$response = $paymentSetupRequest
		    ->withDetails(amount, .., payment_setup_schedule_type)
		    ->withReference(payment_Setup_reference)
		    ->forCustomer(ID_CUSTOMER)
		    ->fromAccount(new FundingAccount(ID_FUNDING_ACCOUNT))
		    ->toAccount(new CustomerAccount(ID_CUSTOMER_ACCOUNT))
		    ->withPaymentSchedule(new PaymentSchdule(payment_recurring_type, ..., payment_defer_days))
		    ->withMemo(comments)
		    ->forClient(client_key)
		    ->createdBy(requestor, requestor_type)
		    ->videChannel(channel)
		    ->create($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

PaymentSchedule payment_schedule =  new ( payment_recurring_type , payment_recurring_count ,  payment_amount_type , payment_start_date , payment_end_date , payment_limit_amount , payment_plan_id , payment_defer_days);

PaymentSetup paymentSetup = new PaymentSetup()
                                                                   .WithReference(payment_setup_reference)
                                                                   .WithDetails(amount, card_cvv_number, payment_setup_schedule_type)
                                                                   .WithPaymentSchedule(payment_schedule)
                                                                   .WithFee(new Fee(fee_amount))
                                                                   .WithMemo(comments)
                                                                   .WithCustomFields(custom_fields)
                                                                   .FromAccount(new FundingAccount(id))
                                                                   .ToAccount(new CustomerAccount(id))
                                                                   .ForClient(client_key)
                                                                   .ForCustomer(ID_CUSTOMER)
                                                                   .VideChannel(channel)
                                                                   .CreatedBy(requestor, requestor_type)
                                                                   .Create(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');

var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);

new Orbipay.PaymentSetup()
    .withDetails(amount, card_cvv_number, payment_setup_schedule_type)
    .withCustomFields(custom_fields)
    .withFee(new Orbipay.Fee(fee_amount))
    .withPaymentSchedule(new Orbipay.PaymentSchedule(payment_recurring_type, ..., payment_defer_days))
    .withReference(payment_setup_reference)
    .withMemo(comments)
    .fromAccount(new Orbipay.FundingAccount(id_funding_account))
    .toAccount(new Orbipay.CustomerAccount(id_customer_account))
    .forCustomer(id_customer)
    .createdBy(requestor, requestor_type)
    .videChannel(channel)
    .forClient(client_key)
    .create(invocationContext, function(exception, paymentsetup) {
  	// asynchronously called
    });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = PaymentSetup()
				.with_details(amount, card_cvv_number, payment_setup_schedule_type)
				.with_reference(payment_setup_reference)
				.with_payment_schedule(PaymentSchedule(payment_recurring_type, 
				  payment_recurring_count, payment_amount_type, payment_start_date, 
				  payment_end_date, payment_limit_amount, payment_plan_id, payment_defer_days))
				.for_customer(id_customer)
				.from_account(FundingAccount(id_funding_account))
				.to_account(CustomerAccount(id_customer_account))
				.with_memo(comments)
				.with_fee(Fee(fee_amount))
				.with_custom_fields(custom_fields)
				.for_client(client_key)
				.vide_channel(channel)
				.created_by(requestor, requestor_type)
				.create(invocation_context)
invocation_context = InvocationContext.new(secret: "",  idempotent_request_key: "", x_opay_headers: "")

response = PaymentSetup.new
			.with_details(amount: "", card_cvv_number: "", payment_setup_schedule_type: "")
			.with_reference(payment_setup_reference: "")
			.with_payment_schedule(PaymentSchedule.new(payment_recurring_type: "",
			  payment_recurring_count: "", payment_amount_type: "", payment_start_date: "",
			  payment_end_date: "", payment_limit_amount: "", payment_plan_id: "", payment_defer_days: ""))
			.for_customer(id_customer: "")
			.from_account(FundingAccount.new(id_funding_account: ""))
			.to_account(CustomerAccount.new(id_customer_account: ""))
			.with_memo(comments: "")
			.with_fee(Fee.new(fee_amount: ""))
			.with_custom_fields(custom_fields: {})
			.for_client(client_key: "")
			.vide_channel(channel: "")
			.created_by(requestor: "", requestor_type: "")
			.create(invocation_context: invocation_context)

Request JSON

{
    "payment_setup_reference": "1aQVAZ3kXTF0ocGgi_1212121", 
    "payment_setup_schedule_type": "variable_recurring_enrollment", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "fee": {
        "fee_amount": "5.00"
    }, 
    "customer": {
        "id": "12684515"
    }, 
    "funding_account": {
        "id": "123456789"
    }, 
    "customer_account": {
        "id": "123456789"
    }, 
    "payment_schedule": {
        "payment_recurring_type": "monthly", 
        "payment_recurring_count": "10", 
        "payment_amount_type": "other", 
        "payment_start_date": "2019-12-03", 
        "payment_end_date": "", 
        "payment_limit_amount": "1000000", 
        "payment_plan_id": "", 
        "payment_defer_days": ""
    }, 
    "custom_fields": { }, 
    "comments": "string"
}

Example responses

{
    "id": "123456789", 
    "url": "/paymentsetups/{ID_PAYMENT_SETUP}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "payment_setup_schedule_type": "variable_recurring_enrollment", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "next_payment_date": "2019-12-03", 
    "payment_setup_reference": "1aQVAZ3kXTF0ocGgi_1212121", 
    "payment_schedule": {
        "payment_recurring_type": "monthly", 
        "payment_recurring_count": "10", 
        "payment_amount_type": "other", 
        "payment_start_date": "2019-12-03", 
        "payment_end_date": "", 
        "payment_limit_amount": "1000000", 
        "payment_plan_id": "", 
        "payment_defer_days": ""
    }, 
    "payment_setup_entry_date": "2019-12-03", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}

POST /customers/{ID_CUSTOMER}/paymentsetups

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

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

Request Parameters

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

Request Object

Attributes
payment_setup_reference
payment_setup_schedule_typerequired
amount
card_cvv_number
fee
fee_amount
customerrequired
idrequired
funding_accountrequired
idrequired
customer_accountrequired
idrequired
payment_schedulerequired
payment_recurring_type
payment_recurring_count
payment_amount_type
payment_start_date
payment_end_date
payment_limit_amount
payment_plan_id
payment_defer_days
custom_fields
comments

Returns

The payment setup

Get Payment Setup

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

PaymentSetup getPaymentSetup = new PaymentSetup(id)
									           .forCustomer(id)
                                                                                   .forClient(clientKey)
									           .retrievedBy(requestorId, requestorType)
                                                                                   .videChannel(channel)
									  	   .get(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentSetupRequest = new PaymentSetup(ID_PAYMENT_SETUP);
$response = $paymentSetupRequest
	    ->forClient(client_key)
	    ->retrievedBy(requestor, requestor_type)
	    ->videChannel(channel)
	    ->get($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

PaymentSetup paymentSetup = new PaymentSetup(ID_PAYMENT_SETUP)
                                                                   .ForCustomer(ID_CUSTOMER)
                                                                   .ForClient(client_key)
                                                                   .VideChannel(channel)
                                                                   .RetrievedBy(requestor, requestor_type)
                                                                   .Get(invocationContext , invocation_mode, url);
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
            });
invocation_context = InvocationContext(secret, idempotent_request_key, 
		x_opay_headers)

response = PaymentSetup(id_payment_setup)
				.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 = PaymentSetup.new(id_payment_setup: "")
			.for_customer(id_customer: "")
			.for_client(client_key: "")
			.vide_channel(channel: "")
			.retrieved_by(requestor: "", requestor_type: "")
			.get(invocation_context: invocation_context)

Example responses

{
    "id": "123456789", 
    "url": "/paymentsetups/{ID_PAYMENT_SETUP}", 
    "fee": {
        "fee_type": "add_to_principal", 
        "fee_amount": "5.00", 
        "id": "123456789", 
        "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
    }, 
    "status": "scheduled", 
    "payment_method": "ach", 
    "payment_setup_schedule_type": "variable_recurring_enrollment", 
    "confirmation_number": "A12N12I12L", 
    "custom_fields": { }, 
    "currency_code3d": "USD", 
    "amount": "101.05", 
    "card_cvv_number": "", 
    "next_payment_date": "2019-12-03", 
    "payment_setup_reference": "1aQVAZ3kXTF0ocGgi_1212121", 
    "payment_schedule": {
        "payment_recurring_type": "monthly", 
        "payment_recurring_count": "10", 
        "payment_amount_type": "other", 
        "payment_start_date": "2019-12-03", 
        "payment_end_date": "", 
        "payment_limit_amount": "1000000", 
        "payment_plan_id": "", 
        "payment_defer_days": ""
    }, 
    "payment_setup_entry_date": "2019-12-03", 
    "customer": {
        "id": "12684515", 
        "url": "/customers/{ID_CUSTOMER}", 
        "first_name": "Michael", 
        "last_name": "Smith", 
        "middle_name": "S", 
        "email": "userid@example.com", 
        "home_phone": "1234567890", 
        "address": {
            "address_line1": "1551 South Washington Ave", 
            "address_line2": "Suite 130 Piscataway", 
            "address_city": "Piscataway", 
            "address_state": "NJ", 
            "address_country": "USA", 
            "address_zip1": "12345", 
            "address_zip2": "1234"
        }
    }, 
    "funding_account": {
        "id": "123456789", 
        "url": "/fundingaccounts/{ID_FUNDING_ACCOUNT}", 
        "account_number": "xxxxx0206", 
        "account_type": "bank", 
        "account_subtype": "savings", 
        "aba_routing_number": "123456789"
    }, 
    "customer_account": {
        "id": "123456789", 
        "url": "/customeraccounts/{ID_CUSTOMER_ACCOUNT}"
    }
}

GET /customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}

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

Response content type: application/json

Request Parameters

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

Returns

The payment setup with the id provided.

Delete Payment Setup

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

PaymentSetup paymentSetup = new PaymentSetup(id)
                                                                          .forCustomer(id)
									  .deletedBy(requestorId, requestorType)
                                                                          .videChannel(channel)
                                                                          .withMemo(memo)
									  .forClient(clientKey)
									  .delete(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$paymentSetupRequest = new PaymentSetup(ID_PAYMENT_SETUP);
$response = $paymentSetupRequest
	    ->forClient(client_key)
	    ->deletedBy(requestor, requestor_type)
	    ->videChannel(channel)
	    ->delete($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

PaymentSetup paymentSetup = new PaymentSetup(ID_PAYMENT_SETUP)
                                                                   .ForCustomer(ID_CUSTOMER)
                                                                   .ForClient(client_key)
                                                                   .VideChannel(channel)
                                                                   .DeleteddBy(requestor, requestor_type)
                                                                   .Delete(invocationContext , invocation_mode, url);
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
            });
invocation_context = InvocationContext(secret, idempotent_request_key, 
                 x_opay_headers)

response = PaymentSetup(id_payment_setup)
				.for_customer(id_customer)
				.with_memo(comments)
				.for_client(client_key)
				.deleted_by(requestor, requestor_type)
				.vide_channel(channel)
				.delete(invocation_context)
invocation_context = InvocationContext.new(secret: "",  idempotent_request_key: "", x_opay_headers: "")

response = PaymentSetup.new(id_payment_setup: "")
			.for_customer(id_customer: "")
			.with_memo(comments: "")
			.for_client(client_key: "")
			.vide_channel(channel: "")
			.deleted_by(requestor: "", requestor_type: "")
			.delete(invocation_context: invocation_context)

Request JSON

{
    "comments": "string"
}

Example responses

{
    "deleted": "true", 
    "id": "string"
}

DELETE /customers/{ID_CUSTOMER}/paymentsetups/{ID_PAYMENT_SETUP}

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

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

Request Parameters

  • ID_PAYMENT_SETUPstringin: path required
  • The unique identifier assigned by Orbipay to the payment setup.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. 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.

Object JSON

{
    "refund_reference": "aQV1A2Z6kXTF70ocGgi_1317", 
    "id": "123456789", 
    "url": "/refunds/{ID_REFUND}", 
    "refund_type": "payment_and_fee", 
    "refund_amount": "101.05", 
    "fee_refund": {
        "fee_refund_amount": "5.00", 
        "fee_type": "add_to_principal"
    }, 
    "status": "scheduled", 
    "confirmation_number": "A12N12I12L", 
    "expected_refund_settlement_date": "2019-12-03", 
    "custom_fields": { }, 
    "source_payment": {
        "id": "12684515", 
        "url": "/payments/{ID_PAYMENT}"
    }
}
Attributes
refund_referencestring

The unique identifier in the client system for the refund.

Max. Length: 50  Reg. Exp.: [0-9a-zA-Z._-]{0,50}  
idstring

The unique identifier assigned by Orbipay to the refund.

Max. Length: 20  Reg. 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: 1  Max. Length: 17  Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$  
fee_refundobject
fee_refund_amountstring

The refunded fee amount upto 2 decimal places.

Min. Length: 1  Max. Length: 17  Reg. Exp.: ^[0-9]{1,14}(\.[0-9][0-9]?)?$  
fee_typestring

The way the fee is being charged to the customer. Fee could be added to the amount being paid, or, it could be charged separately by the biller. The fee_type would default to add_to_principal if the fee is not configured for the client in Orbipay.

Valid Values: add_to_principal, bill_separately
statusstring

The status of the refund.

Valid Values: scheduled, processing, processed, declined
confirmation_numberstring

The confirmation number or reference provided to the customer for the refund.

Max. Length: 30  Reg. 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: 10  Max. Length: 10  Date Format: YYYY-MM-DD  
custom_fieldsmap

The additional information or meta-information that Orbipay can accept, maintain and transmit back to the client. The custom fields need to be configured with Orbipay before they can be accepted. Orbipay would reject custom fields that are not pre-configured. Please contact support@billerpayments.com for more information on configuring and using custom fields.

source_paymentobject
idstring
Max. Length: 20  Reg. Exp.: [0-9]{0,20}  
urlstring

This URL fetches the details of source payment.

Create Refund

InvocationContext invocationContext = new InvocationContext(secret, idempotentKey, attributes);

Refund refund = new Refund(refundReference , refundType, amount, customFields)
                                         .createdBy(requestorId, requestorType)
                                         .videChannel(channel)
                                         .forCustomer(id)
                                         .forPayment(id)
                                         .withMemo(memo)
					 .forClient(clientKey)
                                         .create(invocationContext);
$invocation_context = new InvocationContext(idempotent_request_key, secret, attributes);
$response = $refund
		    ->withDetails(refund_type, amount)
		    ->withReference(refund_reference)
		    ->withMemo(comments)
		    ->forCustomer(ID_CUSTOMER)
		    ->forPayment(ID_PAYMENT)
		    ->forClient(client_key)
		    ->createdBy(requestor, requestor_type)
		    ->videChannel(channel)
		    ->create($invocation_context);
InvocationContext invocationContext = new InvocationContext(secret, idempotent_request_key, attributes);

 Refund refundResp = new Refund()
                                             .WithReference(refund_reference)
                                             .WithDetails(refund_type,refund_amount)
                                             .WithCustomFields(custom_fields)
                                             .WithMemo(comments)
                                             .ForClient(client_key)
                                             .ForPayment(ID_PAYMENT)
                                             .ForCustomer(ID_CUSTOMER)
                                             .VideChannel(channel)
                                             .CreatedBy(requestor, requestor_type)
                                             .Create(invocationContext , invocation_mode, url);
var Orbipay = require('orbipay-paymentsapi-client');

var invocationContext = new Orbipay.InvocationContext(idempotent_request_key, secret, attributes);

new Orbipay.Refund()
		    .withDetails(refund_type, amount)
		    .withReference(refund_reference)
		    .withMemo(comments)
		    .forCustomer(ID_CUSTOMER)
		    .forPayment(ID_PAYMENT)
		    .forClient(client_key)
		    .createdBy(requestor, requestor_type)
		    .videChannel(channel)
		    .create(invocationContext, function(exception, paymentsetup) {
  	                      // asynchronously called
                    });
invocation_context = InvocationContext(secret,  idempotent_request_key, 
                  x_opay_headers)

response = Refund()
				.with_details(refund_type, refund_amount)
				.with_reference(refund_reference)
				.for_customer(id_customer)
				.with_memo(comments)
				.with_custom_fields(custom_fields)
				.for_payment(id_payment)
				.for_client(client_key)
				.created_by(requestor, requestor_type)
				.vide_channel(channel)
				.create(invocation_context)
invocation_context = InvocationContext.new(secret: "",  idempotent_request_key: "", x_opay_headers: "")

response = Refund.new
		.with_details(refund_type: "", refund_amount: "")
		.with_reference(refund_reference: "")
		.for_customer(id_customer: "")
		.with_memo(comments: "")
		.with_custom_fields(custom_fields: {})
		.for_payment(id_payment: "")
		.for_client(client_key: "")
		.vide_channel(channel: "")
		.created_by(requestor: "", requestor_type: "")
		.create(invocation_context: invocation_context)

Request JSON

{
    "refund_reference": "aQV1A2Z6kXTF70ocGgi_1317", 
    "refund_type": "payment_and_fee", 
    "refund_amount": "", 
    "comments": "initiating refund", 
    "custom_fields": { }
}

Example responses

{
    "refund_reference": "aQV1A2Z6kXTF70ocGgi_1317", 
    "id": "123456789", 
    "url": "/refunds/{ID_REFUND}", 
    "refund_type": "payment_and_fee", 
    "refund_amount": "101.05", 
    "fee_refund": {
        "fee_refund_amount": "5.00", 
        "fee_type": "add_to_principal"
    }, 
    "status": "scheduled", 
    "confirmation_number": "A12N12I12L", 
    "expected_refund_settlement_date": "2019-12-03", 
    "custom_fields": { }, 
    "source_payment": {
        "id": "12684515", 
        "url": "/payments/{ID_PAYMENT}"
    }
}

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.

Request content type: application/json 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}  
  • ID_CUSTOMERstringin: path required
  • The unique identifier assigned by Orbipay to the customer.
  • Max. Length: 20  Reg. Exp.: [0-9]{1,20}  

Request Object

Attributes
refund_reference
refund_typerequired
refund_amount
comments
custom_fields

Returns

The refund object with confirmation number, id, status, expected settlement date and corresponding payment reference.