====== Registering Secure Tokens ======= ~~TOC~~ This feature enables you to store your customers' card details using a hosted page. * Sandbox URL: ''%URLSecureCard'' ===== Request ===== ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | ACTION | Y | ^{string ''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 %CompanyName. | | MERCHANTREF | Y | ^{string ''[ 1 .. 200 ] characters''} \\ Unique Reference assigned by the merchant to identify the stored card details. | | EMAIL \\ ^{See notes: [[hpp_secure_tokens_features#ND0003 - Cardholder email field|ND0003]]} | N | ^{string ''[ 1 .. 128 ] characters''} \\ The cardholder email address. | | DATETIME | Y | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ Date and time of the request. | | HASH \\ ^{See notes: [[hpp_secure_tokens_features#ND001 - Hash generation|ND001]]} | Y | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the request fields. | | STOREDCREDENTIALUSE | N | ^{string ''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 \\ ''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 **[[selfcare:api_specification:special_fields_and_parameters|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 ''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**: mySharedSecretUSD

===== 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: ^ **FIELD** ^ **DESCRIPTION** ^ | RESPONSECODE \\ ^{See notes: [[hpp_secure_tokens_features#ND002 - Response error codes|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 %CompanyName, this is the token that represents the card details. | | CARDTYPE | Card type used for the transaction. \\ For more details on this, visit **[[selfcare:api_specification:special_fields_and_parameters#the_card_types|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 \\ ''CHECKING'' \\ ''SAVINGS'' \\ The account type of the client's bank account. | | DATETIME | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ The time of the registration. | | HASH \\ ^{See notes: [[hpp_secure_tokens_features#ND001 - Hash validation|ND001]]} | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the response fields. | | STOREDCREDENTIALUSE | ^{string ''UNSCHEDULED'', ''INSTALLMENT'', ''RECURRING''} \\ The same value you provided in the request will be echoed back here. | | STOREDCREDENTIALTXTYPE | ^{string ''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 %CompanyName. See how to decode and validate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|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== ^ **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| \\ \\