Hosted Forms is an enabler that's available on the Orbipay platform. It provides an easy way to integrate Orbipay payments with client website, thereby obviating the need for PCI compliance. It does so by creating secure tokens for each payment request, that can be used only once. Hosted Forms comes with an SDK that simplifies the client integration. The SDK comes in various languages like Java, Python, C#, Node.js and PHP.
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
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¶m2=value2&…, where the query parameters are sorted in alphabetical order of the parameter names. In case multiple values are present for a parameter, the query parameters are sorted in alphabetical order of the parameter names and subsequently by the parameter values for each such paramter. Both the parameter names and their values should be trimmed for leading and trailing whitespaces, should be in their normal pre-encoded format. Only parameters with non-empty values, after trimming the leading and trailing whitespaces, should be included. If there are no query parameters at all, the queryString() should evaluate to an empty string (“”). |
headers() | A string in the format header1=value1&header2=value2&.......&headerN=valueN. The headers are to be sorted alphabetically. Both the header names and their values must be trimmed for leading and trailing white-space, and in their normal pre-encoded format . Only the headers listed by the application and those that are non-empty, after trimming the leading and trailing whitespaces, are to be included. |
payload() | The raw HTTP body |
Orbipay Hosted Forms provides server SDKs in Java, Python, C#, Node.js and PHP languages which are used to confirm payment from client's server . Orbipay Hosted Forms application utilizes secure RSA (size 2048) public and private key algorithm to encrypt and decrypt the token information between client server SDKs and Orbipay Hosted Forms. The unique public and private key pair are shared with clients, enabling them to make API requests securely and encrypt the sensitive information at field / parameter level. All requests must pass through key pair validation, and appropriate responses are sent.
Error Code | Description |
---|---|
200 - OK | Successfully processed the request |
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 |
500 - Internal Server Error | Something went wrong with Orbipay and the request could not be processed. |
Orbipay Hosted Forms uses standard HTTP response codes to return the status of an API call. Additional information, such as errors, may be useful to a caller. An HTTP response code of 2xx indicates success. In this case, additional information pertaining to the request is sent back in the header parameters. An HTTP response code of 4xx or 5xx indicates a processing error. In this case, Orbipay also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable.)
API Specific Error codes
Error code | Error Message |
---|---|
error_account_issuing_institution_name | Invalid account issuer name(5231) |
error_card_auth | The request cannot be completed as the card details provided cannot be validated(5232) |
error_card_avs_mismatch | The payment is rejected as the card AVS details mismatch with cardholders bank.(5233) |
error_card_cvv_mismatch | The payment is rejected as the card CVV details mismatch with cardholders bank.(5234) |
error_card_declined | The request cannot be completed as the given card is declined by the issuer(5235) |
error_card_expiry | The payment is rejected as the card expires before the payment date.(5236) |
error_charge_amount | The request cannot be processed with the given amount.(5237) |
error_confirm_payment_token_request | The request cannot be processed as it contains an invalid token request. (5238). |
error_currency_code3d | The request cannot process with the given currency code(5239) |
error_customer_account_invalid | The request cannot be processed with the given account information.(5241) |
error_customer_account_missing | The request cannot be processed with the given account information.(5242) |
error_customer_account_reference | The request cannot be processed as it contains invalid customer account reference(5243) |
error_customer_id | The request cannot be processed with the given Customer Id(5244) |
error_customer_missing | The request cannot be processed due to invalid customer details.(5245) |
error_dda_invalid | The request cannot be processed due to invalid bank details.(5246) |
error_duplicate_customer | A customer with the same details exists already.(5247) |
error_duplicate_customer_account | Could not identify a unique customer account.(5248) |
error_duplicate_funding_account | The funding account is rejected as it duplicates an existing one.(5249) |
error_duplicate_payment | The payment is rejected as it duplicates an existing one.(5251) |
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.(5252) |
error_funding_account_delete_disallowed | The funding account cannot be deleted due to other linked resources or business rules violation.(5253) |
error_funding_account_id | The request cannot be processed with the given Funding account id(5254) |
error_funding_account_invalid | The request cannot be processed with the given funding account information.(5255) |
error_funding_account_limit_reached | The funding account cannot be added due to business rules violation.(5256) |
error_funding_account_missing | The request cannot be processed due to invalid funding account.(5257) |
error_funding_account_status_invalid | The request cannot be processed due to invalid funding account.(5258) |
error_funding_account_update_disallowed | The funding account cannot be modified due to business rules violation.(5259) |
error_insufficient_balance | The request cannot be completed with the given funding source as it does not have sufficient balance. Choose a different type of funding source and try again.(5260) |
error_invalid_card | The request cannot be completed with the given card account details(5261) |
error_invalid_dda | The request cannot be completed with the given bank account details.(5262) |
error_issued_cust_id | The request cannot be processed with the given Issued Customer Id(5263) |
error_order_ref_no | The request cannot be processed with the given Order Reference Number(5264) |
error_payment_disallowed | The request cannot be processed with the given payment date.(5265) |
error_payment_method_mistmatch | The request cannot be processed with the given payment method.(5266) |
error_payment_rejected | The error returned if a payment cannot be processed as it violates business rules.(5267) |
error_payment_update_disallowed | The payment cannot be modified due to business rules violation.(5268) |
error_tech_difficulties | The request cannot be processed due to technical difficulties.Please contact Support team (obp.support@alacriti.com) for more details. |
error_token | The request contains invalid token(5273) |
error_unknown_error | Couldn't process the request. Please try again later. (Unknown error)(5274) |
error_unsupported_card | This card type is not supported. Please use another card.(5275) |
error_unsupported_funding_account | The request cannot be processed as the funding account is not supported for the client(5276) |
error_validate_request | The request cannot be processed as it contains an invalid validate request.(5277) |
error_acc_sub_type | Please select a valid acct subtype |
error_funding_source | Please select a valid funding source |
error_card_number | Please provide a valid card number |
error_card_not_allowed | This card type is not supported |
error_make_payment_not_opted | Client has not opted for Capture Payment function. Please contact the Support team (obp.support@alacriti.com) for more details. |
error_add_funding_account_not_opted | Client has not opted for Add Funding Account function. Please contact the Support team (obp.support@alacriti.com) for more details. |
error_update_funding_account_not_opted | Client has not opted for Update Funding Account function. Please contact the Support team (obp.support@alacriti.com) for more details. |
error_confirm_request | The request cannot be processed as it contains an invalid confirm request(5285) |
error_client_domain | The request cannot be processed as the client domain is not white listed with the system. Please contact Support team (obp.support@alacriti.com) for more details. |
error_client_id | The request cannot be processed as it contains invalid Client Key. Please contact Support team (obp.support@alacriti.com) for more details. |
error_fee_amount_disallowed | The fee amount cannot be accepted as it's configured to be calculated by Orbipay. |
error_confirm_request | The request cannot be processed as it contains an invalid confirm request. |
error_view_cnfg | The request cannot be processed dut to technical difficulties. Please contact (obp.support@alacriti.com) for more details. |
Custom fields are useful for storing additional structured information on an object. Orbipay supports custom fields for Customer Accounts and for Payments. For example, you could store the customer’s full name and corresponding unique identifier from your system, on a Orbipay Customer object. Custom fields are only captured and stored by Orbipay and not used for processing of any sort. Please contact support@billerpayments.com for any additional requirement you may have on custom fields.
The Create Payment Token API takes the token, digisign and creates a Payment.
client_id required | string [ 0 .. 50 ] characters ^[A-Za-z0-9-_]{0,50}$ Unique client Identifier, for example: 2490213303 |
digi_sign required | string Generated Digital Signature for data using private key, for example
|
This JSON contains all the attributes to Confirm Payment.
token required | string A unique token created for each call to a confirm payment token service. It is encrypted with the set of keys which are shared between Client anc Hosted forms Application |
tokenized_amount required | string Customer's order amount for confirm payment.The amount has to be encrypted with the keys provided, for payment confirmation. |
customer_account_reference required | string [ 0 .. 50 ] characters ^[A-Za-z0-9-_]{0,50}$ The unique identifier in the client system for the customer account. |
custom_fields | object |
Returns Confirm payment response with payment, customer, customer account and funding account information. It contains a set of ids which can be used for future reference.
The request was unacceptable, often due to missing a required parameter.
Unauthorized
The request was unacceptable, often due to missing a required parameter.
The requested resource doesn't exist.
Something went wrong at the Orbipay-Checkout Server
unexpected error
Java
Python
Php
Node.js
C#
{- "token": "KrsxtD6BAyNFTutlbvZibxf4Gb0bU8U+/+DU+KmoecKAYY41b+5kyABM3/gzWg9mgzTtlkSqlavJVrL+RWOfw223Ef3Nw4jV4J2XdWntvOJOldybKk7/4SgBRdllakp4i+Iuk/SEmaEWMj/UC0vy930gpNTrCpCbZQtJtmHqjjA8bHIcnKf5F7LSmlPK6ND7xSlGdi1g9aOmmGiN2ZktZkCXzYormZLjX1SElC9cxHmygdLt2zCqhLBr0wEGBsaYCFOTrFTYRsUcLs4IHR8lixlG1IhPtoDolRxxuLyRic+ZgM2KxcPvQXJgplL8n/szBNlteT28SXTxLPzFtB+TFA==",
- "tokenized_amount": "jDPs0mVc63zR+hZzchAyMr9/IXl/G664T1v53V+FMzkVHAC2hClyT9B05jAw7UT9/+lNTygwGwl44GQDzzLhzv8jiyY7MH/pgxOTFCrQcn8HlTedLSygfsj87bPCcRxiKJa13w8hJ5lOD55UH9JjiZF9JX/GLRhtoLIg/X/k62VvHjMgU1226iE0TkCu67AW1yH7bxlmucG+/YlT6CK2gYp6CDS4pV1rwnWnOJkbosYxnbq6LCzc7T7F4j4EIYksCrK5tvXIIFmFySDnRUlx7R3y1hx/2KeLJOE6I10ROchgSwTerQs6ZEW0bxGWJXjHB27EBJNCj36/7Z7pbZ26RQ",
- "customer_account_reference": "custexamplef5ptd555f",
- "custom_fields": {
- "property1": "string",
- "property2": "string"
}
}
{- "id": "12684515",
- "url": "/payments/{ID_PAYMENT}",
- "fee": {
- "fee_type": "add_to_principal",
- "fee_amount": "1.05",
- "id": "123456789",
- "url": "/customers/{ID_CUSTOMER}/fees/{ID_FEE}"
}, - "status": "scheduled",
- "payment_method": "check",
- "confirmation_number": "string",
- "currency_code3d": "USD",
- "amount": "101.05",
- "card_cvv_number": 321,
- "payment_date": "06/14/2017",
- "payment_schedule_type": "one_time_payment",
- "payment_request_date": "stringstri",
- "payment_amount_type": "other",
- "payment_reference": "PBruOrpMLl1dsBQ",
- "expected_payment_settlement_date": "2021-09-30",
- "payment_entry_date": "2021-09-30",
- "payment_return_date": "2021-09-30",
- "return_code": "string",
- "payer": {
- "id": "12684515",
- "url": "string",
- "customer_reference": "string",
- "first_name": "Will",
- "last_name": "Smith",
- "middle_name": "Collins",
- "date_of_birth": "2021-09-30",
- "ssn": "stringstr",
- "locale": "strin",
- "email": "user@example.com",
- "home_phone": "5876654586",
- "phone_number": "9825917248",
- "address": {
- "address_line1": "string",
- "address_line2": "string",
- "address_city": "string",
- "address_state": "st",
- "address_country": "str",
- "address_zip1": "strin",
- "address_zip2": "stri"
}, - "status": "active"
}, - "customer": {
- "id": "12684515",
- "url": "string",
- "customer_reference": "string",
- "first_name": "Will",
- "last_name": "Smith",
- "middle_name": "Collins",
- "date_of_birth": "2021-09-30",
- "ssn": "stringstr",
- "locale": "strin",
- "email": "user@example.com",
- "home_phone": "5876654586",
- "phone_number": "5876654586",
- "address": {
- "address_line1": "string",
- "address_line2": "string",
- "address_city": "string",
- "address_state": "st",
- "address_country": "str",
- "address_zip1": "strin",
- "address_zip2": "stri"
}, - "status": "active"
}, - "funding_account": {
- "id": "12684515",
- "url": "string",
- "account_holder_name": "string",
- "account_number": "string",
- "aba_routing_number": "031201360",
- "issuer_name": "string",
- "account_type": "card",
- "account_subtype": "visa_credit"
}, - "customer_account": {
- "id": "12684515",
- "url": "string"
}, - "custom_fields": {
- "property1": "string",
- "property2": "string"
}
}
The Create Funding Account Token API takes the token, digisign and creates a funding account.
client_id required | string [ 0 .. 50 ] characters ^[A-Za-z0-9-_]{0,50}$ Unique client Identifier, for example: 2490213303 |
digi_sign required | string Generated Digital Signature for data using private key, for example |
This JSON contains all the attributes to create Funding account .
token required | string A unique token created for each call to a confirm payment token service. It is encrypted with the set of keys which are shared between Client anc Hosted forms Application |
custom_fields | object |
Returns Funding account Object, along with the ids that are required for future reference.
The request was unacceptable, often due to missing a required parameter.
Unauthorized
The request was unacceptable, often due to missing a required parameter.
The requested resource doesn't exist.
Something went wrong at the Orbipay-Checkout Server
unexpected error
Java
Python
Php
Node.js
C#
{- "token": "FFFsddasdunddsds23323daccounttoken23984ashk+/+DU+KmoecKAYY41b+5kyABM3/gzWg9mgzTtlkSqlavJVrL+RWOfw223Ef3Nw4jV4J2XdWntvOJOldybKk7/4SgBRdllakp4i+Iuk/SEmaEWMj/UC0vy930gpNTrCpCbZQtJtmHqjjA8bHIcnKf5F7LSmlPK6ND7xSlGdi1g9aOmmGiN2ZktZkCXzYormZLjX1SElC9cxHmygdLt2zCqhLBr0wEGBsaYCFOTrFTYRsUcLs4IHR8lixlG1IhPtoDolRxxuLyRic+ZgM2KxcPvQXJgplL8n/szBNlteT28SXTxLPzFtB+TFA==",
- "custom_fields": {
- "property1": "string",
- "property2": "string"
}
}
{- "funding_account": {
- "account_holder_name": "string",
- "nickname": "Will's credit card",
- "address": {
- "address_line1": "string",
- "address_line2": "string",
- "address_city": "string",
- "address_state": "st",
- "address_country": "str",
- "address_zip1": "strin",
- "address_zip2": "stri"
}, - "account_number": "string",
- "aba_routing_number": "031201360",
- "issuer_name": "TD BANK, NA",
- "currency_code3d": "USD",
- "expiry_date": "11/29",
- "account_subtype": "visa_credit",
- "id": "12684515",
- "url": "string",
- "save_for_future_use": "true, false",
- "account_type": "card"
}, - "payer": {
- "id": "12684515"
}, - "customer_account": {
- "id": "12684515"
}
}
The Update Funding Account Token API takes the token, digisign and updates a funding account. The Id of the funding account gets updated to a new value if the account number is updated.
ID_ACCOUNT required | string <= 20 characters [0-9]{0,20} Unique id of funding account of a customer in Orbipay. |
client_id required | string [ 0 .. 50 ] characters ^[A-Za-z0-9-_]{0,50}$ Unique client Identifier, for example: 2490213303 |
digi_sign required | string Generated Digital Signature for data using private key, for example BQYpeA50hrxKGjQs76oLRyTTbTEbFslxlZDkePpP6pz2gLFeSY9YekAnBP4BzacDz46kCLaQDIoGEUlY0ujlSD/3YoxRVmuvXGkSsG+7tHQidrwCmYa0qTGXM1xRq9x7Q77T8mV/rV9cuOIYr9Y9bjkpSi8XyDHwBBLzibCYOl7LG1loQA4CJ7cs8WKhqdPn1kR7gtl2AFbGp+BLuN1mvMYNiXfwsS1OYMzj0pEdDDL5xz8wRYjHSemixE2MzkUSSEzSCHrRz8KPG508uQ17i7KdszcWQjvwhow3NtCdHxYvXuv/tq0FJoCTJk92TtTe006viXQg5wu+KuUrO3yW1Q== |
This JSON contains all the attributes to update Funding account .
token required | string A unique token created for each call to a confirm payment token service. It is encrypted with the set of keys which are shared between Client anc Hosted forms Application |
custom_fields | object |
Returns Funding account Object, along with the ids that are required for future reference.
The request was unacceptable, often due to missing a required parameter.
Unauthorized
The request was unacceptable, often due to missing a required parameter.
The requested resource doesn't exist.
Something went wrong at the Orbipay-Checkout Server
unexpected error
Java
Python
Php
Node.js
C#
{- "token": "FFFsddasdunddsds23323daccounttoken23984ashk+/+DU+KmoecKAYY41b+5kyABM3/gzWg9mgzTtlkSqlavJVrL+RWOfw223Ef3Nw4jV4J2XdWntvOJOldybKk7/4SgBRdllakp4i+Iuk/SEmaEWMj/UC0vy930gpNTrCpCbZQtJtmHqjjA8bHIcnKf5F7LSmlPK6ND7xSlGdi1g9aOmmGiN2ZktZkCXzYormZLjX1SElC9cxHmygdLt2zCqhLBr0wEGBsaYCFOTrFTYRsUcLs4IHR8lixlG1IhPtoDolRxxuLyRic+ZgM2KxcPvQXJgplL8n/szBNlteT28SXTxLPzFtB+TFA==",
- "custom_fields": {
- "property1": "string",
- "property2": "string"
}
}
{- "funding_account": {
- "account_holder_name": "string",
- "nickname": "Will's credit card",
- "address": {
- "address_line1": "string",
- "address_line2": "string",
- "address_city": "string",
- "address_state": "st",
- "address_country": "str",
- "address_zip1": "strin",
- "address_zip2": "stri"
}, - "account_number": "string",
- "aba_routing_number": "031201360",
- "issuer_name": "TD BANK, NA",
- "currency_code3d": "USD",
- "expiry_date": "11/29",
- "account_subtype": "visa_credit",
- "id": "12684515",
- "url": "string",
- "save_for_future_use": "true, false",
- "account_type": "card"
}, - "payer": {
- "id": "12684515"
}, - "customer_account": {
- "id": "12684515"
}
}