Registering Secure Tokens

Table of Contents

This feature enables you to store your customers' card details using a hosted page.

  • Sandbox URL: https://testpayments.worldnettps.com/merchant/securecardpage

Request

Filter:

FIELD REQUIRED DESCRIPTION
ACTION Y string <enum> register, update
The action that determines whether you're trying to store or update a Secure Tokens.
TERMINALID Y string [ 1 .. 50 ] characters
The terminal number assigned by Worldnet.
MERCHANTREF Y string [ 1 .. 200 ] characters
Unique Reference assigned by the merchant to identify the stored card details.
EMAIL
See notes: ND004 		N string [ 1 .. 128 ] characters
The cardholder email address.
DATETIME Y string <date-time> DD-MM-YYYY:HH:MM:SS:SSS
Date and time of the request.
HASH
See notes: ND001 		Y string <SHA-512> [ 1 .. 128 ] characters
A HASH code formed by part of the request fields.
STOREDCREDENTIALUSE N string <enum> UNSCHEDULED, INSTALLMENT, RECURRING
When cardholders authorize a merchant to store their card details, they must explicitly consent to how their credentials will be used in the future.
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.


Request notes

ND001 - Hash generation

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

TERMINALID:MERCHANTREF:DATETIME:ACTION:SECRET


ND002 - Hosted page in an iFrame

When embedding the hosted page inside an iframe and using the sandbox attribute, ensure that allow-same-origin is included in the list of allowed tokens.
Without this, browser security policies may block scripts from executing properly, leading to CORS-related errors and preventing the page from functioning correctly.

Recommended sandbox configuration:
sandbox=“allow-modals allow-forms allow-popups allow-scripts allow-same-origin”

For more details on the sandbox attribute, refer to the MDN documentation

You can embed our hosted pages within an iframe if you don't want the customer to leave your site. There are two ways to do that:

  1. Build and submit the form as with standard integration, but within the iFrame.
  2. Construct the request URL, including the parameters as query strings, and set it as the src of the iFrame.

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 - Updating Secure Tokens

To initiate card details updating, the value of the ACTION parameter should be changed to update. Updates are performed based on the MERCHANTREF field.


ND004 - Cardholder email field

This field is available for all terminals, but depending on the Hosted token 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.

The email address will be mandatory for terminals that have 3-D Secure Authentication enabled.

Request sample

  • Scenario: Minimum request containing only mandatory data.
  • Terminal Secret: mySharedSecretUSD
<html>
  <body>
    <form action="https://testpayments.worldnettps.com/merchant/securecardpage" method="post">
        <input type="hidden" name="ACTION" value="register" />
        <input type="hidden" name="TERMINALID" value="4480001" />
        <input type="hidden" name="MERCHANTREF" value="1234321" />
        <input type="hidden" name="DATETIME" value="15-3-2023:10:43:01:673" />
        <input type="hidden" name="HASH" value="b08244ab9557ba680174870c2a3cae3e6c88c31ab84537a0bf86e6f04676995ffa11d6bfaeee6ae3fa2935c899e04af5f867f861accae2f1f22709046dcb599a" />
        <input type="submit" value="Register" />
    </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 registration is complete, the following parameters will be forwarded to the Secure Tokens URL configured in your terminal:

Filter:

FIELD DESCRIPTION
RESPONSECODE
See notes: ND002 		A - Approval
RESPONSETEXT string [ 1 .. 48 ] characters
The text of the response.
MASKEDCARDNUMBER string [ 12 .. 19 ] characters
The registered or updated card number masked as per PCI requirements.
MERCHANTREF string [ 1 .. 200 ] characters
The MERCHANTREF provided in the request.
CARDREFERENCE string [ 12 .. 19 ] characters
The reference number assigned by Worldnet, this is the token that represents the card details.
CARDTYPE Card type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
CARDEXPIRY string MMYY
Expiry date of the card.
TRANSITNUMBER string [ 5 ] characters
Client's bank branch/transit number.
ROUTINGNUMBER string [ 9 ] characters
The 9-digit ABA routing transit number of the account.
ACCOUNTNUMBER string
Client's bank account number masked with the character * except last four digits.
INSTITUTIONNUMBER string [ 3 ] characters
Client's institution number.
ACCOUNTTYPE string <enum>
CHECKING
SAVINGS
The account type of the client's bank account.
DATETIME string <date-time> DD-MM-YYYY:HH:MM:SS:SSS
The time of the registration.
HASH
See notes: ND001 		string <SHA-512> [ 1 .. 128 ] characters
A HASH code formed by part of the response fields.
STOREDCREDENTIALUSE string <enum> UNSCHEDULED, INSTALLMENT, RECURRING
The same value you provided in the request will be echoed back here.
STOREDCREDENTIALTXTYPE string <enum> FIRST_TXN, SUBSEQUENT_MERCHANT_INITIATED_TXN, SUBSEQUENT_CARDHOLDER_INITIATED_TXN
Since this is registration, the gateway will always return FIRST_TXN.
BRANDTXIDENTIFIER string [ 1 .. 64 ] characters
Reference provided by the card scheme. It's the link to the payment history between a customer and a merchant.


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 the following format: 

TERMINALID:RESPONSECODE:RESPONSETEXT:MERCHANTREF:CARDREFERENCE:DATETIME:SECRET


ND002 - Response error codes

Filter:

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E04 INVALID REFERENCE DETAILS
E05 INVALID CARD TYPE
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E09 INVALID DATETIME
E10 INVALID CARDNUMBER
E11 INVALID CARDEXPIRY
E12 INVALID CARDHOLDERNAME
E13 INVALID HASH
E14 CVV VALIDATION FAILED
E24 SECURE TOKEN IS USED IN SUBSCRIPTION
E32 SECURE TOKEN ALREADY EXISTS
E33 INVALID ENCRYPTION METHOD
E42 INAPPROPRIATE CARD NUMBER USAGE
E43 APPROVED BUT ACCOUNT NOT VALIDATED
E44 BANK ACCOUNT VALIDATION FAILED



Copyright © 2025 | Powered by DokuWiki