1. Online payments scenes
EVO Payment Gateway API
  • Gateway Integration
    • Version Record
    • CardInfoLink Gateway API Integration Guide
      • Online payments scenes
        • DCC
        • Tokenization
        • Payment
        • 3DS Authentication
        • Capture
        • Cancel
        • Refund
        • Merchandise Credit
        • Network token management
        • Cancel or Refund
        • Recapture
        • Recurring
      • Security Requirements and Message Header
        • Message protocol
        • Signature
        • Card Information Encryption
        • PIN Encryption
      • Offline payments scenes
        • Pre-authorization
        • Payment
        • Capture
        • Refund
        • Merchandise Credit
        • Cancel
        • Reversal
        • DCC
        • Recurring
      • Appendix
        • Response code
        • FAQ
        • Mastercard-Merchant Advice Code
        • Product Code
    • Offline API Specification
      • Payment
        • Payment
        • Payment
      • StandaloneCapture
        • StandaloneCapture
        • StandaloneCapture
      • Reversal
        • Reversal
      • MerchandiseCredit
        • MerchandiseCredit
        • MerchandiseCredit
      • Capture
        • Capture
        • Capture
      • TipsAdjustment
        • TipsAdjustment
        • TipsAdjustment
      • Cancel
        • Cancel
        • Cancel
      • MultipleCapture
        • MultipleCapture
        • MultipleCapture
      • FXRateInquiry
        • FXRateInquiry
        • FXRateInquiry
      • Refund
        • Refund
        • Refund
      • DCCToNon-DCC
        • DCCToNon-DCC
        • DCCToNon-DCC
      • ZPK
        • ZPK
      • Notification
        • Asynchronous notification for StandaloneCapture
        • Asynchronous notification for MultipleCapture
        • Asynchronous notification for Payment
        • Asynchronous notification for Capture
        • Asynchronous notification for Refund
        • Asynchronous notification for MerchandiseCredit
        • Asynchronous notification for Cancel
    • Online API Specification
      • PaymentMethod
        • PaymentMethod
        • PaymentMethod
        • PaymentMethod
        • PaymentMethod
      • Payment
        • Payment
        • Payment
        • Payment
      • Refund
        • Refund
        • Refund
      • Cancel
        • Cancel
        • Cancel
      • Capture
        • Capture
        • Capture
      • PaymentInstrument
        • PaymentInstrument
        • PaymentInstrument
        • PaymentInstrument
        • PaymentInstrument
      • MerchandiseCredit
        • MerchandiseCredit
        • MerchandiseCredit
      • CancelOrRefund
        • CancelOrRefund
        • CancelOrRefund
      • TransactionHistoryInquiry Copy
        • TransactionHistoryInquiry
      • MultipleCapture
        • MultipleCapture
        • MultipleCapture
      • Cryptogram
        • Cryptogram
        • Cryptogram
      • StandaloneCapture
        • StandaloneCapture
        • StandaloneCapture
      • Recapture
        • Recapture
        • Recapture
      • AsynchronousNotification
        • Asynchronous notification for Multiple Capture
        • Asynchronous notification for PaymentMethod
        • Asynchronous notification for PaymentInstrument
        • Asynchronous notification for Payment
        • Asynchronous notification for Merchandise Credit
        • Asynchronous notification for Refund
        • Asynchronous notification for Capture
        • Asynchronous notification for Cancel
        • Asynchronous notification for Recapture
        • Asynchronous notification for Cryptogram
        • Asynchronous notification for Network Token update
        • Asynchronous notification for Standalone Capture
        • Asynchronous notification for Network Token authentication finished
      • HealthCheck
        • HealthCheck
      • FX Rate inquiry
        • FXRateInquiry
        • FXRateInquiry
  1. Online payments scenes

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.
TIP
If you need to bind the card while authorizing, EVO Cloud 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 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.
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 Cloud. Just can complete the authentication via alternative methods and then bind a card solely through EVO Cloud.
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.
Card TransactionToken Transaction
paymentMethod.typecardtoken
paymentMethod.cardExistsDoes not exist
paymentMethod.tokenDoes not existExists
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 Cloud 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 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.
Request ParameterDescription
userReferenceUse the userReference set when creating the Gateway Token to query all associated Gateway Tokens.
tokenSpecify 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 ParameterDescription
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.
paymentMethodTypeOnly 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 ParameterDescription
paymentMethod.card.encryptedCardInfoIndicates 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 Cloud 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.cardInfoEncryptMethodIndicates 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 Cloud 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 ParameterDescription
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 ParameterDescription
tokenSpecify 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 ParameterDescription
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.
Previous
DCC
Next
Payment
Built with