EVO Payment API Portal

简体中文

ENG

简体中文

ENG

绑卡 ​

绑卡 ​

Gateway Token ​

EVO Payment 支持您将消费者的卡信息存储在 EVO Payment 的系统中，然后由 EVO Payment 生成一个 Gateway Token，您可以在后续的交易中直接使用 Gateway Token 发起交易。

创建 Gateway Token ​

您有以下两种方式来创建 Gateway Token：

  1. 在授权的同时创建 Gateway Token
  2. 直接创建 Gateway Token

下面将分别为您介绍这两种方式的详细流程。

在授权的同时创建 Gateway Token ​

您可以在您现有的授权流程中进行绑卡，如果授权成功 EVO Payment 将会在应答中同步返回 Gateway Token，如果授权失败，则绑卡也同时失败。

TIP

如果您需要在授权的同时进行绑卡，EVO Payment 会要求同时对这笔交易进行 3DS 认证，关于 3DS 认证的详情请参考 3DS 章节。

主要流程如下：

  1. 您需要在 POST Payment 的请求中额外添加以下参数：

    • paymentMethod.card.tokenize：固定值 true，表示在授权的同时绑卡。
    • paymentMethod.card.payerReference：消费者标识，你可以自定义该字段的值。
    • authentication：包含 3DS 认证相关信息的结构体，详情参考 3DS 章节。

  2. 检查 EVO Payment 的应答，如果应答中存在 result.action 字段，则表示该笔交易需要继续进行 3DS 认证（请参考 3DS 章节）。

    如果应答中不存在 result.action 字段，则需要根据 payment.status 字段内容判断交易结果。如果字段的值为 Captured 、 Authorised 或 Capturing （取决于 captureAfterHours 字段的值）则表示交易成功，同时您可以从应答中的 paymentMethod.token.value 字段中找到 Gateway Token 的值，否则就需要查看 result.code 以及 result.message 来查看交易失败原因。

  3. 如果您没有收到来自 EVO Payment 的应答报文，则需要您调用 GET Payment 来查询交易结果。当收到查询应答时，您同样也需要通过 payment.status 字段内容来判断交易结果，判断方式与第 2 步一致。如果交易失败，您需要通过 payment.failureCode 以及 payment.failureReason 来查看交易失败原因。

  4. 如果您在 POST Payment 请求中上送了 webhook 并且交易的 payment.status 为 Captured 、 Authorised 或 Capturing，您也可以通过异步通知来获取交易结果，异步通知中的 eventCode 为 Payment。同样也需要通过 payment.status 字段内容来判断交易结果，判断方式与第 2 步一致。

  5. 向消费者展示付款及绑卡结果。

直接创建 Gateway Token ​

如果您的消费者当前仅需要绑卡，你可以使用 POST PaymentMethod 或者 POST PaymentInstrument接口直接创建 Gateway Token。

TIP

  1. 使用 POST PaymentMethod 直接创建 Gateway Token 时，EVO Payment 会要求先进行 3DS 认证，关于 3DS 认证的详情请参考 3DS 章节。
  2. 使用 POST PaymentInstrument 直接创建 Gateway Token 时，EVO Payment 不会要求进行任何认证，由商户通过其他途径做完认证，仅在 EVO Payment 完成绑卡。

PaymentMethod 主要流程如下：

  1. 在调用 PaymentMethod 接口时需要包含但不限于以下参数，字段详情参考 API 文档：

    • paymentMethod.type：表明支付方式的字段，如果是卡交易则使用 card。
    • paymentMethod.card：包含消费者卡信息的结构体。当 paymentMethod.type 为 card 时必填。
    • merchantTransInfo：包含商户订单号等信息的结构体。
    • pspInfo：包含卡组织资质信息的结构体。
    • transInitiator：包含消费者设别信息的结构体。
    • authentication：包含 3DS 认证相关信息的结构体，详情参考 3DS 章节。

  2. 检查 EVO Payment 的应答，如果应答中存在 result.action 字段，则表示该笔交易需要继续进行 3DS 认证（请参考 3DS 章节）。

    如果应答中不存在 result.action 字段，则需要根据 paymentMethod.status 字段内容判断交易结果。如果字段的值为 Success 则表示 Token 创建成功，同时您可以从应答中的 paymentMethod.token.value 字段中找到 Gateway Token 的值，否则就需要查看 result.code 以及 result.message 来查看交易失败原因。

  3. 如果您没有收到来自 EVO Payment 的应答报文，则需要您调用 GET PaymentMethod 来查询交易结果。当收到查询应答时，您同样也需要通过 paymentMethod.status 字段内容来判断交易结果，判断方式与第 2 步一致。如果交易失败，您需要通过 paymentMethod.failureCode 以及 paymentMethod.failureReason 来查看交易失败原因。

  4. 如果您在 POST PaymentMethod 请求中上送了 webhook 并且交易的 paymentMethod.status 为 Success，您也可以通过异步通知来获取交易结果，异步通知中的 eventCode 为 PaymentMethod。同样也需要通过 payment.status 字段内容来判断交易结果，判断方式与第 2 步一致。

  5. 向消费者展示绑卡结果。

