Manage token
用户可能需要更新已保存的支付方式，或删除之前保存的某个支付方式。你可以先查询该用户已保存的支付方式，再处理用户的请求。
查询网关令牌
查询某个用户已保存的网关令牌，从服务端向 EVO Payment 发起 HTTP GET 请求：
/g2/v1/payment/mer/{sid}/paymentMethod
并传入以下任一参数：
| Query 参数 | 是否必填 | 说明 |
|---|---|---|
userReference | O | 用户标识。传入后，返回该用户保存的全部支付方式。 |
token | O | 某个已保存支付方式的令牌值。传入后，返回该令牌值对应的支付方式。 |
如果两个参数同时传入，会忽略 userReference。
以下示例查询某个用户保存的全部支付方式：
js
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"应答中的 paymentMethodList 数组包含该用户已保存的支付方式。
js
{
"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"
}
}
]
}更新网关令牌
卡支付场景下，用户可以申请修改已保存的支付方式。网关令牌关联的信息包括：卡号、有效期（卡片的月份和年份）、持卡人姓名（可选）。
- 可以更新的内容：卡片的
expiryDate和holderName，以及令牌的userReference、vaultID和tokenValidDays。 - 更新以上信息后，网关令牌值不变。
- 如果用户换成新卡号，需要作为新的网关令牌保存。
电子钱包令牌（包括 WeChat Pay 和 Alipay）只能更新 userReference 和 vaultID。
更新令牌信息时，从服务端向 EVO Payment 发起 HTTP PUT 请求：
/g2/v1/payment/mer/{sid}/paymentMethod
并传入以下参数：
| Query 参数 | 是否必填 | 说明 |
|---|---|---|
| token | M | 要更新的已保存支付方式的令牌值。 |
| Body 参数 | 是否必填 | 说明 |
|---|---|---|
paymentMethod | M | - 更新电子钱包：paymentMethod.type 设为 e-wallet，并传入要更新的 userInfo.reference 和/或 paymentMethod.e-wallet.vaultID。- 更新卡： paymentMethod.type 设为 card，并传入要更新的 paymentMethod.card.cardInfo.expiryDate、paymentMethod.card.cardInfo.holderName、userInfo.reference、paymentMethod.card.vaultID 和/或 paymentMethod.card.tokenValidDays。tokenValidDays 传 0 表示令牌永久有效；传 1-365 表示从请求当日起延长 1–365 天有效期。 |
metadata | O | 商户自定义的参考信息，请求中传入后会在应答中原样回显。 |
示例：
js
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"
}'以下为应答示例，paymentMethod 对象中是更新后的令牌信息：
js
{
"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"
}删除网关令牌
用户可能要求删除某个已保存的支付方式，或注销在你平台上的账户。删除用户已保存支付方式的令牌时，从服务端向 EVO Payment 发起 HTTP DELETE 请求：
/g2/v1/payment/mer/{sid}/paymentMethod
并传入以下参数：
| Query 参数 | 是否必填 | 说明 |
|---|---|---|
userReference | O | 用户标识。传入后，停用该用户保存的全部支付方式。 |
token | O | 某个已保存支付方式的令牌值。传入后，停用该令牌值对应的支付方式。 |
| Body 参数 | 是否必填 | 说明 |
|---|---|---|
metadata | O | 商户自定义的参考信息，请求中传入后会在应答中原样回显。 |
initiatingReason | O | 本次请求的原因。用户删除 WeChat Pay 令牌时必填。 |
两个 Query 参数任选其一传入；如果同时传入，会忽略 userReference。
以下示例停用某个用户保存的全部支付方式：
js
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"
}'以下为应答示例，paymentMethodList 数组中是已删除的令牌信息。
js
{
"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"
}
}
]
}删除网络令牌
删除网关令牌时，其下关联的网络令牌也会一并删除。
异常处理
向 EVO Payment 发起的 HTTP PUT / GET / DELETE 请求：
- HTTP PUT / GET / DELETE 请求是幂等的。如果在一定时间内（例如 45 秒）没有收到 EVO Payment 的应答，可以用完全相同的报文重新发送。
- 多次重发仍未收到应答时，请联系你的 EVO Payment 客户经理协助处理。
