Faster Payouts for Platforms (1.0)

Contact: support@billerpayments.com License: © Alacriti Inc

Authentication

Overview

The requests are authenticated using the api_key which is shared with the client at the time of client on-boarding. The client can only invoke those APIs based on the permissions assigned to the api_key

OPAY1-HMAC-SHA256

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 api key
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

Error Handling

HTTP Codes

The Faster Payouts API uses the standard HTTP response codes to return the status of an API call. An HTTP response code of 2xx indicates success. An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, the API returns a list of errors.

Error Codes

Each error in the list has a code, message, and specifics on which field the error pertains to (if applicable). In addition to these details, it can also have a list of inner errors that caused this error, on the lines of an Exception Stack trace.

Below table specifies the Error category and Error code.

Error Category	Code
Validation Error	FP-10-XXXXXX.
Business Error	FP-20-XXXXXX.
System Error	FP-50-XXXXXX.

         // format
      {
         "error": [
             {
                 "code": "FP-10-XXXXXX",
                 "message": "Error message"
             }
         ]
     }

The following table lists the business errors that need to be handled by the client.

Error Code	Description
FP-20-290001	Payment rejected by the bank or clearing network.
FP-20-290003	Creditor account is blocked by the creditor FI.
FP-20-290004	Creditor account does not exist.
FP-20-290005	Encountered technical difficulty that may clear later. Please try later.
FP-20-290006	Transaction amount is more than allowed.
FP-20-290007	Transaction amount is less than the minimum allowed.

Duplicate Requests and Retries

The Faster Payouts API supports 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 the API 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 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.

Hypermedia

As per REST guidelines, Faster Payouts API supports hypermedia. This allows for simple and intuitive navigation between the resources, making it easy to fetch associated metadata for any given resource.

Payouts

Create Simple Payout

query Parameters

name_match

string

Indicates card account name match strategy to be followed.
Possible Values :
strict complete name match only.
lenient complete or partial name match, name match not supported for card.
ignore name match not required. default

header Parameters

client_key required	any The unique identifier assigned to the client. Example:`CLIAAADDD0910`
product required	any The product identifier corresponding to the API. Possible values:`payouts`
payment_channel required	any The FI channel vide which the API is invoked. Possible values:`online,hosted_portal`
access_channel	any This is internal channel through which the API is invoked. Example:`web_portal, agent`
requestor_type required	any Identifies the requestor type for the API request. Possible values:`party, client_agent, external_agent`
client_requestor_reference	any The identifier for the requestor of the API, in the client system. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
requestor	any The identifier for the requestor of the API issued by Orbipay. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
context_variant	any To be used if there's a need to provide additional contextual information. For future use.
idempotent_request_key required	any The unique token that clients can generate and maintain in order to identify an API request. This is used to identify duplicate requests and retrials. Example:`6bc5f0f49ee2412a93b0596d6a3c4eca`
X-PAAS-Headers	any For additional context information such as end user IP address, session information and so on. The content is a list of key-value pairs separated by semicolon (;) where key and value are separated by equals sign(=). Example:`session=SADKAS2131312;ip_address=10.112.25.45`
processing_mode	string Indicates whether the transaction will be processed synchronously or asynchronously, in a non-blocking fashion. Possible Values : synchronous The transaction will be processed in a blocking fashion. default asynchronous The transaction will be processed in a non-blocking fashion.
timestamp required	any The UTC datetime when the API is invoked, in the ISO 8601 format Example:`2020-09-18T17:31:34.000-05:30`

Request Body Schema: application/json

source

required

object

The details of the Payer of funds or debtor. This could be different from the entity originating the payout.

original_source

object

The name of the actual payer or the ultimate debtor.

destination

object

The recipient of funds or the creditor.

ultimate_destination

object

The actual recipient of funds or the ultimate creditor. This could be different from the entity whose account is being credited.

destination_account

required

bank_account (object) or card_account (object)

Indicates the recipient account of the payout.

amount

required

object

The amount being transfered from the source account to the destination account.

fulfilment_type

string

Enum: "instant" "regular" "instant.TCH_RTP" "instant.FEDNOW" "instant.CARD_VISA" "urgent.FEDWIRE" "regular.ACH"

end_to_end_reference

required

string [ 1 .. 35 ] characters

The reference for the payment that is passed on from the initiator to the recipient. This is the reference that traces the entire flow of the payment. However, please note that certain payment rails do not support an end to end reference.The maximum length for the end_to_end_reference varies across different payment rails and is outlined below

Payment Method	Max Length
RTP	35
FEDNOW	35
FEDWIRE	16
ACH	15

payment_reference

required

string [ 0 .. 16 ] characters [0-9a-zA-Z._-]{0,16}

The unique identifier that the client might want to assign for the payout.

purpose

object

Indicates purpose of the payemnt.

remittance_info

object

Information supplied to enable the matching/reconciliation of an entry with the item(s) that the payout is intended to settle, such as bills or RFPs received.

Responses

201

The Payout object with confirmation number and id issued by Faster Payouts.

400

Bad Request

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed.

500

Something went wrong and the request could not be processed.

502

Server Error.

Events

