绑卡
绑卡
Gateway Token
EVO Cloud 支持您将消费者的卡信息存储在 EVO Cloud 的系统中，然后由 EVO Cloud 生成一个 Gateway Token，您可以在后续的交易中直接使用 Gateway Token 发起交易。
创建 Gateway Token
您有以下两种方式来创建 Gateway Token：
- 在授权的同时创建 Gateway Token
- 直接创建 Gateway Token
下面将分别为您介绍这两种方式的详细流程。
在授权的同时创建 Gateway Token
您可以在您现有的授权流程中进行绑卡，如果授权成功 EVO Cloud 将会在应答中同步返回 Gateway Token，如果授权失败，则绑卡也同时失败。
TIP
如果您需要在授权的同时进行绑卡，EVO Cloud 会要求同时对这笔交易进行 3DS 认证，关于 3DS 认证的详情请参考 3DS 章节。
主要流程如下：
您需要在
POST Payment的请求中额外添加以下参数：paymentMethod.card.tokenize：固定值true，表示在授权的同时绑卡。paymentMethod.card.payerReference：消费者标识，你可以自定义该字段的值。authentication：包含 3DS 认证相关信息的结构体，详情参考 3DS 章节。
检查 EVO Cloud 的应答，如果应答中存在
result.action字段，则表示该笔交易需要继续进行 3DS 认证（请参考 3DS 章节）。如果应答中不存在
result.action字段，则需要根据payment.status字段内容判断交易结果。如果字段的值为Captured、Authorised或Capturing（取决于captureAfterHours字段的值）则表示交易成功，同时您可以从应答中的paymentMethod.token.value字段中找到 Gateway Token 的值，否则就需要查看result.code以及result.message来查看交易失败原因。如果您没有收到来自 EVO Cloud 的应答报文，则需要您调用
GET Payment来查询交易结果。当收到查询应答时，您同样也需要通过payment.status字段内容来判断交易结果，判断方式与第 2 步一致。如果交易失败，您需要通过payment.failureCode以及payment.failureReason来查看交易失败原因。如果您在
POST Payment请求中上送了webhook并且交易的payment.status为Captured、Authorised或Capturing，您也可以通过异步通知来获取交易结果，异步通知中的eventCode为Payment。同样也需要通过payment.status字段内容来判断交易结果，判断方式与第 2 步一致。向消费者展示付款及绑卡结果。
直接创建 Gateway Token
如果您的消费者当前仅需要绑卡，你可以使用 POST PaymentMethod 或者 POST PaymentInstrument接口直接创建 Gateway Token。
TIP
- 使用
POST PaymentMethod直接创建 Gateway Token 时，EVO Cloud 会要求先进行 3DS 认证，关于 3DS 认证的详情请参考 3DS 章节。 - 使用
POST PaymentInstrument直接创建 Gateway Token 时，EVO Cloud 不会要求进行任何认证，由商户通过其他途径做完认证，仅在 EVO Cloud 完成绑卡。
PaymentMethod 主要流程如下：
在调用
PaymentMethod接口时需要包含但不限于以下参数，字段详情参考 API 文档：paymentMethod.type：表明支付方式的字段，如果是卡交易则使用card。paymentMethod.card：包含消费者卡信息的结构体。当paymentMethod.type为card时必填。merchantTransInfo：包含商户订单号等信息的结构体。pspInfo：包含卡组织资质信息的结构体。transInitiator：包含消费者设别信息的结构体。authentication：包含 3DS 认证相关信息的结构体，详情参考 3DS 章节。
检查 EVO Cloud 的应答，如果应答中存在
result.action字段，则表示该笔交易需要继续进行 3DS 认证（请参考 3DS 章节）。如果应答中不存在
result.action字段，则需要根据paymentMethod.status字段内容判断交易结果。如果字段的值为Success则表示 Token 创建成功，同时您可以从应答中的paymentMethod.token.value字段中找到 Gateway Token 的值，否则就需要查看result.code以及result.message来查看交易失败原因。如果您没有收到来自 EVO Cloud 的应答报文，则需要您调用
GET PaymentMethod来查询交易结果。当收到查询应答时，您同样也需要通过paymentMethod.status字段内容来判断交易结果，判断方式与第 2 步一致。如果交易失败，您需要通过paymentMethod.failureCode以及paymentMethod.failureReason来查看交易失败原因。如果您在
POST PaymentMethod请求中上送了webhook并且交易的paymentMethod.status为Success，您也可以通过异步通知来获取交易结果，异步通知中的eventCode为PaymentMethod。同样也需要通过payment.status字段内容来判断交易结果，判断方式与第 2 步一致。向消费者展示绑卡结果。
PaymentInstrument 主要流程如下：
在调用
PaymentInstrument接口时需要包含但不限于以下参数，字段详情参考 API 文档：merchantTransInfo：包含商户订单号等信息的结构体，作为 EVO Cloud 的 Gateway Token 的溯源信息。paymentMethod.type：表明支付方式的字段，如果是卡交易则使用card。paymentMethod.card：包含消费者卡信息的结构体。当paymentMethod.type为card时必填。paymentMethod.card.cardInfo.paymentBrand：表明卡品牌的字段，可选。（1）当不指定 PaymentBrand 时，可以不上送该字段，EVO Cloud 会通过卡号进行卡品牌判断，如果在 American_Express、Diners、JCB、Mastercard、UnionPay、Visa、MyDebit、TPN、NAPAS 卡品牌内，应答会返回对应的卡品牌，如果不在，则 EVO Cloud 不会返回卡品牌。（2）当指定 PaymentBrand 时，必须在 American_Express、Diners、JCB、Mastercard、UnionPay、Visa、MyDebit、TPN、NAPAS 这些品牌中选择上送，否则不生效。paymentMethod.merchantToken：包含商户自带的 Token 信息的结构体。当商户通过其他途径做完认证，拿到第三方的 Token 后，可选填，从而跟 EVO Cloud 的 Gateway Token 完成绑定。
检查 EVO Cloud 的应答，根据
result.message字段内容判断交易结果。如果字段的值为Success则表示 Token 创建成功，那么您可以从应答的paymentMethod.token.value字段中找到 Gateway Token 的值。否则就需要查看result.code以及result.message后在应答码章节找到交易的失败原因。如果您没有收到来自 EVO Cloud 的应答报文，则需要您调用
GET PaymentInstrument来查询交易结果。当收到查询应答时，您同样也需要通过result.message字段内容来判断交易结果，判断方式与第 2 步一致。如果交易失败，您需要通过查看result.code以及result.message后在应答码章节找到交易的失败原因。如果您在
POST PaymentInstrument请求中上送了webhook并且交易的result.message为Success，您也可以通过异步通知来获取交易结果，异步通知中的eventCode为PaymentInstrument。同样也需要通过result.message字段内容来判断交易结果，判断方式与第 2 步一致。向消费者展示绑卡结果。
使用 Gateway Token 进行支付
当您成功获取到了 Gateway Token 以后，就可以在您的授权请求中使用 Gateway Token 来替代卡信息来发起交易，交易流程与普通的授权交易一致，只需要您将 POST Payment 请求中的部分字段进行替换即可。
| 卡交易 | Token 交易 | |
|---|---|---|
paymentMethod.type | card | token |
paymentMethod.card | 存在 | 不存在 |
paymentMethod.token | 不存在 | 存在 |
TIP
- 使用
POST PaymentMethod直接创建的 Gateway Token 发起的交易同样支持 3DS 认证，流程与普通卡交易一致，详情参考 3DS 章节。 - 使用
POST PaymentInstrument创建的 Gateway Token，通过 EVO Cloud 完成支付，可以是 EVO Cloud Token，也可以是 Merchant Token，同样支持 3DS 认证，流程与普通卡交易一致，详情参考 3DS 章节。 - 使用
POST PaymentInstrument创建 Gateway Token，可以使用其他收单服务商完成支付，这时需要通过GET PaymentInstrument获取卡信息，之后到指定收单服务商完成支付。
管理 Gateway Token
消费者可能会需要更新（卡有效期更新）、删除（卡片停用）他们已经绑定过的卡片。 EVO Cloud 提供了查询、更新以及删除 Gateway Token 的能力。
查询 Gateway Token
- 您可以使用
GET PaymentMethod接口，通过指定不同参数的方式来查询由 PaymentMethod 接口创建的某一个 Gateway Token 或者某个消费者的所有 Gateway Token 的信息。
| 请求参数 | 描述 |
|---|---|
userReference | 通过您在创建 Gateway Token 时设置的 userReference，你可以查询到与这个 userReference 关联的全部的 Gateway Token |
token | 你可以通过指定一个 Gateway Token 的 value 来查询这个 Gateway Token 的全部信息 |
- 您可以使用
GET PaymentInstrument接口，通过指定不同参数的方式来查询由 PaymentInstrument 接口创建的某一个 Gateway Token 或者某笔订单关联的 Gateway Token 信息。同时会返回您想要的 Token 信息或卡信息，卡信息可以用于后续支付。
| 请求参数 | 描述 |
|---|---|
token | （1）您可以通过指定一个 Gateway Token 的 value 来查询这个 Gateway Token 的全部信息（2）或者通过指定一个 您在创建 Gateway Token 时设置的 Merchant Token 的 value ，来查询与之关联的 Gateway Token （3）需要和 paymentMethodType一起使用 |
paymentMethodType | 仅支持 card，需要和token一起使用 |
merchantTransID | 通过您在创建 Gateway Token 时设置的 merchantTransID ，你可以查询到与这个 merchantTransID 关联的 Gateway Token |
| 应答参数 | 描述 |
|---|---|
paymentMethod.card.encryptedCardInfo | 表明加密后的卡信息字段。 如果查询参数为有效的 Token 且 paymentMethodType 为 card，同时机构在 EVO Cloud 配置了‘API Resp RSA/SM2 加密密钥’，则此字段将返回。 （1）EVO Cloud 将卡号、有效期、持卡人姓名一起拼接成 json 字符串，然后对字符串进行整体加密得到该字段。 第一步：拼接后的 json 字符串：{"cardNumber":"1234123412341234","expiryDate":"2407","holderName":"test"} 第二步：使用 cardInfoEncryptedMethod 指定的加密方法对字符串进行加密 第三步：将密文放入本字段中 （2）您可使用公钥解密后得到明文 json 字符串：{"cardNumber":"1234123412341234","expiryDate":"2407","holderName":"test"} （3）需要和 paymentMethod.card.cardInfoEncryptMethod一起配合使用 |
paymentMethod.card.cardInfoEncryptMethod | 表明 paymentMethod.card.encryptedCardInfo 的加密算法。 （1）如果查询参数为有效的 Token 且 paymentMethodType 为 card，同时机构在 EVO Cloud 配置了‘API Resp RSA/SM2 加密密钥’，则此字段将返回对应配置的密钥方式。如果配置多个，则默认为 'RSA'。 （2）枚举值：RSA、SM2 （3）需要和 paymentMethod.card.cardInfoEncryptMethod一起配合使用 |
更新 Gateway Token
您可以使用
PUT PaymentMethod接口，来更新某一个由 PaymentMethod 接口创建的 Gateway Token 的信息，以下是支持更新的信息：expiryDate：卡有效期holderName：持卡人姓名tokenValidDays：Gateway Token 有效期
您可以使用
PUT PaymentInstrument接口，来更新某一个由 PaymentInstrument 接口创建的 Gateway Token 的信息，以下是支持更新的信息：expiryDate：卡有效期holderName：持卡人姓名tokenValidDays：Gateway Token 有效期payerReference：顾客标识
| 请求参数 | 描述 |
|---|---|
token | （1）你可以通过指定一个 Gateway Token 的 value 来更新这个 Gateway Token 的信息（2）或者通过指定一个 您在创建 Gateway Token 时设置的 Merchant Token 的 value ，来更新与之关联的 Gateway Token 的信息 |
删除 Gateway Token
- 您可以使用
DELETE PaymentMethod接口，通过指定 Gateway Token Value 来删除某一个由 PaymentMethod 接口创建的 Gateway Token，
| 请求参数 | 描述 |
|---|---|
token | 你可以通过指定一个 Gateway Token 的 value 来删除这个 Gateway Token |
- 您可以使用
DELETE PaymentInstrument接口，通过指定 Gateway Token value 或者 Merchant Token value 来删除某一个由 PaymentInstrument 接口创建的 Gateway Token，
| 请求参数 | 描述 |
|---|---|
token | （1）你可以通过指定一个 Gateway Token 的 value 来删除这个 Gateway Token（2）或者通过指定一个 您在创建 Gateway Token 时设置的 Merchant Token 的 value ，来删除与之关联的 Gateway Token |
