Accepting Bank Transfer Payments

Accepting Bank Transfer Payments
- Request
  - Request notes
  - Request sample
- Response
  - Response notes

Worldnet-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	`https://testpayments.worldnettps.com/merchant/paymentpage`

Request

Filter:

FIELD	REQUIRED	DESCRIPTION
TERMINALID	Y	^{string [ 1 .. 50 ] characters} The terminal number assigned by Worldnet.
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	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 Worldnet 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:

Build and submit the form as with standard integration, but within the iFrame.
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.

Request sample

Scenario: Minimum request containing only mandatory data.
Terminal Secret: x4n35c32RT.

<html>
  <body>
    <form action="https://testpayments.worldnettps.com/merchant/paymentpage" 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 Worldnet. 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.