Tokenization ​

Tokenization ​

Gateway Token ​

EVO Cloud allows you to store consumer card information in its system, generating a Gateway Token that you can use for subsequent transactions.

Create Gateway Token ​

There are two ways to create a Gateway Token:

1. Create Gateway Token while authorizing
2. Create Gateway Token directly

Here are the detailed processes for both methods.

Create Gateway Token when Authorizing ​

You can bind the card during your existing authorization process. If authorization is successful, EVO Cloud will return the Gateway Token in the response; if it fails, the tokenization will also fail.

The main process is as follows:

1. Add the following parameters to the POST Payment request:

   • paymentMethod.card.tokenize: Set to true to bind the card during authorization.
   • paymentMethod.card.payerReference: A consumer identifier that you can customize.
   • authentication: Object contains 3DS authentication information; refer to the 3DS section for details.

2. Check the EVO Cloud response. If result.action is present, the transaction requires 3DS authentication (refer to the 3DS section). If not, check the payment.status field. If its value is Captured, Authorised, or Capturing (depending on captureAfterHours), the transaction is successful, and you can find the Gateway Token in paymentMethod.token.value. Otherwise, check result.code and result.message for the failure reason.

3. If no response is received from EVO Cloud, call GET Payment to query the transaction result. Upon receiving the query response, check the transaction result using the payment.status field as in step 2. For failures, refer to payment.failureCode and payment.failureReason.

4. If you included a webhook in your POST Payment request and the payment.status is Captured, Authorised, or Capturing, you can also receive the transaction result through asynchronous notification with eventCode as Payment. Again, check the payment.status field as in step 2.

5. Present the payment and card binding results to the consumer.

Directly Create Gateway Token ​

If the consumer only needs to bind a card, you can use the POST PaymentMethod or POST PaymentInstrument interface to create a Gateway Token directly.

The main process of PaymentMethod is as follows:

1. When calling the PaymentMethod interface, include, but are not limited to, the following parameters (refer to the API documentation for details):

   • paymentMethod.type: Indicates the payment method; use card for card transactions.
   • paymentMethod.card: Object contains consumer card information; required if paymentMethod.type is card.
   • merchantTransInfo: Object contains merchant order information.
   • pspInfo: Object contains card organization qualification information.
   • transInitiator: Object contains consumer device information.
   • authentication: Object contains 3DS authentication information; refer to the 3DS section for details.

2. Check the EVO Cloud response. If result.action is present, the transaction requires 3DS authentication (refer to the 3DS section). If not, check the paymentMethod.status. If it is Success, the Token creation is successful, and you can find the Gateway Token in paymentMethod.token.value; otherwise, check result.code and result.message for the failure reason.

3. If no response is received from EVO Cloud, call GET PaymentMethod to query the transaction result. Assess the result using the paymentMethod.status field as in step 2. For failures, refer to paymentMethod.failureCode and paymentMethod.failureReason.

4. If you included a webhook in your POST PaymentMethod request and the paymentMethod.status is Success, you can also receive the transaction result through asynchronous notification with eventCode as PaymentMethod. Again, check the paymentMethod.status as in step 2.

5. Present the card binding result to the consumer.

The main process of PaymentInstrument is as follows:

1. When calling the PaymentInstrument interface, include, but are not limited to, the following parameters (refer to the API documentation for details):

   • merchantTransInfo：Object contains merchant order information and serves as the traceability information for the Gateway Token.
   • paymentMethod.type: Indicates the payment method; use card for card transactions.
   • paymentMethod.card: Object contains consumer card information; required if paymentMethod.type is card.
   • paymentMethod.card.cardInfo.paymentBrand： Indicates the payment brand, optional. (1) If PaymentBrand is not specified, this field may be omitted. EVO Cloud will determine the payment brand through the card number. If the payment brand is among American_Express, Diners, JCB, Mastercard, UnionPay, Visa, MyDebit, TPN, or NAFAS, the response will return the corresponding payment brand. If not, EVO Cloud will not return this field. (2) When specifying PaymentBrand, it must be selected from the brands American_Express, Diners, JCB, Mastercard, UnionPay, Visa, MyDebit, TPN, or NAFAS; otherwise, it will not take effect.
   • paymentMethod.merchantToken：Object contains merchant's own Token information, which can be optionally used to bind with EVO Cloud's Gateway Token.

2. Check the EVO Cloud response. If result.message is Success, the Token creation is successful, and you can find the Gateway Token in paymentMethod.token.value; otherwise, check result.code and result.message for the failure reason. For details, refer to the Response code section.

3. If no response is received from EVO Cloud, call GET PaymentInstrument to query the transaction result. Assess the result using the result.message field as in step 2. For failures, refer to step 2 also.

4. If you included a webhook in your POST PaymentInstrument request and the result.message is Success, you can also receive the transaction result through asynchronous notification with eventCode as PaymentInstrument. Again, check the result.message as in step 2.

5. Present the card binding result to the consumer.

Use Gateway Token for Payment ​

Once you have successfully obtained the Gateway Token, you can use it in your authorization requests instead of card information. The transaction process remains the same as a standard authorization transaction, requiring only a few fields in the POST Payment request to be replaced.

Manage Gateway Token ​

Consumers may need to update (e.g., card expiration) or delete (e.g., card deactivation) their bound cards. EVO Cloud provides capabilities to query, update, and delete Gateway Tokens.

Query Gateway Token ​

1. Use the GET PaymentMethod interface to query a specific Gateway Token or all Gateway Tokens associated with a consumer created by the PaymentMethod interface through specifying different parameters.

2. Use the GET PaymentInstrument interface to query a specific Gateway Token or a Gateway Token associated with a merchantTransID created by the PaymentInstrument interface through specifying different parameters. Simultaneously, the token information or card information you desire will be returned, and the card information can be used for subsequent payments.

Update Gateway Token ​

1. Use the PUT PaymentMethod interface to update the information of a specific Gateway Token that was created via the PaymentMethod interface. The following fields can be updated:

   • expiryDate: Card expiration date
   • holderName: Cardholder's name
   • tokenValidDays: Gateway Token validity period

2. Use the PUT PaymentInstrument interface to update the information of a specific Gateway Token that was created via the PaymentInstrument interface. The following fields can be updated:

   • expiryDate: Card expiration date
   • holderName: Cardholder's name
   • tokenValidDays: Gateway Token validity period
   • payerReference: The customer identification

Delete Gateway Token ​

1. Use the DELETE PaymentMethod interface to delete a specific Gateway Token created via the PaymentMethod interface by specifying the Gateway Token value.

2. Use the DELETE PaymentInstrument interface to delete a specific Gateway Token created via the PaymentInstrument interface by specifying a Gateway Token value or Merchant Token value.