Following events are triggered in the context of this API

fasterpayouts.payout.status_updated

post/payouts/simplepayout

https://api.orbipay.com/fasterpayouts/v1/payouts/simplepayout

Java

Please click on a language icon above to try out the API

Request samples

Content type

application/json

Copy

Expand all Collapse all


{"source": 
{"id": "FP-****-**0",
"name": "Michael",
"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"
}
},
"original_source": 
{"name": "Michael",
"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"
}
},
"destination": 
{"name": "Michael",
"email": "userid@example.com",
"phone": "1234567890"
},
"ultimate_destination": 
{"name": "Michael",
"email": "userid@example.com",
"phone": "1234567890"
},
"destination_account": 
{"name_on_account": "Michael Smith",
"routing_number": "123456789",
"account_number": "123450206",
"account_sub_type": "savings"
},
"amount": 
{"value": "101.05",
"currency": "string"
},
"fulfilment_type": "instant",
"end_to_end_reference": "string",
"payment_reference": "string",
"purpose": 
{"code": "string",
"description": "string"
},
"remittance_info": 
{"comment": "string",
"additional_info": 
[
{"document_reference": "string",
"document_type": "RPIN",
"document_date": "stringstri",
"document_amounts": 
[
{"amount_type": "due_payable_amount",
"value": "101.05",
"currency": "string"
}
]
}
]
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": "string",
"confirmation_number": "string",
"url": "string",
"source": 
{"id": "FP-****-**0",
"name": "Michael",
"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"
}
},
"original_source": 
{"name": "Michael",
"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"
}
},
"destination": 
{"name": "Michael",
"email": "userid@example.com",
"phone": "9012345678"
},
"ultimate_destination": 
{"name": "Michael",
"email": "userid@example.com",
"phone": "1234567890"
},
"destination_account": 
{"name_on_account": "Michael Smith",
"routing_number": "123456789",
"account_number": "123450206",
"account_sub_type": "savings"
},
"amount": 
{"value": "101.05",
"currency": "string"
},
"fulfilment_type": "instant",
"end_to_end_reference": "string",
"payment_reference": "string",
"remittance_info": 
{"comment": "string",
"additional_info": 
[
{"document_reference": "string",
"document_type": "RPIN",
"document_date": "stringstri",
"document_amounts": 
[
{"amount_type": "due_payable_amount",
"value": "101.05",
"currency": "string"
}
]
}
]
},
"payment_date": "stringstri",
"status": "success",
"initiation_type": "push",
"payment_orientation": "sent",
"payment_method": "TCH_RTP",
"status_reason_info": 
{"reason_code": "string",
"additional_info": "string"
}
}

Common

Get Payment Status

Get Payment Status API returns the current status of payment.

header Parameters

client_key required	any The unique identifier assigned to the client. Example:`CLIAAADDD0910`
product required	any The product identifier corresponding to the API. Possible values:`payouts`
payment_channel required	any The FI channel vide which the API is invoked. Possible values:`online,hosted_portal`
access_channel	any This is internal channel through which the API is invoked. Example:`web_portal, agent`
requestor_type required	any Identifies the requestor type for the API request. Possible values:`party, client_agent, external_agent`
client_requestor_reference	any The identifier for the requestor of the API, in the client system. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
requestor	any The identifier for the requestor of the API issued by Orbipay. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
context_variant	any To be used if there's a need to provide additional contextual information. For future use.
idempotent_request_key required	any The unique token that clients can generate and maintain in order to identify an API request. This is used to identify duplicate requests and retrials. Example:`6bc5f0f49ee2412a93b0596d6a3c4eca`
timestamp required	any The UTC datetime when the API is invoked, in the ISO 8601 format Example:`2020-09-18T17:31:34.000-05:30`
X-PAAS-Headers	any For additional context information such as end user IP address, session information and so on. The content is a list of key-value pairs separated by semicolon (;) where key and value are separated by equals sign(=). Example:`session=SADKAS2131312;ip_address=10.112.25.45`

Request Body Schema: application/json

payment_reference	string [ 1 .. 16 ] characters [0-9a-zA-Z_-]{1,16} The unique identifier that the bank might want to assign for the payment. Constraints: CMM11
id	string The unique identifier assigned by Unified Money Movement Services to payment. Constraints: CMM11

Responses

201

The Payment object with id and confirmation mumber issued by Unified Money Movement Services.

400

Bad Request

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed.

500

Something went wrong and the request could not be processed.

502

Server Error.

post/status/getpaymentstatus

https://api.orbipay.com/fasterpayouts/v1/status/getpaymentstatus

Java

Please click on a language icon above to try out the API

Request samples

Content type

application/json

Copy

Expand all Collapse all


{"payment_reference": "string",
"id": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"payment_reference": "string",
"id": "string",
"confirmation_number": "string",
"status": "success",
"status_reason_info": 
{"reason_code": "string",
"additional_info": "string"
}
}

Ancillary

Get Routing Details

The API is used to get information on the Routing and Transit Number. It returns the details of the corresponding Participant in the RTP Network, the RTP messages that it supports and the current status of the participant.

path Parameters

routing_number

required

string