PaymentInstrument 主要流程如下：

  1. 在调用 PaymentInstrument 接口时需要包含但不限于以下参数，字段详情参考 API 文档：

    • merchantTransInfo：包含商户订单号等信息的结构体，作为 EVO Payment 的 Gateway Token 的溯源信息。
    • paymentMethod.type：表明支付方式的字段，如果是卡交易则使用 card。
    • paymentMethod.card：包含消费者卡信息的结构体。当 paymentMethod.type 为 card 时必填。
    • paymentMethod.card.cardInfo.paymentBrand：表明卡品牌的字段，可选。（1）当不指定 PaymentBrand 时，可以不上送该字段，EVO Payment 会通过卡号进行卡品牌判断，如果在 American_Express、Diners、JCB、Mastercard、UnionPay、Visa、MyDebit、TPN、NAPAS 卡品牌内，应答会返回对应的卡品牌，如果不在，则 EVO Payment 不会返回卡品牌。（2）当指定 PaymentBrand 时，必须在 American_Express、Diners、JCB、Mastercard、UnionPay、Visa、MyDebit、TPN、NAPAS 这些品牌中选择上送，否则不生效。
    • paymentMethod.merchantToken：包含商户自带的 Token 信息的结构体。当商户通过其他途径做完认证，拿到第三方的 Token 后，可选填，从而跟 EVO Payment 的 Gateway Token 完成绑定。

  2. 检查 EVO Payment 的应答，根据 result.message 字段内容判断交易结果。如果字段的值为 Success 则表示 Token 创建成功，那么您可以从应答的 paymentMethod.token.value 字段中找到 Gateway Token 的值。否则就需要查看 result.code 以及 result.message 后在应答码章节找到交易的失败原因。

  3. 如果您没有收到来自 EVO Payment 的应答报文，则需要您调用 GET PaymentInstrument 来查询交易结果。当收到查询应答时，您同样也需要通过 result.message 字段内容来判断交易结果，判断方式与第 2 步一致。如果交易失败，您需要通过查看 result.code 以及 result.message 后在应答码章节找到交易的失败原因。

  4. 如果您在 POST PaymentInstrument 请求中上送了 webhook 并且交易的 result.message 为 Success，您也可以通过异步通知来获取交易结果，异步通知中的 eventCode 为 PaymentInstrument。同样也需要通过 result.message 字段内容来判断交易结果，判断方式与第 2 步一致。

  5. 向消费者展示绑卡结果。

使用 Gateway Token 进行支付 ​

当您成功获取到了 Gateway Token 以后，就可以在您的授权请求中使用 Gateway Token 来替代卡信息来发起交易，交易流程与普通的授权交易一致，只需要您将 POST Payment 请求中的部分字段进行替换即可。

卡交易Token 交易
paymentMethod.typecardtoken
paymentMethod.card存在不存在
paymentMethod.token不存在存在

TIP

  1. 使用 POST PaymentMethod 直接创建的 Gateway Token 发起的交易同样支持 3DS 认证，流程与普通卡交易一致，详情参考 3DS 章节。
  2. 使用 POST PaymentInstrument 创建的 Gateway Token，通过 EVO Payment 完成支付，可以是 EVO Payment Token，也可以是 Merchant Token，同样支持 3DS 认证，流程与普通卡交易一致，详情参考 3DS 章节。
  3. 使用 POST PaymentInstrument 创建 Gateway Token，可以使用其他收单服务商完成支付，这时需要通过 GET PaymentInstrument 获取卡信息，之后到指定收单服务商完成支付。

管理 Gateway Token ​

消费者可能会需要更新（卡有效期更新）、删除（卡片停用）他们已经绑定过的卡片。 EVO Payment 提供了查询、更新以及删除 Gateway Token 的能力。

查询 Gateway Token ​
  1. 您可以使用 GET PaymentMethod 接口，通过指定不同参数的方式来查询由 PaymentMethod 接口创建的某一个 Gateway Token 或者某个消费者的所有 Gateway Token 的信息。
请求参数描述
userReference通过您在创建 Gateway Token 时设置的 userReference，你可以查询到与这个 userReference 关联的全部的 Gateway Token
token你可以通过指定一个 Gateway Token 的 value 来查询这个 Gateway Token 的全部信息
  1. 您可以使用 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 Payment 配置了‘API Resp RSA/SM2 加密密钥’，则此字段将返回。
（1）EVO Payment 将卡号、有效期、持卡人姓名一起拼接成 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 Payment 配置了‘API Resp RSA/SM2 加密密钥’，则此字段将返回对应配置的密钥方式。如果配置多个，则默认为 'RSA'。
（2）枚举值：RSA、SM2
（3）需要和paymentMethod.card.cardInfoEncryptMethod一起配合使用
更新 Gateway Token ​

  1. 您可以使用 PUT PaymentMethod 接口，来更新某一个由 PaymentMethod 接口创建的 Gateway Token 的信息，以下是支持更新的信息：

    • expiryDate：卡有效期
    • holderName：持卡人姓名
    • tokenValidDays：Gateway Token 有效期

  2. 您可以使用 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 ​
  1. 您可以使用 DELETE PaymentMethod 接口，通过指定 Gateway Token Value 来删除某一个由 PaymentMethod 接口创建的 Gateway Token，
请求参数描述
token你可以通过指定一个 Gateway Token 的 value 来删除这个 Gateway Token
  1. 您可以使用 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