Tokenization

Tokenization

Gateway Token

EVO Payment 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 Payment will return the Gateway Token in the response; if it fails, the tokenization will also fail.

TIP

If you need to bind the card while authorizing, EVO Payment requires 3DS authentication for this transaction. For details on 3DS authentication, please refer to the 3DS section.

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 Payment 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 Payment, 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.

TIP

1. Using the POST PaymentMethod to directly create a Gateway Token requires 3DS authentication; for details, refer to the 3DS section.
2. You can directly create a Gateway Token using the POST PaymentInstrument without the need for authentication through EVO Payment. Just can complete the authentication via alternative methods and then bind a card solely through EVO Payment.

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 Payment 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 Payment, 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 Payment 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 Payment 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 Payment's Gateway Token.

2. Check the EVO Payment 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 Payment, 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.

	Card Transaction	Token Transaction
paymentMethod.type	card	token
paymentMethod.card	Exists	Does not exist
paymentMethod.token	Does not exist	Exists

TIP

1. Transactions initiated using the Gateway Token created directly by POST PaymentMethod also support 3DS authentication, following the same process as standard card transactions; refer to the 3DS section for details.
2. Transactions initiated through EVO Payment using the Gateway Token or Merchant Token created directly by POST PaymentInstrument also support 3DS authentication, following the same process as standard card transactions; refer to the 3DS section for details.
3. Use the POST PaymentInstrument to create a Gateway Token. You may utilize other acquiring service providers to finalize the payment process. In such cases, you must first retrieve the card information using the GET PaymentInstrument , and then proceed to the designated acquiring service provider to complete the payment.

Manage Gateway Token

Consumers may need to update (e.g., card expiration) or delete (e.g., card deactivation) their bound cards. EVO Payment 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.

Request Parameter	Description
userReference	Use the userReference set when creating the Gateway Token to query all associated Gateway Tokens.
token	Specify the value of a Gateway Token to query its information.

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.

Request Parameter	Description
token	(1) Specify the value of a Gateway Token to query its information. (2) Or using the merchantToken.value set when creating the Gateway Token to query the associated Gateway Token. (3) Please use with the field paymentMethodType.
paymentMethodType	Only supports enumeration value card. Please use with the field token.
merchantTransID	Use the merchantTransID set when creating the Gateway Token to query the associated Gateway Token.

Response Parameter	Description
paymentMethod.card.encryptedCardInfo	Indicates the encrypted card information. If paymentMethodType is card in URL & paymentMethod.token.value is valid & the acquirer has configured ‘API Resp RSA/SM2 Encryption Key' in EVO Payment Platform, then this field will be returned. (1) The plain text sample is as follows:{"cardNumber":"1234123412341234","expiryDate":"2407","holderName":"test"} (2) The Encryption flow is as follows: Step 1: The spliced json character string:{"cardNumber":"1234123412341234","expiryDate":"2407","holderName":"test"} Step 2: Encrypt the character string using the public key specified by paymentMethod.card.cardInfoEncryptMethod . Step 3: Put the cipher text into this field. (3) Please use with the field paymentMethod.card.cardInfoEncryptMethod .
paymentMethod.card.cardInfoEncryptMethod	Indicates the encryption algorithm of paymentMethod.card.encryptedCardInfo . (1) If paymentMethodType is card in URL & paymentMethod.token.value is valid & the acquirer has configured ‘API Resp RSA/SM2 Encryption Key' in EVO Payment Platform, then this field will be returned with the corresponding configured key type. If multiple configurations exist, the default will be 'RSA'. (2) Enumeration values: RSA, SM2. (3) Please use with the field paymentMethod.token.value .

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

Request Parameter	Description
token	(1) Specify the value of a Gateway Token to update its information. (2) Or using the merchantToken.value set when creating the Gateway Token to update the associated Gateway Token.

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.

Request Parameter	Description
token	Specify the value of a Gateway Token to delete it.

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.

Request Parameter	Description
token	(1) Specify the value of a Gateway Token to delete it. (2) Or using the merchantToken.value set when creating the Gateway Token to delete the associated Gateway Token.