The Routing Number for which the real-time capabilities need to be checked.

header Parameters

client_key required	any The unique identifier assigned to the client. Example:`CLIAAADDD0910`
product required	any The product identifier corresponding to the API. Possible values:`payouts`
payment_channel required	any The FI channel vide which the API is invoked. Possible values:`online,hosted_portal`
access_channel	any This is internal channel through which the API is invoked. Example:`web_portal, agent`
requestor_type required	any Identifies the requestor type for the API request. Possible values:`party, client_agent, external_agent`
client_requestor_reference	any The identifier for the requestor of the API, in the client system. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
requestor	any The identifier for the requestor of the API issued by Orbipay. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
context_variant	any To be used if there's a need to provide additional contextual information. For future use.
idempotent_request_key required	any The unique token that clients can generate and maintain in order to identify an API request. This is used to identify duplicate requests and retrials. Example:`6bc5f0f49ee2412a93b0596d6a3c4eca`
timestamp required	any The UTC datetime when the API is invoked, in the ISO 8601 format Example:`2020-09-18T17:31:34.000-05:30`
X-PAAS-Headers	any For additional context information such as end user IP address, session information and so on. The content is a list of key-value pairs separated by semicolon (;) where key and value are separated by equals sign(=). Example:`session=SADKAS2131312;ip_address=10.112.25.45`

Responses

200

The Routing number with the details of the corresponding Participant in the RTP Network is provided.

400

Bad Request

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed.

500

Something went wrong and the request could not be processed.

502

Server Error.

get/rtp/rtn/{routing_number}

https://api.orbipay.com/fasterpayouts/v1/rtp/rtn/{routing_number}

Java

Please click on a language icon above to try out the API

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"routing_number": "011401533",
"participants": 
[
{"network": "TCH_RTP",
"participant_name": "FI Branch",
"financial_institution": "FI sample",
"receive_services": "CRDT, RFP, ACK, RMT, RFI, RFRF, RFPR, RFIR, RFRFR",
"status": "online"
}
]
}

Verify Card Details

The API is used to validate a card for payout

query Parameters

name_match

string

header Parameters

client_key required	any The unique identifier assigned to the client. Example:`CLIAAADDD0910`
product required	any The product identifier corresponding to the API. Possible values:`payouts`
payment_channel required	any The FI channel vide which the API is invoked. Possible values:`online,hosted_portal`
access_channel	any This is internal channel through which the API is invoked. Example:`web_portal, agent`
requestor_type required	any Identifies the requestor type for the API request. Possible values:`party, client_agent, external_agent`
client_requestor_reference	any The identifier for the requestor of the API, in the client system. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
requestor	any The identifier for the requestor of the API issued by Orbipay. Either the client_requestor_reference or the requestor has to be available in every API request for audit purposes.
context_variant	any To be used if there's a need to provide additional contextual information. For future use.
idempotent_request_key required	any The unique token that clients can generate and maintain in order to identify an API request. This is used to identify duplicate requests and retrials. Example:`6bc5f0f49ee2412a93b0596d6a3c4eca`
timestamp required	any The UTC datetime when the API is invoked, in the ISO 8601 format Example:`2020-09-18T17:31:34.000-05:30`
X-PAAS-Headers	any For additional context information such as end user IP address, session information and so on. The content is a list of key-value pairs separated by semicolon (;) where key and value are separated by equals sign(=). Example:`session=SADKAS2131312;ip_address=10.112.25.45`

Request Body Schema: application/json

card_account

required

object

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

The requested resource doesn't exist.

422

The parameters were valid but the request failed.

500

Something went wrong and the request could not be processed.

502

Server Error.

post/card/verify

https://api.orbipay.com/fasterpayouts/v1/card/verify

Java

Please click on a language icon above to try out the API

Request samples

Content type

application/json

Copy

Expand all Collapse all


{"card_account": 
{"last_name": "Michael",
"first_name": "Smith",
"middle_name": "Smith",
"owner_type": 1,
"card_number": "string",
"expiry_date": "string",
"cvv": "",
"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"
}
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"card_account": 
{"last_name": "Michael",
"first_name": "Smith",
"middle_name": "Smith",
"owner_type": 1,
"card_number": "string",
"expiry_date": "string",
"cvv": "",
"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"
}
},
"verification_result": 
{"status": "approved",
"name_match_result_code": "string",
"services_supported": 
[
[
{"key": null,
"value": null
}
]
],
"status_reason_info": 
{"reason_code": "string",
"additional_info": "string"
}
}
}

Faster Payouts for Platforms (1.0)

Authentication

OPAY1-HMAC-SHA256

Error Handling

Duplicate Requests and Retries

Hypermedia

Pagination

Payouts

Create Simple Payout

query Parameters

header Parameters

Request Body Schema: application/json

Responses

Events

Request samples

Response samples

Common

Get Payment Status

header Parameters

Request Body Schema: application/json

Responses

Request samples

Response samples

Ancillary

Get Routing Details

path Parameters

header Parameters

Responses

Response samples

Verify Card Details

query Parameters

header Parameters

Request Body Schema: application/json

Responses

Request samples

Response samples