Payment
步骤 1：获取可用支付方式
当用户准备支付或进入支付页面时，获取可用支付方式列表，以及每种支付方式需要用户填写的信息。
我们强烈建议调用以下接口，确保始终向用户展示最新的支付方式列表，但此步骤为可选步骤。您也可以缓存接口响应，每周更新一次。
您可以从服务端向 EVO Payment 以下接口发起 HTTP GET 请求：
/g2/v1/payment/mer/{sid}/paymentMethod
并指定以下任一参数：
| 查询参数 | 是否必填 | 说明 |
|---|---|---|
paymentBrand | O | 您计划向用户提供的指定支付品牌。传入该参数后，响应将返回该支付品牌下可用的支付方式及支付信息。 |
cardBIN | O | 用户计划用于支付的指定卡 BIN。传入该参数后，响应将返回该卡 BIN 下可用的支付方式及支付信息。 |
Currency | O | 用户计划用于支付的指定币种。传入该参数后，响应将返回该币种下可用的支付方式及支付信息。 |
Tokenize | O | 布尔类型字段，用于查询支持令牌化的支付方式。取值为 true 时，将返回支持令牌化的支付方式及支付信息。 |
每次请求只允许使用以上一个参数。如果同时传入多个参数，系统将按照 cardBIN、paymentBrand、currency 的优先级进行响应。
如果未指定任何查询参数，系统将根据您与 EVO Payment 的接入情况，返回全部支付方式及需要收集的支付信息。
以下是不带任何查询参数的请求示例：
curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod \
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"响应中的 paymentBrandList 数组包含可用支付方式列表，每种支付方式包含以下字段：
- brandName：支付方式的品牌名称。
- brandImage：支付方式的 Logo 图片 URL，用于在支付页面展示 Logo。
- paymentInfo：卡组织或电子钱包发起支付所需的支付信息。
- authenticationInfo：卡组织发起用户身份认证所需的认证信息。
- promotionInfo：该支付方式支持的优惠活动名称列表。
更多详情请参阅《EVO Payment API 规范》。
以下是响应示例：
{
"result": {
"code": "S0000",
"message": "Success"
},
"paymentMethod": {
"paymentBrandList": [
{
"brandName": "Visa",
"brandImage": "https://VISA_LOGO_IMAGE_URL.com",
"type": "card",
"paymentInfo": [
{
"key": "Card Number",
"optional": false,
"type": "number",
"minLength": "12",
"maxLength": "19"
},
{
"key": "Expiry date",
"optional": false,
"type": "number",
"minLength": "4",
"maxLength": "4",
"defaultValue": "MMYY",
"regEx": "/^(0[1-9]|1[0-2]){2}$/"
},
{
"key": "CVC",
"optional": true,
"type": "number",
"minLength": "3",
"maxLength": "4"
},
{
"key": "Cardholder Name",
"optional": true,
"type": "string",
"maxLength": "50"
}
],
"authenticationInfo": [
{
"key": "Card Number",
"optional": false,
"type": "number",
"minLength": "12",
"maxLength": "19"
},
{
"key": "Cardholder Name",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Cardholder Email",
"optional": true,
"type": "string",
"maxLength": "254",
"regEx": "/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/"
},
{
"key": "Billing Address",
"optional": true,
"type": "Object"
},
{
"key": "Billing Address",
"subKey": "Country",
"optional": false,
"type": "string"
},
{
"key": "Billing Address",
"subKey": "State Or Province",
"optional": true,
"type": "string"
},
{
"key": "Billing Address",
"subKey": "City",
"optional": false,
"type": "string",
"maxLength": "50"
},
{
"key": "Billing Address",
"subKey": "addressLine1",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Billing Address",
"subKey": "addressLine2",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Billing Address",
"subKey": "addressLine3",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Billing Address",
"subKey": "Postal Code",
"optional": false,
"type": "string"
},
{
"key": "Delivery Address",
"optional": true,
"type": "Object"
},
{
"key": "Delivery Address",
"subKey": "Country",
"optional": false,
"type": "string"
},
{
"key": "Delivery Address",
"subKey": "State Or Province",
"optional": true,
"type": "string"
},
{
"key": "Delivery Address",
"subKey": "City",
"optional": false,
"type": "string",
"maxLength": "50"
},
{
"key": "Delivery Address",
"subKey": "addressLine1",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Delivery Address",
"subKey": "addressLine2",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Delivery Address",
"subKey": "addressLine2",
"optional": true,
"type": "string",
"maxLength": "50"
},
{
"key": "Delivery Address",
"subKey": "Postal Code",
"optional": false,
"type": "string"
}
]
},
{
"brandName": "Alipay",
"type": "e-wallet",
"brandImage": "https://ALIPAY_LOGO_IMAGE_URL.com"
},
{
"brandName": "AlipayHK",
"type": "e-wallet",
"brandImage": "https://ALIPAYHK_LOGO_IMAGE_URL.com"
},
{
"brandName": "Alipay+",
"type": "e-wallet",
"brandImage": "https://ALIPAYPLUS_LOGO_IMAGE_URL.com",
"promotionInfo": [
"en_US":"RM1 Voucher",
"zh_CN":"1元 红包"
]
},
]
}
}如果您希望引导用户在前端页面或客户端 APP 中完成支付，可以使用 paymentMethod.paymentBrandList.paymentInfo 展示支付方式列表，以及每种支付方式需要填写的支付信息。
如果您希望引导用户完成支付认证，可以使用 paymentMethod.paymentBrandList.authenticationInfo。详情请参阅 Authentication（认证） 章节。
如有需要，您也可以自行添加额外的提示或格式校验。
请注意，以下字段在从用户处收集后、发送给 EVO Payment 之前，您需要确保请求符合 ISO 规范。详情请参阅《EVO Payment API 规范》。
| paymentBrandList 中的键名 | EVO Payment API 中的字段名 | ISO 规范 |
|---|---|---|
| Country（Delivery Address 中） | userInfo.deliveryAddress.country | ISO-3166-1 alpha-3，例如 SGP。 |
| State or Province（Delivery Address 中） | userInfo.deliveryAddress.stateOrProvince | ISO-3166-2，例如 North East。 |
| Country（Billing Address 中） | userInfo.billingAddress.country | ISO-3166-1 alpha-3，例如 SGP。 |
| State or Province（Billing Address 中） | userInfo.billingAddress.stateOrProvince | ISO-3166-2，例如 North East。 |
步骤 2：收集用户支付信息
根据每种支付方式要求的字段收集用户的支付信息，然后发送到您的服务端。
请注意，如果用户选择使用银行卡支付，商户必须满足 PCI DSS 合规要求。您可以通过以下 2 种方式收集卡信息：
使用 EVO Payment 客户端方案对用户卡信息进行安全加密。该方式可确保您满足 PCI DSS 合规要求，您只需提交 PCI DSS 自评估问卷 A（SAQ A）。详情请参阅《EVO Payment SDK 集成指南》。
收集并发送卡片明文数据。该方式要求您按照 PCI DSS 自评估问卷 D（SAQ D）评估自身的 PCI DSS 合规情况，这是范围最广的自我认证形式。
步骤 3：发起支付
用户选择支付方式并提交所需支付信息后，您需要向 EVO Payment 发起支付请求。
您可以从服务端向 EVO Payment 以下接口发起 HTTP POST 请求：
/g2/v1/payment/mer/{sid}/payment
并指定以下参数：
| Body 参数 | 是否必填 | 说明 |
|---|---|---|
merchantTransInfo | M | 支付的参考信息，包括唯一的 merchantTransID，以及表示您发起请求时间的 merchantTransTime。 |
transAmount | M | 支付的币种（currency）和金额（value）。金额必须符合该币种的最小单位规则。 |
paymentMethod | M | 使用 paymentMethod.type 指定支付方式类型，例如 e-wallet 或 card，并携带上一步收集的对应支付信息。 |
transInitiator | M | 发起交易的设备信息。 |
storeInfo | O | 补充的门店信息。当您的门店在 EVO Payment 中配置了多个 MCC 时，需通过该字段指明本次支付使用的 MCC。 |
tradeInfo | O | 当 paymentMethod.e-wallet.paymentBrand 为 Alipay 时必填，用于说明本次支付的详细信息。 |
userInfo | O | 买家的详细信息。如果您能获取用户信息，请传入该参数，有助于 EVO Payment 进行反洗钱和欺诈检测，并提升支付成功率。 |
validTime | O | 当 paymentMethod.type 为 e-wallet 时适用，表示订单的有效时间（分钟）。支付只能在该时间之前完成。如对该值有特殊要求，请联系 EVO Payment 客户经理获取详情和建议。 |
returnURL | O | 用户完成或取消支付后，跳转回您页面的 URL。 |
Webhook | O | 接收通知的 URL。传入该参数后，支付成功时将收到 EVO Payment 的通知。 |
Metadata | O | 您可在请求中自定义的参考信息，会在响应中原样返回。除 GET 请求外，响应中的 metadata 与您请求中的 metadata 相同；GET 响应中的 metadata 与 POST 请求中的 metadata 相同；通知中的 metadata 也与 POST 请求中的 metadata 相同。 |
paymentMethod 对象的更多说明：
A. 用户选择电子钱包支付时：
paymentMethod.type：请求中设置为 e-wallet。paymentMethod.e-wallet.paymentBrand：用户选择的电子钱包支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。paymentMethod.e-wallet.subOpenID：用户在您的微信小程序中的用户 ID。当用户在您的微信小程序（transInitiator.platform为 MINI）中使用微信支付（paymentMethod.e-wallet.paymentBrand为 WeChat_Pay）时必填。用户登录您的微信小程序时可获取该 ID。paymentMethod.e-wallet.subAppID：微信分配的 APP ID。当用户在您的微信小程序（transInitiator.platform为 MINI）或客户端 APP（transInitiator.platform为 APP）中使用微信支付（paymentMethod.e-wallet.paymentBrand为 WeChat_Pay）时必填。您在微信注册小程序或 APP 时可获取该 ID。paymentMethod.e-wallet.mobilePhone：用户在电子钱包中注册的手机号。当用户使用 TrueMoney 钱包支付时必填。
B. 用户选择银行卡支付时：
paymentMethod.type：请求中设置为 card。paymentMethod.card.encryptedCardInfo：加密后的卡信息。如果您使用 EVO Payment 客户端方案对用户卡信息进行安全加密，前端会从 EVO Payment SDK 获取该值，您需要将其发送到服务端，再由服务端将原始数据转发给 EVO Payment。paymentMethod.card.cardInfo：卡信息明文数据。如果您收集并向 EVO Payment 发送卡片明文数据，需要在该对象中传入 cardNumber、expiryDate、cvc（可选）和 holderName。对于部分银联借记卡，expiryDate 也是可选的。（如果同时传入
paymentMethod.card.encryptedCardInfo和paymentMethod.card.cardInfo，将以paymentMethod.card.cardInfo为准。）
C. 用户选择银联 SecurePay 支付时：
paymentMethod.type：请求中设置为 onlineBanking。paymentMethod.onlineBanking.paymentBrand：支付方式的支付品牌，必填。请求中设置为 UnionPay。paymentMethod.onlineBanking.encryptedCardInfo：加密后的卡信息。如果您使用 EVO Payment 客户端方案对用户卡信息进行安全加密，前端会从 EVO Payment SDK 获取该值，您需要将其发送到服务端，再由服务端将原始数据转发给 EVO Payment。paymentMethod.onlineBanking.cardInfo：卡信息明文数据。如果您收集并向 EVO Payment 发送卡片明文数据，可选择在该对象中传入 cardNumber。（如果同时传入
paymentMethod.onlineBanking.encryptedCardInfo和paymentMethod.onlineBanking.cardInfo，将以paymentMethod.onlineBanking.cardInfo为准。）
D. 用户选择网银支付时：
paymentMethod.type：请求中设置为 onlineBanking。paymentMethod.onlineBanking.paymentBrand：用户选择的网银支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。
E. 用户选择积分支付时：
paymentMethod.type：请求中设置为 points。paymentMethod.points.paymentBrand：用户选择的积分支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。
F. 用户选择银行转账支付时：
paymentMethod.type：请求中设置为 bankTransfer。paymentMethod.bankTransfer.paymentBrand：用户选择的银行转账支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。paymentMethod.bankTransfer.name：用户的名和姓。当 paymentBrand 为 Bank_Transfer_JPN 或 PayEasy 时，需要在该对象中传入 givenName 和 familyName。对象详情请参阅《EVO Payment API 规范》。paymentMethod.bankTransfer.mobilePhone：用户手机号。当 paymentBrand 为 Bank_Transfer_JPN 或 PayEasy 时必须传入。
G. 用户选择先买后付（Buy Now Pay Later）时：
paymentMethod.type：请求中设置为 buyNowPayLater。paymentMethod.buyNowPayLater.paymentBrand：用户选择的先买后付支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。userInfo.name：用户姓名。当 paymentBrand 为 Paidy 时必须传入。userInfo.shippingAddressCity：用户所在城市名称。当 paymentBrand 为 Paidy 时必须传入。userInfo.shippingAddressLine1：用户所在的楼宇名称和房间号。当 paymentBrand 为 Paidy 时必须传入。userInfo.shippingAddressLine2：用户所在的区域、地号及地号扩展信息。当 paymentBrand 为 Paidy 时必须传入。userInfo.shippingAddressState：用户所在的州或都道府县名称。当 paymentBrand 为 Paidy 时必须传入。userInfo.shippingAddressPostalCode：用户地址所属的邮政编码。当 paymentBrand 为 Paidy 时必须传入。userInfo.shippingAddressCountry：用户所在国家名称。当 paymentBrand 为 Paidy 时必须传入。
H. 用户选择运营商代扣（Carrier Billing）支付时：
paymentMethod.type：请求中设置为 carrierBilling。paymentMethod.carrierBilling.paymentBrand：用户选择的运营商代扣支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。
I. 用户选择预付卡支付时：
paymentMethod.type：请求中设置为 prepaidCard。paymentMethod.prepaidCard.paymentBrand：用户选择的预付卡支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。paymentMethod.prepaidCard.prepaidNumber：预付卡卡号。使用预付卡支付时必须传入。
J. 用户选择现金支付时：
paymentMethod.type：请求中设置为 cash。paymentMethod.cash.paymentBrand：用户选择的现金支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。
K. 用户选择 Google Pay™️ 支付时：
paymentMethod.type：请求中设置为 googlePay。paymentMethod.googlePay.paymentBrand：用户选择的 Google Pay™️ 支付品牌，必填。完整支付品牌列表请参阅《EVO Payment API 规范》。
如需实现以下功能，您需要在支付请求中添加额外参数：
对用户支付信息进行令牌化。详情请参阅 Tokenization（令牌化）章节。
使用 3D Secure 或 SecurePlus 对用户进行认证。详情请参阅 Authentication（认证）章节。
预授权冻结资金，稍后再请款。详情请参阅 After Payment（支付后处理）章节。
以下是使用 Alipay 发起 10 USD 支付的示例：
curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment \
-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 '{
"merchantTransInfo": {
"merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
"merchantTransTime": "2021-12-31T08:30:59+08:00"
},
"transAmount": {
"currency": "USD",
"value": "10.00"
},
"validTime": "120",
"returnURL": "https://YOUR_COMPANY.com/RETURNURL",
"paymentMethod": {
"type": "e-wallet",
"e-wallet": {
"paymentBrand": "Alipay"
}
},
"transInitiator": {
"platform": "WEB"
},
"tradeInfo": {
"tradeType": "Sale of goods",
"goodsName": "iPhone 13",
"goodsDescription": "This is an iPhone 13",
"totalQuantity": "2"
},
"webhook": "https://YOUR_COMPANY.com/WEBHOOK",
"metadata": "This is a metadata"
}'如果响应中没有返回 action 对象，您可以直接进入步骤 7，根据 result.code 和 payment.status 向用户展示支付结果。
否则，需要执行后续步骤才能完成支付。您需要将 action 对象发送到前端页面或客户端 APP，然后进入下一步。
以下是返回需要跳转的 action 对象的响应示例：
{
"result": {
"code": "S0000",
"message": "Success",
"pspResponseCode": "PAYMENT_IN_PROCESS",
"pspMessage": "Payment is processing."
},
"action": {
"type": "redirectUser",
"redirectData": {
"url": "https://ALIPAY_REDIRECT_URL.com",
"method": "GET"
}
},
"paymentMethod": {
"e-wallet": {
"paymentBrand": "Alipay"
}
},
"payment": {
"status": "Pending",
"merchantTransInfo": {
"merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
"merchantTransTime": "2021-12-31T08:30:59+08:00"
},
"evoTransInfo": {
"evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
"evoTransTime": "2021-12-31T00:30:59Z"
},
"pspTransInfo": {
"pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
"pspTransTime": "2021-12-31T08:30:59+08:00"
},
"transAmount": {
"currency": "USD",
"value": "10.00"
}
},
"pspData": {
"name": "Alipay"
},
"metadata": "This is a metadata"
}步骤 4：执行后续操作
如果您的服务端在支付响应（/g2/v1/payment/mer/{sid}/payment）中收到 action 对象，需要根据 action.type 执行下一步操作。
| Action 类型 | 说明 | 后续步骤 |
|---|---|---|
threeDSRedirect | 适用于 3DS 1 或 3DS 2 认证场景，此时 paymentMethod.type 为 card，authentication.type 为 threeDSPage 或 threeDSIntegrator。 | 使用同一响应中的 action.threeDSData，将用户跳转到其他网站完成 3DS 1 或 3DS 2 认证。详情请参阅 Authentication（认证）章节。 |
threeDSIdentify | 适用于 3DS 2 认证场景，此时 paymentMethod.type 为 card，authentication.type 为 threeDSIntegrator。 | 使用同一响应中的 action.threeDSData，将用户跳转到其他网站完成 3DS 2 无感认证（frictionless）。详情请参阅 Authentication（认证）章节。 |
threeDSChallenge | 适用于 3DS 2 认证场景，此时 paymentMethod.type 为 card，authentication.type 为 threeDSIntegrator。 | 使用同一响应中的 action.threeDSData，将用户跳转到其他网站完成 3DS 2 挑战认证（challenge）。详情请参阅 Authentication（认证）章节。 |
inputMobilePhone | 适用于 SecurePlus 认证，此时 paymentMethod.type 为 card，authentication.type 为 SecurePlus。 | 在支付页面展示输入框，请用户输入手机号并提交给 EVO Payment。详情请参阅 Authentication（认证）章节。 |
inputSMSCode | 适用于 SecurePlus 认证，此时 paymentMethod.type 为 card，authentication.type 为 SecurePlus。 | 在支付页面展示输入框，请用户输入手机收到的短信验证码并提交给 EVO Payment。详情请参阅 Authentication（认证）章节。 |
redirectUser | 适用于需要跳转的支付和认证场景，涉及以下支付方式和支付品牌： (a) PC WEB 上的 Alipay、Alipay+ 和 JkoPay。 (b) 移动端 WAP 上的 Alipay、Alipay+、Alipay HK、微信支付和 Jkopay。 (c) 微信公众号中的微信支付。 (d) PC WEB 和移动端 WAP 上的银联 SecurePay。 | 使用 action.redirectData.method 指定的 HTTP 方法，将用户跳转到 action.redirectData.url。如果 action.redirectData.method 为 POST 且存在 action.redirectData.parameter，需将 parameter 对象中的子字段作为 POST 请求的表单数据。用户随后会跳转到对应页面，根据 PSP 的要求完成后续操作。用户完成支付后，会通过 HTTP GET 或 POST 跳转回您的 returnURL。您可以忽略该跳转，也可以在获取支付结果前向用户展示加载页面。1. 您可以选择从服务端向 EVO Payment 接口 /g2/v1/payment/mer/{sid}/payment 发起 HTTP GET 请求获取支付结果。详情请参阅步骤 6。2. 或者等待通知 Webhook 获取支付结果。详情请参阅 After Payment（支付后处理）章节。 |
redirectInIframe | 适用于使用 AlipayHK 商户账户在 PC WEB 上进行的电子钱包支付，包括用户使用 AlipayHK 钱包 APP 和 Alipay 钱包 APP 支付。 | 在支付页面渲染一个 iframe，并在 iframe 中使用 action.redirectData.method 指定的 HTTP 方法跳转到 action.redirectData.url。如果 action.redirectData.method 为 POST 且存在 action.redirectData.parameter，需将 parameter 对象中的子字段作为 POST 请求的表单数据。随后 iframe 中会展示二维码，用户需使用电子钱包 APP 扫码支付。1. 您可以选择从服务端向 EVO Payment 接口 /g2/v1/payment/mer/{sid}/payment 发起 HTTP GET 请求获取支付结果。详情请参阅步骤 6。2. 或者等待通知 Webhook 获取支付结果。详情请参阅 After Payment（支付后处理）章节。 |
presentQRCode | 适用于在 PC WEB 上使用微信支付的电子钱包支付。 | 使用 action.qrData 对象中的数据渲染二维码。随后向用户展示二维码，用户需使用电子钱包 APP 扫码支付。1. 您可以选择从服务端向 EVO Payment 接口 /g2/v1/payment/mer/{sid}/payment 发起 HTTP GET 请求获取支付结果。详情请参阅步骤 6。2. 或者等待通知 Webhook 获取支付结果。详情请参阅 After Payment（支付后处理）章节。 |
invokeWallet | 适用于： (a) 在钱包 APP 和小程序中使用微信支付或支付宝的电子钱包支付。 (b) 在钱包 APP 中使用银联 SecurePay。 | 1. 使用 action.walletData.paymentString 调起钱包 SDK，切换到钱包 APP。请参阅微信支付 APP 支付集成指南、支付宝 APP 支付集成指南或银联 APP 内支付集成指南。您也可以选择使用 EVO Payment SDK 实现相同功能，详情请参阅《EVO Payment SDK 集成指南》。用户随后会切换到钱包 APP，并在其中完成后续支付操作。2. 用户完成支付后，会通过您调起 SDK 时指定的回调函数跳转回来。您可以在获取支付结果前向用户展示加载页面。 3. 您可以选择从服务端向 EVO Payment 接口 /g2/v1/payment/mer/{sid}/payment 发起 HTTP GET 请求获取支付结果。详情请参阅步骤 6。4. 或者等待通知 Webhook 获取支付结果。详情请参阅 After Payment（支付后处理）章节。 |
presentEcontext | 适用于现金支付和银行转账。 | 在支付页面展示 action.econtext 对象中的文本，请用户完成后续支付流程。如果返回了 action.econtext.instructionURL 字段，也可以在支付页面展示该链接以引导用户。 |
以下是处理 redirectUser、redirectInIframe、presentQRCode 和 invokeWallet 时，前端需要执行操作的更多说明。
A. redirectUser
如果 action.redirectData.method 为 GET，将用户跳转到 action.redirectData.url。
curl {action.redirectData.url}
如果 action.redirectData.method 为 POST 且存在 action.redirectData.parameter，例如用户在 PC WEB 或移动端 WAP 上使用银联 SecurePay 支付时，action.redirectData.parameter 示例如下：
{
"accNo": "ZgTg0d4%2BWJeM7GBq9EbxjSu0wvQQYpS8%2F%2B9NJ848bx1tLlqWc%2FbtUSzFiMaKaFHNEJMT3PPvv8RY8C9lcOeoWJpFBUA4en%2FSw2OlqY%2Fmj1zcikLMg5O4XgO8aqELQUDZNin1mtlkDGx1%2B%2FR9NNX4a%2F2E8x2%2Fme4haxUdO%2BVY76v7edaj30pR2n%2BbLfB70pDnc9XisZrL5cNPE9Wj83Mirh2rLwEtreS%2FktCYqzpopLEcu115sd%2BJOdj1E0z3Bp2x5EBLrdiz714kOV0FmY7HQz0UfwV3MnY7PofuQ7MwnilYYnTsFBcTKxNpSwAZlZAB0eSijnFpIG3tYjnIephVFg%3D%3D",
"accessType": "1",
"acqInsCode": "YOUR_ACQUIRER_IIN",
"backUrl": "https%3A%2F%2F%7BEVO_Cloud_DOMAIN_NAME.com%7D%2FpspNotify%2FUPI%2F%7BYOUR_ACQUIRER_IIN%7D",
"bizType": "000201",
"certId": "69798631478",
"channelType": "07",
"currencyCode": "840",
"encoding": "UTF-8",
"encryptCertId": "69026275926",
"frontUrl": "https%3A%2F%2FYOUR_COMPANY.com%2FRETURNURL",
"merAbbr": "AbbrName",
"merCatCode": "5411",
"merId": "999290058120001",
"merName": "This is your merchant name",
"orderId": "YOUR_TRANS_ID",
"payTimeout": "20211231183059",
"signMethod": "01",
"signature": "EashQx%2F4eLvGenbKThFNeqssyg6tSXlj5mT3GbF2ll9TV8ObzqYpMd%2Fl2Ymv0UKkWOi05QeRM9c2UajjzAM92CUGp8KhVkfcK4BUH1BXNgAWAEZwB8ZLLuMPvnTQZJ%2F03HQ6hOeyIXOCE1lOm4HlL9n5B5bg2ACRFpxK%2FmGVPZ%2FuGumAMyEWq5%2B8HwRlcTBepzDYNuSqCLegofT7bTAQZIELf%2BjxKSgV3D3cCI9PwOg44uFlRwSdtg%2Fr0FnIh%2BhQTVDgY0ttJm99GWYwJIKzdsEdN9tihpgxJVoxveoJBwll2M6mrv7THXMFvI3p3zFCpLIjU%2FxqvvUQmViYC3lniA%3D%3D",
"txnAmt": "1000",
"txnSubType": "01",
"txnTime": "20211231083059",
"txnType": "01",
"version": "5.1.0"
}B. redirectInIframe
与处理 redirectUser 类似，但您需要在支付页面渲染的 iframe 内发起 HTTP GET 或 POST 请求。建议将 iframe 尺寸设置为 200x200 px。
C. presentQRCode
使用 action.qrData 对象中的数据渲染二维码并展示给用户。action.qrData 包含以下内容：
action.qrData.qrCode：二维码内容，UTF-8 字符串，用于渲染二维码。
action.qrData.qrDownloadURL：二维码下载地址。未返回
action.qrData.qrCode时会返回该字段。action.qrData.expiredAt：支付过期的日期和时间，例如：
2017-07-17T13:42:40+01:00。
D. invokeWallet
如果您选择使用钱包 SDK，请参阅对应钱包的 SDK 指南了解如何调起 SDK。
如果您使用 EVO Payment SDK，请参阅《EVO Payment SDK 集成指南》。您可以联系 EVO Payment 客户经理获取这些指南。
步骤 5：提交补充支付信息
当支付方式为银行卡且用户进行了认证流程时，您需要向 EVO Payment 提交补充支付信息以完成支付。详情请参阅 Authentication（认证）章节。
步骤 6：查询支付结果
当支付方式为电子钱包时，如果您将用户跳转到其他网站或 APP，或向用户展示二维码进行扫码支付，且未使用 Accept Notification（接收通知）Webhook，您可以向 EVO Payment 发起请求查询支付结果。
您可以从服务端向 EVO Payment 以下接口发起 HTTP GET 请求：
/g2/v1/payment/mer/{sid}/payment
并指定以下参数：
| 参数 | 是否必填 | 说明 |
|---|---|---|
| merchantTransID | M | 待查询支付的 merchantTransInfo.merchantTransID。 |
查询支付结果示例：
curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_PAYMENT} \
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"如果响应中返回了 action 对象，与步骤 3 类似，需要执行后续步骤才能完成支付。您需要将 action 对象发送到前端页面或客户端 APP，然后返回步骤 4 执行所需操作。
如果没有返回 action 对象，您可以进入步骤 7，根据 result.code 和 payment.status 向用户展示支付结果。
如果支付已完成，响应中会返回 payment 对象，展示本次支付的详细信息：
payment.status：本次请款的状态，必填，取值可为 Verifying、Verified、Pending、Authorised、Cancelling、Cancelled、Capturing、Captured、Refunding、Refunded、Partial Refunded 或 Failed。详情请参阅《EVO Payment API 规范》。payment.failureCode：支付的错误码，当 payment.status 为 Failed 时返回。payment.failureReason：支付的错误信息，当 payment.status 为 Failed 时返回。payment.transAmount：支付的币种和金额，必填，从您的请求中原样返回。payment.merchantTransInfo：支付的参考信息对象，必填，由您的服务端生成，从您的请求中原样返回。payment.evoTransInfo：支付的参考信息对象，必填，由 EVO Payment 生成。包含 evoTransID、evoTransTime、traceNum（可选），以及部分 PSP（如 Visa 或 Mastercard）的 retrievalReferenceNum。payment.pspTransInfo：请款的参考信息对象，可选，由 PSP 生成。包含 pspTransID、pspTransTime 和 authorizationCode。如果 PSP 返回了这些信息，EVO Payment 会将其转发给您的服务端。payment.billingAmount和payment.billingFXRate：用户账单币种及金额，以及 payment.transAmount.currency 与 payment.billingAmount.currency 之间的汇率（如有）。如果 PSP 返回了这些信息，EVO Payment 会将其转发给您的服务端。适用于 PSP 进行货币转换的部分电子钱包支付场景，或您开通 DCC 功能的部分银行卡支付场景。详情请联系 EVO Payment 客户经理。payment.convertTransAmount和payment.convertTransFXRate：交易发送至 PSP 时，EVO Payment 根据 transAmount 及 transAmount.currency 到其他币种的汇率计算出的币种和金额，以及 payment.transAmount.currency 与 payment.convertTransAmount.currency 之间的汇率。当您在 EVO Payment 开通货币转换功能且本次请款使用了货币转换时，会提供该汇率。详情请联系 EVO Payment 客户经理。
以下是支付成功的响应示例：
{
"result": {
"code": "S0000",
"message": "Success",
"pspResponseCode": "SUCCESS",
"pspMessage": "success"
},
"paymentMethod": {
"e-wallet": {
"paymentBrand": "Alipay"
}
},
"payment": {
"status": "Captured",
"merchantTransInfo": {
"merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
"merchantTransTime": "2021-12-31T08:30:59+08:00"
},
"evoTransInfo": {
"evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
"evoTransTime": "2021-12-31T00:30:59Z"
},
"pspTransInfo": {
"pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
"pspTransTime": "2021-12-31T08:30:59+08:00"
},
"transAmount": {
"currency": "USD",
"value": "10.00"
}
},
"pspData": {
"name": "Alipay"
},
"metadata": "This is a metadata"
}步骤 7：展示支付结果
用户完成支付且前端或客户端 APP 无需执行后续操作后，您可以根据 result.code 和 payment.status 告知用户支付状态。
| Result Code | Description |
|---|---|
S0000 | Success |
V0008 | Field {} is not applied with |
C0004 | Request resource merchantTransID {XXX} not exist |
C0006 | Request resource vault ID {XXX} not exist |
C0008 | Request resource paymentMethod token {XXX} not exist |
B0005 | Unsupported function {XXX}, please check your profile setup in EVO Payment |
B0012 | Invalid transaction status {XXX} to complete the request |
B0019 | Authentication required, please ask user to input authentication info |
B0021 | {Payment / Tokenization} failed due to user authentication results with high risk, please ask user to try again |
其他可能的 result.code 取值以及可向用户展示的推荐提示语，请参阅*《EVO Payment API 规范》附录*。
如果 result.code 为 S0000，您需要检查 payment.status 来判断支付状态并告知用户。
| 状态 | 说明 |
|---|---|
| Authorised | 用于银行卡交易，表示交易授权已成功完成，等待请款（商户可提交撤销）。 |
| Captured | 银行卡交易表示授权和请款均已成功完成；电子钱包交易表示交易已成功完成。 |
| Failed | 支付失败。 |
其他可能的 payment.status 取值及说明，请参阅《EVO Payment API 规范》中的 payment.status。
异常处理
向 EVO Payment 发起 HTTP POST 请求时：建议请求发送后至少等待 45 秒。如果在该时间内未收到响应，需要按照步骤 6 发起请求，向 EVO Payment 查询结果。
向 EVO Payment 发起 HTTP GET 请求时：您可以多次发起请求直至获取结果，建议每次后续请求前至少等待 45 秒。如果多次请求后仍无法获取结果，可以根据您的请款模式发起 Cancel（撤销）或 Refund（退款）请求来取消该笔支付。详情请参阅 After Payment（支付后处理）章节。
