1. Tokenization
Merchant Connect API
latest
  • latest
  • HASE
  • Version Record
  • Integration Guide
    • EC Payment
      • Merchant API
        • Overview
        • Payment
        • Payment Methods
        • Response code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
        • Features
          • Account Status Inquiry (ASI)
          • COF
          • Multi-Currency Transaction
          • Recurring
          • Smart Routing
          • Transaction Retry
          • Payout
          • Authentication
            • 3D Secure
            • FIDO Authentication
            • Authentication only
            • Authorization only
          • Tokenization
            • Gateway Tokenization
            • Create a gateway token
            • Network Tokenization
            • Pay with gateway token
            • Manage token
            • Network Token update notification
            • Card Based Network Token
    • In-store Payment
      • Merchant API（QR）
        • Payment
          • CPM
          • MPM
          • MPM static QR code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
      • Merchant API (Card)
        • ZPK
          • ZPK
        • Payment
          • Payment
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
  • API Explorer
    • API Rules
    • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
    • FXRateInquiry
      • FXRateInquiry
      • FXRateInquiry
    • Payment
      • Payment
      • Payment
      • Payment
    • Payout
      • Payout
      • Payout
    • Capture
      • Capture
      • Capture
    • Cancel
      • Cancel
      • Cancel
    • Refund
      • Refund
      • Refund
    • Cryptogram
      • Cryptogram
      • Cryptogram
    • Cancel or Refund
      • Cancel or Refund
      • Cancel or Refund
    • Notification
      • Notification for PaymentMethod
      • Notification for Payment
      • Notification for Capture
      • Notification for Cancel
      • Notification for Refund
      • Notification for DataSubmission
      • Notification for MPM Static QR Code
      • Notification for Token Status Update
      • Notification for Settlement
      • Notification for Reversal
      • Notification for Cryptogram
      • Notification for Payout
    • Appendix
      • Result Code
      • Payment Brands
      • Payment Method Variant
      • Currency list
      • Country and region list
      • Product Code
    • HealthCheck
      • HealthCheck
    • Coupon Write-off
      • Coupon Write-off
    • Coupon Reversal
      • Coupon Reversal
    • ZPK
      • ZPK
latest
  • latest
  • HASE
  1. Tokenization

Manage token

The user may need to update the payment method(s) stored or remove a previously stored payment method. You can retrieve a particular user's stored payment method(s) and complete the user's request.

Retrieve gateway token#

To see the gateway token(s) stored for a user, you can make an HTTP GET request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/paymentMethod
and specify either parameter below.
Query ParameterRequiredDescription
userReferenceOThe reference for the user. With this parameter specified, you can retrieve all the payment method(s) stored for the user.
tokenOThe token value for a specific stored payment method. With this parameter specified, you can retrieve the specific payment method stored with this token value.
If both parameters are specified, the parameter userReference will be ignored.
Here is an example of retrieving all the payment method(s) stored for a specific user:
The paymentMethodList array in the response contains the user's stored payment method(s).

Update gateway token#

For card payment, the user can request to change the stored payment method(s). The details associated with a gateway token are card number, expiry date (month and year of the card), and the cardholder name (optional). You can update the expiryDate and holderName of a card, and the userReference, vaultID, and tokenValidDays of the token. The gateway token value remains the same when you update these details. If the user updates with a new card number, you need to store it as a new gateway token.
For tokens of E-Wallet payment, including WeChat Pay and Alipay, only userReference and vaultID can be updated.
To update the token details, you can make an HTTP PUT request to EVO Cloud endpoint:
/g2/v1/payment/mer/{sid}/paymentMethod
And specify the parameters below:
Query ParameterRequiredDescription
tokenMThe token value for the stored payment method to be updated.
Body ParameterRequiredDescription
paymentMethodM- For E-Wallet updates: Specify paymentMethod.type as e-wallet with userInfo.reference and/or paymentMethod.e-wallet.vaultID that you are going to update.
- For Card updates: Specify paymentMethod.type as card with paymentMethod.card.cardInfo.expiryDate, paymentMethod.card.cardInfo.holderName, userInfo.reference, paymentMethod.card.vaultID, and/or paymentMethod.card.tokenValidDays that you are going to update. For tokenValidDays, specify 0 to set the token as permanently valid, or 1-365 to extend the valid time by 1-365 days from the request date.
metadataOA self-defined reference information that you can specify in the request and will be echoed back in the response.
Here is an example:
Here is an example of the response with the paymentMethod object to show the updated token information:

Remove gateway token#

A user may request to delete a certain stored payment method or remove their account on your platform. To delete the token(s) of a user's stored payment method(s), make an HTTP DELETE request to the EVO Cloud endpoint:
/g2/v1/payment/mer/{sid}/paymentMethod
and specify the parameters below.
Query ParameterRequiredDescription
userReferenceOThe reference for the user. With this parameter specified, you can disable all payment method(s) stored for the specific user.
tokenOThe token value for a specific stored payment method. With this parameter specified, you can disable the specific payment method stored with this token value.
Body ParameterRequiredDescription
metadataOA self-defined reference information that you can specify in the request and will be echoed back in the response.
initiatingReasonOYou can state the reason for the request in this field, which is required when the user is trying to delete the token for WeChat Pay.
You can specify either of the query parameters above, and if both specified, the userReference will be ignored.
Here is an example of disabling all the payment method(s) stored for a specific user:
Here is an example of the response with the paymentMethodList array to show the deleted token information.

Remove Network Token#

When you delete the gateway token, the associated network token under the gateway token will also be deleted.

Error Handling#

For HTTP PUT/GET/DELETE requests to EVO Cloud:
The HTTP PUT/GET/DELETE request is idempotent, meaning that if you don't receive a response from EVO Cloud within a certain time frame (e.g., 45 seconds), you can resend the request with exactly the same message.
If you still do not receive a response after several attempts, please contact your EVO Cloud account manager for assistance.
Previous
Pay with gateway token
Next
Network Token update notification
Built with