Registering Secure Tokens
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: ND0003 | 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 - 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.
ND0003 - 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
EMAILparameter 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
EMAILparameter 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 |