Accepting Bank Transfer Payments

Table of Contents

-hosted payment page enables you to create secure and fully customized payment forms that let you accept bank transfer payments on your website.

This solution works across devices and doesn't require much development work, all you need to do is send us a POST request with a set of pre-defined fields.

The request body will be identical for bank transfers and payments, but it's the terminal setting that determines which form will be displayed first.

  • Case 1 - The terminal supports card processing and bank transfer
    • Payment Type displays card brands and bank transfers as an option of payment.
  • Case 2 - The terminal supports only card processing
    • Payment Type displays card brands as an option of payment only.
  • Case 3 - The terminal supports only bank transfer
    • Payment Type displays bank transfers as an option of payment only.

TYPE SANDBOX URL
Payment

Request

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y string [ 1 .. 50 ] characters
The terminal number assigned by .
ORDERID Y string [ 1 .. 24 ] characters
A unique identifier for the order assigned by the merchant.
CURRENCY
Y string 3-char ISO 4217 code
The currency of the bank transfer.
AMOUNT Y number <double> > 0
The total amount to be authorized.
DATETIME Y string <date-time> DD-MM-YYYY:HH:MM:SS:SSS
The transaction date and time.
HASH
See notes: ND001 		Y string <SHA-512> [ 1 .. 128 ] characters
A HASH code formed by part of the request fields.
ACCOUNTHOLDER_NAME N string [ 1 .. 50 ] characters
Client's bank account name . If provided, it will be used to pre-populate the account holder name field on the payment page.
DESCRIPTION N string [ 1 .. 1024 ] characters
A brief description of the transaction.
EMAIL
See notes: ND004 		N string [ 1 .. 128 ] characters
The cardholder email address.
If Email Cardholder Receipt feature is enabled on the terminal, we will use this address to delivery transaction receipts to your customer.
RECEIPTPAGEURL N string <URI>
This is the webhook that will use to send you the result of the transactions. If provided, this will override the terminal setting in the Selfcare System.
ADDRESS1
N string [ 1 .. 50 ] characters
The first line of the billing address.
ADDRESS2 N string [ 1 .. 50 ] characters
The second line of the billing address.
POSTCODE
N string [ 1 .. 50 ] characters
The postal code of the billing address.
CITY
N string [ 1 .. 128 ] characters
The city of the billing address.
REGION
N string [ 1 .. 128 ] characters
The region of the billing address.
COUNTRY
N string 2-char ISO 3166-1 code
The country of the billing address.
PHONE N string [ 5 .. 20 ] characters
The cardholder phone number. International numeric format.
CUSTOMFIELD N You can send any of the custom fields configured on your terminal. Otherwise, they will be displayed as inputs, so that the cardholder can populate them. All custom fields will be stored along with the transaction details and echoed back to the Receipt URL. Check Special Fields and Parameters for more details.
PAYMENTOPTIONS N string <enum>
CARD
BANK_TRANSFER
CARD_AND_BANK_TRANSFER
Restricts payment options to either cards, bank transfer providers or both. Not providing a value is equivalent to the CARD_AND_BANK_TRANSFER option.
OTHERFIELD N Any other fields sent in the request will be treated as metadata. They are not going to be stored, but they'll be echoed back to the Receipt URL. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.
CARDREFERENCE N string [ 12 .. 19 ] characters
Token reference of an existing Secure Token.
If provided, your customer won't be able to change the account details or use a different payment method on the hosted page.

Request notes

ND001 - Hash generation

See how to generate a hash string at Special Fields and Parameters. For this specific feature, you should use one of the following formats: 

TERMINALID:ORDERID:AMOUNT:DATETIME:RECEIPTPAGEURL:SECRET


ND002 - Hosted page in an iFrame

If you don't want the customer to leave your site you can implement the HPP within an iframe. There are two ways to do that:

  1. Build and submit the form as with standard integration, but within the iFrame.
  2. Build the POST query string within the main page and then create an iFrame with the string as it's SRC value.

Either way, the following extra parameter should also be included in the request:

FIELD REQUIRED DESCRIPTION
INIFRAME Y Y - Ensures that all redirects performed by our system do not break out of the iFrame.


ND003 - Storing account details

