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 Payment endpoint

/g2/v1/payment/mer/{sid}/paymentMethod

and specify either parameter below.

Query Parameter	Required	Description
userReference	O	The reference for the user. With this parameter specified, you can retrieve all the payment method(s) stored for the user.
token	O	The 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:

curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?userReference={YOUR_USER_REFERENCE} \
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"

The paymentMethodList array in the response contains the user's stored payment method(s).

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethodList": [
        {
            "token": {
                "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
                "expiryDate": "2029-12-31T23:59:59+08:00",
                "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
                "vaultID": "11111902_00001",
                "createTime": "2021-12-31T00:30:59Z",
                "updateTime": "2021-12-31T00:30:59Z",
                "status": "enabled"
            },
            "e-wallet": {
                "paymentBrand": "Alipay"
            }
        },
        {
            "token": {
                "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
                "expiryDate": "2029-12-31T23:59:59+08:00",
                "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
                "vaultID": "11111902_00001",
                "fingerprint": "286fcea14de3eaf021f0304ca34d3f4c",
                "createTime": "2021-12-31T00:30:59Z",
                "updateTime": "2021-12-31T00:30:59Z",
                "status": "enabled"
            },
            "card": {
                "first6No": "476134",
                "last4No": "0019",
                "fundingType": "credit",
                "paymentBrand": "Visa"
            }
        }
    ]
}

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 Payment endpoint: /g2/v1/payment/mer/{sid}/paymentMethod

And specify the parameters below:

Query Parameter	Required	Description
token	M	The token value for the stored payment method to be updated.

Body Parameter	Required	Description
paymentMethod	M	- 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.
metadata	O	A self-defined reference information that you can specify in the request and will be echoed back in the response.

Here is an example:

curl -X PUT https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?token={YOUR_TOKEN_VALUE_TO_BE_UPDATED}\
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \
-d '{
    "paymentMethod": {
        "type": "e-wallet",
        "e-wallet": {
            "vaultID": "11111902_00002"
        }
    },
    "userInfo": {
        "reference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
    },
    "metadata": "This is a metadata"
}'

Here is an example of the response with the paymentMethod object to show the updated token information:

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethod": {
        "token": {
            "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
            "expiryDate": "2029-12-31T23:59:59+08:00",
            "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b25",
            "vaultID": "11111902_00002",
            "createTime": "2021-12-31T00:30:59Z",
            "updateTime": "2021-12-31T06:30:59Z",
            "status": "enabled"
        },
        "e-wallet": {
            "paymentBrand": "WeChat_Pay",
            "planID": "YOUR_PLAN_ID",
            "contractID": "YOUR_CONTRACT_ID",
            "subOpenID": "YOUR_SUB_OPEN_ID"
        }
    },
    "metadata": "This is a metadata"
}

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 Payment endpoint:

/g2/v1/payment/mer/{sid}/paymentMethod

and specify the parameters below.

Query Parameter	Required	Description
userReference	O	The reference for the user. With this parameter specified, you can disable all payment method(s) stored for the specific user.
token	O	The 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 Parameter	Required	Description
metadata	O	A self-defined reference information that you can specify in the request and will be echoed back in the response.
initiatingReason	O	You 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:

curl -X DELETE https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?userReference={YOUR_USER_REFERENCE} \
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"
-d '{
    "initiatingReason": "User logged out"
}'

Here is an example of the response with the paymentMethodList array to show the deleted token information.

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethodList": [
        {
            "token": {
                "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
                "expiryDate": "2029-12-31T23:59:59+08:00",
                "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
                "vaultID": "11111902_00001",
                "createTime": "2021-12-31T00:30:59Z",
                "updateTime": "2021-12-31T00:30:59Z",
                "status": "enabled"
            },
            "e-wallet": {
                "paymentBrand": "Alipay"
            }
        },
        {
            "token": {
                "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
                "expiryDate": "2029-12-31T23:59:59+08:00",
                "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
                "vaultID": "11111902_00001",
                "fingerprint": "286fcea14de3eaf021f0304ca34d3f4c",
                "createTime": "2021-12-31T00:30:59Z",
                "updateTime": "2021-12-31T00:30:59Z",
                "status": "enabled"
            },
            "card": {
                "first6No": "476134",
                "last4No": "0019",
                "fundingType": "credit",
                "paymentBrand": "Visa"
            }
        }
    ]
}

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 Payment:

• The HTTP PUT/GET/DELETE request is idempotent, meaning that if you don't receive a response from EVO Payment 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 Payment account manager for assistance.