Developers

Hosted Forms API (2.0)

Introduction

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.

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

Communication

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 Codes

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

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.

Payment

Create Payment

The Create Payment Token API takes the token, digisign and creates a Payment.

header Parameters
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==

Request Body schema: application/json

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

Responses

200

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.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

402

The request was unacceptable, often due to missing a required parameter.

404

The requested resource doesn't exist.

500

Something went wrong at the Orbipay-Checkout Server

default

unexpected error

post/payments/token
https://apico.billerpayments.com/app/opco/v3/service/payments/token

  • Java

  • Python

  • Php

  • Node.js

  • C#

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Funding Account

Create Funding Account

The Create Funding Account Token API takes the token, digisign and creates a funding account.

header Parameters
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==

Request Body schema: application/json

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

Responses

200

Returns Funding account Object, along with the ids that are required for future reference.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

402

The request was unacceptable, often due to missing a required parameter.

404

The requested resource doesn't exist.

500

Something went wrong at the Orbipay-Checkout Server

default

unexpected error

post/fundingaccounts/token
https://apico.billerpayments.com/app/opco/v3/service/fundingaccounts/token

  • Java

  • Python

  • Php

  • Node.js

  • C#

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Update Funding Account

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.

path Parameters
ID_ACCOUNT
required
string <= 20 characters [0-9]{0,20}

Unique id of funding account of a customer in Orbipay.

header Parameters
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==

Request Body schema: application/json

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

Responses

200

Returns Funding account Object, along with the ids that are required for future reference.

400

The request was unacceptable, often due to missing a required parameter.

401

Unauthorized

402

The request was unacceptable, often due to missing a required parameter.

404

The requested resource doesn't exist.

500

Something went wrong at the Orbipay-Checkout Server

default

unexpected error

put/fundingaccounts/{ID_ACCOUNT}/token
https://apico.billerpayments.com/app/opco/v3/service/fundingaccounts/{ID_ACCOUNT}/token

  • Java

  • Python

  • Php

  • Node.js

  • C#

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}