Give customers the option to store their account details during a payment. To display this option, you just need to include the field below in the request:

FIELD REQUIRED DESCRIPTION
SECURECARDMERCHANTREF Y string [ 1 .. 200 ] characters
Unique Reference assigned by the merchant to identify the stored account details.


ND004 - Cardholder email field

This field is available for all terminals, but depending on the Hosted payment page email field setup terminal setting, it might have one of the following behaviors:

  • Hidden - the gateway accepts the field, if sent, and adds it to the transaction, but does not show it to the customer.
  • Optional - an optional e-mail field is displayed to the cardholder. If you send the EMAIL parameter in the request, we'll use its value to pre-populate the field.
  • Mandatory - a required e-mail field is displayed to the cardholder. If you send the EMAIL parameter in the request, we'll use its value to pre-populate the field.

Request sample

  • Scenario: Minimum request containing only mandatory data.
  • Terminal Secret: x4n35c32RT.
<html>
  <body>
    <form action="" method="post">
       <input type="hidden" name="TERMINALID" value="6491003" />
       <input type="hidden" name="ORDERID" value="1478" />
       <input type="hidden" name="CURRENCY" value="USD" />
       <input type="hidden" name="AMOUNT" value="10.00" />
       <input type="hidden" name="DATETIME" value="28-8-2023:10:20:15:225" />
       <input type="hidden" name="HASH" value="2eccef7c0a499bf3b1ebed56a59c595c" />
       <input type="submit" value="Pay Now" />
    </form>
  </body>
</html>


Remember to change the TERMINALID and SECRET for valid values. Ready to try? Sign up for a sandbox account.

Response

Assuming valid details were sent, the hosted page will be displayed to the cardholder and he'll be prompted to enter his card details. Once the payment is processed, the following parameters will be forwarded to the Receipt URL configured in your terminal:

Filter:

FIELD DESCRIPTION
ORDERID string [ 1 .. 24 ] characters
Echoed back from the request.
UNIQUEREF string [ 10 ] characters
Unique reference assigned by the gateway that identifies the transaction on both platforms. Note: Clients must be able to store this value in order to eventually perform follow up operation on existing transactions.
TRANSIT_NUMBER string [ 5 ] characters
Client's bank branch/transit number.
ROUTING_NUMBER string [ 9 ] characters
The 9-digit ABA routing transit number of the account.
ACCOUNT_NUMBER string
Client's bank account number masked with the character * except last four digits.
INSTITUTION_NUMBER string [ 3 ] characters
Client's institution number.
ACCOUNT_TYPE string <enum>
CHECKING
SAVINGS
The account type of the client's bank account.
RESPONSECODE string <enum>
A: Approval
D: Declined
RESPONSETEXT string [ 0 .. 48 ] characters
A brief description sent by the processor about the transaction result.
DISCOUNT_AMOUNT number <double> > 0
The discount amount.
DATETIME string <date-time> DD-MM-YYYY:HH:MM:SS:SSS
The processing date and time of the transaction.
EMAIL string [ 1 .. 128 ] characters
Echoed back from the request.
PHONE string [ 5 .. 20 ] characters
Echoed back from the request.
COUNTRY string 2-char ISO 3166-1 code
Echoed back from the request.
HASH
See notes: ND001 		string <SHA-512> [ 1 .. 128 ] characters
A HASH code formed by part of the response fields.
CUSTOMFIELD Echoed back from the request.


Response notes

ND001 - Hash validation

A hash string is also included in the response, so that you can implement a verification logic to make sure it was sent by . See how to decode and validate a hash string at Special Fields and Parameters.

For this specific feature, you should expect one of the following formats: 

/**
 * The general case
 */
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET


ND002 - Secure Token registration

By including the SECURECARDMERCHANTREF field in the request, you give customers the option to store their account details.
If a customer checks that option, the gateway automatically triggers a secure registration and adds the following extra parameters to the response:

FIELD DESCRIPTION
ISSTORED boolean
true, false
SCERROR If ISSTORED = false, check out this field for a brief description of the failure.
MERCHANTREF string [ 1 .. 200 ] characters
The same SECURECARDMERCHANTREF you sent in the request.


Copyright © 2024 | Powered by DokuWiki