Create a gateway token

保存用户支付方式并获取 EVO Cloud 生成的网关令牌，有两种方式：

支付时创建网关令牌

先创建网关令牌，之后再支付

卡支付可以根据业务需要任选一种。WeChat Pay 和 Alipay 按 PSP 的规定，必须先创建网关令牌再支付。

支付时创建网关令牌

卡支付场景下，在用户支付时额外传入参数即可创建网关令牌。EVO Cloud 会采集用户的支付信息并生成网关令牌，处理流程与“支付”章节相同。

从服务端向 EVO Cloud 发起 HTTP POST 请求：

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

并额外传入以下参数（M = 必填，O = 可选）：

Body 参数	是否必填	说明
`paymentMethod.type`	M	仅支持 card。
`paymentMethod.card`	M	将 `paymentMethod.card.tokenize` 设为 true，请求 EVO Cloud 对本次支付进行令牌化，并在 `paymentMethod.card` 对象中传入相关卡信息和令牌化属性。
`paymentMethod.recurringProcessingModel`	O	表示交易是否为周期扣款。如果是保存凭证的周期扣款交易，可设为 Subscription。
`authentication`	O	令牌化前用于用户认证的信息。
`userInfo`	M	买家详细信息。需传入与令牌关联的用户标识。
`returnURL`	M	用户完成或取消支付后重定向回的 URL。

paymentMethod.card 对象中附加参数的详细说明：

paymentMethod.card.tokenize：布尔值，必填。需要为用户的卡信息生成令牌时设为 true。

paymentMethod.card.vaultID：令牌所属的分组 ID，必填。接入前请向客户经理获取 EVO Cloud 分配的该 ID。

paymentMethod.card.tokenValidDays：令牌有效期（天），可选。填 0 或不传表示生成的令牌永久有效；填 1 到 365 表示令牌的有效天数。

userInfo 对象中附加参数的详细说明：

userInfo.reference：用户唯一标识，必填，作为令牌的关联标识。

authentication 对象的详细说明见“认证”章节。

以下示例为一笔 10 USD 信用卡支付，同时申请网关令牌：

通常在完成令牌化和支付之前，还需要额外操作完成用户认证，详见“认证”章节。

用户认证和支付完成后，网关令牌会通过应答参数 paymentMethod.token 对象返回给你的服务端。

以下为包含网关令牌的支付成功应答示例：

提示

请在服务端保存收到的令牌信息，供后续使用。

先创建网关令牌，之后再支付

卡支付和电子钱包支付（WeChat Pay、Alipay）都可以先通过 PaymentMethod API 创建网关令牌，之后再支付。这样可以先引导用户把支付方式添加到账户，之后再支付。

WeChat Pay 特别说明：按 PSP 的规定，只能在微信小程序内创建网关令牌。除 API 接入外，EVO Cloud 还提供 SDK 方案来简化小程序接入。接入前请参阅《EVO Cloud SDK 接入指南》，并联系 EVO Cloud 客户经理做好准备。

上图描述了你需要实现的服务端集成和客户端实现。

步骤 1：获取可用支付方式

用户准备支付或进入支付页面时，获取可用支付方式列表，以及每种支付方式需要用户填写的信息。

详见“支付”章节的步骤 1。

步骤 2：采集用户支付信息

按每种支付方式要求的字段采集用户支付信息，然后发送到你的服务端。

详见“支付”章节的步骤 2。

步骤 3：提交令牌化请求

用户选择支付方式并提交所需支付信息后，向 EVO Cloud 发起支付请求。

从服务端向 EVO Cloud 发起 HTTP POST 请求：

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

并传入以下参数：

Body 参数	是否必填	说明
`merchantTransInfo`	M	本次请求的商户参考信息，包括唯一的 `merchantTransID`，以及表示请求发起时间的 `merchantTransTime`。
`paymentMethod`	M	用 `paymentMethod.type` 指定用户要令牌化的是 `e-wallet` 还是 `card`，并传入上一步采集的对应支付信息。
`transInitiator`	O	发起交易的设备信息。
`authentication`	O	令牌化前用于用户认证的信息，卡支付时必填。
`userInfo`	M	买家详细信息。需传入与令牌关联的用户标识。
`storeInfo`	M	门店补充信息。门店在 EVO Cloud 配置了多个 MCC 时，需要用此字段指明本次支付使用哪个 MCC。
`returnURL`	O	用户完成或取消支付后重定向回的 URL。
`webhook`	O	接收通知的 URL。传入后，令牌化成功时 EVO Cloud 会向该地址发送通知。
`metadata`	O	商户自定义的参考信息，请求中传入后会在应答中原样回显。除 GET 请求外，应答中的 metadata 与本次请求中的 metadata 一致；GET 应答和通知中的 metadata 与 POST 请求中的 metadata 一致。

paymentMethod 和 userInfo 对象详细说明：

A. 用户选择用电子钱包令牌化：

paymentMethod.type：请求中设为 e-wallet。

paymentMethod.e-wallet.paymentBrand：用户选择令牌化的钱包品牌，必填。支持 WeChat_Pay 和 Alipay。

userInfo.reference：用户唯一标识，必填，作为令牌的关联标识。

paymentMethod.e-wallet.vaultID：令牌所属的分组 ID，必填。接入前请向客户经理获取 EVO Cloud 分配的该 ID。

paymentMethod.e-wallet.planID：微信自动扣款协议模板 ID。用户在你的微信小程序中（transInitiator.platform 为 MINI）使用 WeChat Pay 令牌化（paymentMethod.e-wallet.paymentBrand 为 WeChat_Pay）时必填。向微信申请自动扣款服务时获取。

paymentMethod.e-wallet.subOpenID：用户在你的微信小程序中的用户 ID。用户在你的微信小程序中（transInitiator.platform=MINI）使用 WeChat Pay 令牌化（paymentMethod.e-wallet.paymentBrand=WeChat_Pay）时必填。在用户登录你的……时获取

B. 用户选择用卡令牌化：

paymentMethod.type：请求中设为 card。

paymentMethod.card.encryptedCardInfo：加密后的卡信息。如果使用 EVO Cloud 客户端方案安全加密用户卡信息，前端会从 EVO Cloud SDK 拿到该值。你需要把它发送到服务端，再由服务端原样转发给 EVO Cloud。

paymentMethod.card.cardInfo：卡信息明文。如果你自行采集卡明文并发送给 EVO Cloud，需要在该对象中传入 cardNumber、expiryDate、cvc（可选）和 holderName。注意：部分银联借记卡的 expiryDate 也是可选的。

（如果同时传入 paymentMethod.card.encryptedCardInfo 和 paymentMethod.card.cardInfo，以 paymentMethod.card.cardInfo 为准。）

userInfo.reference：用户唯一标识，必填，作为令牌的关联标识。

paymentMethod.card.vaultID：令牌所属的分组 ID，必填。接入前请向客户经理获取 EVO Cloud 分配的该 ID。

paymentMethod.card.tokenValidDays：令牌有效期（天），可选。填 0 或不传表示生成的令牌永久有效；填 1 到 365 表示令牌的有效天数。

authentication 对象的详细说明见“认证”章节。

以下为 Alipay 令牌化示例：

应答中通常会包含 action 对象，提示你还需要哪些额外步骤才能完成令牌化。你需要把 action 对象发给 Web 前端或客户端 App，然后进入下一步。

以下为需要重定向用户以完成令牌化的应答示例：

以下为 WeChat Pay 令牌化示例：

以下为需要唤起微信 App 以完成令牌化的应答示例：

步骤 4：执行附加操作

如果服务端在 /g2/v1/payment/mer/{sid}/paymentMethod 的应答中收到 action 对象，下一步操作取决于 action.type。

action 类型	说明	下一步
`threeDSRedirect`	适用于 3DS 1 或 3DS 2 认证场景：`paymentMethod.type` 为 card，`authentication.type` 为 threeDSPage 或 threeDSIntegrator。	使用同一应答中的 `action.threeDSData`，将用户重定向到另一个网站完成 3DS 1 或 3DS 2 认证。详见“认证”章节。
`threeDSIdentify`	适用于 3DS 2 认证场景：`paymentMethod.type` 为 card，`authentication.type` 为 threeDSIntegrator。	使用同一应答中的 `action.threeDSData`，将用户重定向到另一个网站完成 3DS 2 无感认证。详见“认证”章节。
`threeDSChallenge`	适用于 3DS 2 认证场景：`paymentMethod.type` 为 card，`authentication.type` 为 threeDSIntegrator。	使用同一应答中的 `action.threeDSData`，将用户重定向到另一个网站完成 3DS 2 挑战认证。详见“认证”章节。
`inputMobilePhone`	适用于 SecurePlus 认证：`paymentMethod.type` 为 card，`authentication.type` 为 SecurePlus。	在支付页面展示输入框，请用户输入手机号，并提交给 EVO Cloud。详见“认证”章节。
`inputSMSCode`	适用于 SecurePlus 认证：`paymentMethod.type` 为 card，`authentication.type` 为 SecurePlus。	在支付页面展示输入框，请用户输入手机收到的短信验证码，并提交给 EVO Cloud。详见“认证”章节。
`redirectUser`	适用于在 PC Web、移动 WAP 和客户端 App 上使用 Alipay 令牌化。	按 `action.redirectData.method` 指定的 HTTP 方法，将用户重定向到 `action.redirectData.url`。如果 `action.redirectData.method` 为 POST 且存在 `action.redirectData.parameter`，将 parameter 对象中的子字段作为 POST 请求的表单数据传入。用户会进入一个页面，与钱包运营方签署电子协议以完成令牌化。签约完成后，用户会通过 HTTP GET 被重定向回你的 returnURL。在拿到令牌化结果前，你可以选择向用户展示加载页。你可以从服务端向 EVO Cloud 的 /g2/v1/payment/mer/{sid}/paymentMethod 发起 HTTP GET 请求获取令牌化结果（详见步骤 6），也可以等待 webhook 通知获知结果（详见“支付后处理”章节）。
`invokeWallet`	适用于在微信小程序中使用 WeChat Pay 令牌化。	按 `action.redirectData.method` 指定的 HTTP 方法，将用户重定向到 `action.redirectData.url`。如果 `action.redirectData.method` 为 POST 且存在 `action.redirectData.parameter`，将 parameter 对象中的子字段作为 POST 请求的表单数据传入。用户会进入一个页面，与钱包运营方签署电子协议以完成令牌化。签约完成后，用户会通过 HTTP GET 被重定向回你的 returnURL。在拿到令牌化结果前，你可以选择向用户展示加载页。你可以从服务端向 EVO Cloud 的 /g2/v1/payment/mer/{sid}/paymentMethod 发起 HTTP GET 请求获取令牌化结果（详见步骤 6），也可以等待 webhook 通知获知结果（详见“支付后处理”章节）。

步骤 5：提交令牌化附加信息

支付方式为卡时，如果用户进入了认证流程，需要向 EVO Cloud 提交认证附加信息以完成令牌化。详见“认证”章节。

WeChat Pay 场景下，用户会被切换到微信 App 与微信签署电子协议，你需要把签约结果提交给 EVO Cloud 以完成令牌化。

从服务端向 EVO Cloud 发起 HTTP PUT 请求：

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

并传入以下参数：

Query 参数	是否必填	说明
`merchantTransID`	M	首次令牌化请求中的 merchantTransInfo.merchantTransID。

Body 参数	是否必填	说明
`paymentMethod.e-wallet.contractID`	M	WeChat Pay 令牌化时，填写微信返回的 `contract_id`。需要提交给 EVO Cloud 才能完成令牌化处理。

以下为 WeChat Pay 令牌化的 HTTP PUT 请求示例：

令牌化成功的应答中包含描述令牌信息的 paymentMethod.token 对象，字段如下：

paymentMethod.token.value：EVO Cloud 生成的令牌值。

paymentMethod.token.userReference：用户唯一标识，与 POST 请求中的 userInfo.reference 一致。

paymentMethod.token.vaultID：令牌所属的分组 ID，与 POST 请求中的 paymentMethod.e-wallet.vaultID 或 paymentMethod.card.vaultID 一致。

paymentMethod.token.expiryDate：令牌到期日期和时间，例如 2017-07-17T13:42:40+01:00。

卡支付：按 POST 请求中的 paymentMethod.card.tokenValidDays 生成。POST 请求未传 tokenValidDays 或传 0 时，应答中不会返回 expiryDate，表示令牌永久有效。

电子钱包支付：由用户与钱包运营方签署电子协议时决定。

paymentMethod.token.fingerprint：令牌指纹，适用于卡支付。它是与卡号一一对应的唯一值，可用来判断某张卡是否已在 EVO Cloud 令牌化。

paymentMethod.token.status：令牌状态。有效令牌的值为 enabled。

paymentMethod.token.createTime：令牌创建的日期和时间，例如 2017-07-17T13:42:40+01:00。

paymentMethod.token.updateTime：令牌更新的日期和时间，例如 2017-07-17T13:42:40+01:00。

如果这是一笔需要保存凭证的周期扣款交易，且交易成功，应答中会返回 paymentMethod.recurringReference，后续周期扣款交易要用到它。

A. 电子钱包支付时，令牌化成功的应答中还包含描述令牌关联钱包信息的 paymentMethod.e-wallet 对象，字段如下：

paymentMethod.e-wallet.paymentBrand：用户选择令牌化的钱包品牌，与 POST 请求中的 paymentMethod.e-wallet.paymentBrand 一致。

paymentMethod.e-wallet.planID：微信自动扣款协议模板 ID，适用于用户在你的微信小程序中使用 WeChat Pay 令牌化，与 POST 请求中的 paymentMethod.e-wallet.planID 一致。

paymentMethod.e-wallet.subOpenID：用户在你的微信小程序中的用户 ID，适用于用户在你的微信小程序中使用 WeChat Pay 令牌化，与 POST 请求中的 paymentMethod.e-wallet.planID 一致。

paymentMethod.e-wallet.contractID：微信返回的 contract_id，适用于用户在你的微信小程序中使用 WeChat Pay 令牌化，与 PUT 请求中的 paymentMethod.e-wallet.contractID 一致。

B. 卡支付时，令牌化成功的应答中还包含描述令牌关联卡信息的 paymentMethod.card 对象，可能包含以下字段：

paymentMethod.card.paymentBrand：用户令牌化所用卡的品牌，与 POST 请求中的 paymentMethod.card.paymentBrand 一致。

paymentMethod.card.first6No：卡号前 6 位。

paymentMethod.card.last4No：卡号后 4 位。

paymentMethod.card.holderName：持卡人姓名。

paymentMethod.card.fundingType：卡类型，credit（信用卡）、debit（借记卡）或 prepaid（预付卡）。

paymentMethod.card.issuingBank：发卡行名称。

paymentMethod.card.issuingCountry：发卡国家。

paymentMethod.card.issuerCountry：持卡人所在国家。

paymentMethod.card.isCommercial：是否为商务卡。

以下为 WeChat Pay 令牌化成功的应答示例：

步骤 6：查询令牌化结果

电子钱包支付场景下，如果你把用户重定向到了其他网站或 App，且没有使用通知 webhook，可以向 EVO Cloud 查询令牌化结果。

从服务端向 EVO Cloud 发起 HTTP GET 请求：

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

并传入以下参数：

Query 参数	是否必填	说明
`merchantTransID`	M	首次令牌化请求中的 `merchantTransInfo.merchantTransID`。

以下示例展示如何查询令牌化结果：

如果令牌化已成功完成，GET 应答与 PUT 应答相同，详见步骤 5。

步骤 7：展示令牌化结果

用户完成令牌化，且前端或客户端 App 无需进一步操作后，使用 result.code 和 paymentMethod.status 告知用户令牌化状态。

Result code	Description
S0000	Success
C0004	Request resource merchantTransID {XXX} not exist
C0006	Request resource vault ID {XXX} not exist
C0007	Request resource userReference {XXX} not exist
C0008	Request resource paymentMethod token {XXX} not exist
B0005	Unsupported function {XXX}, please check your profile setup in EVO Cloud
B0006	Unsupported payment brand {XXX}, please check your profile setup in EVO Cloud
B0009	Unsupported card BIN {XXX}, please check your profile setup in EVO Cloud
B0012	Invalid transaction status {XXX} to complete the request
B0015	Cannot complete the request because token in the request is expired
B0019	Authentication required, please ask user to input authentication info, please ask user to input authentication info
B0020	Token update failed, please check your request message
B0021	{Payment / Tokenization} failed due to user authentication results with high risk, please ask user to try again

其他可能的 result.code 值及建议向用户展示的提示信息，见 EVO Cloud API 规范附录。

如果 result.code 为 S0000，还需要检查 paymentMethod.status，判断令牌化状态并告知用户。

状态	说明
Success	令牌已创建
Failed	令牌创建失败

其他可能的 paymentMethod.status 值及说明，见 EVO Cloud API 规范中的 paymentMethod.status。

创建网关令牌时同步创建网络令牌

无论是支付时创建网关令牌，还是单独创建网关令牌，都可以同时创建网络令牌。你需要先在 EVO Cloud 门户为商户配置“网络令牌服务（Network token Service）”，然后按 4.2.1 或 4.2.2 章节的说明发起创建网关令牌请求。

如果卡品牌在下表中，且发卡行支持网络令牌，EVO Cloud 会在 Payment 或 PaymentMethod 的应答报文中返回 networkToken 对象。

卡品牌	是否支持网络令牌
Visa	是
Mastercard	是

网络令牌创建成功的应答中，还会额外包含描述网络令牌信息的 paymentMethod.networkToken 对象，字段如下：

paymentMethod.networkToken.tokenID：卡组织分配的网络令牌唯一 ID。

paymentMethod.networkToken.status：网络令牌状态。有效网络令牌的值为 enabled。

paymentMethod.networkToken.supportDeviceBinding：网络令牌是否支持设备绑定（该功能暂未开放）。

完成上述步骤后，你会得到一个关联了网络令牌的网关令牌。这个网关令牌的支付用法与普通网关令牌相同（见 4.3 章节），EVO Cloud 会自动决定使用网络令牌还是卡号（PAN）发起授权。

该场景同样适用 3D Secure 2。

创建网络令牌时的 FIDO 认证

创建网关令牌并关联网络令牌时，除了 3D Secure 2，还可以使用 FIDO 认证。

如果卡品牌在下表中，且发卡行支持网络令牌，EVO Cloud 支持使用 FIDO 认证用户。

卡品牌	是否支持网络令牌	是否支持 FIDO 认证
Visa	是	否
Mastercard	是	是

FIDO 认证详见 FIDO Authentication 章节。

异常处理

向 EVO Cloud 发起的 HTTP POST 请求：建议请求发出后至少等待 45 秒。如果在该时间内没有收到应答，需要按步骤 6 向 EVO Cloud 查询结果。

向 EVO Cloud 发起的 HTTP PUT 请求：HTTP PUT 请求是幂等的。如果在一定时间内（例如 45 秒）没有收到 EVO Cloud 的应答，可以用完全相同的请求报文重新发送。多次重发仍未收到应答时，可以改为发起一笔新的令牌化请求。

向 EVO Cloud 发起的 HTTP GET 请求：HTTP GET 请求是幂等的。可以多次发起请求直到拿到结果，建议每次请求之间至少间隔 45 秒。多次请求仍未拿到结果时，可以改为发起一笔新的令牌化请求。

支付时创建网关令牌#

先创建网关令牌，之后再支付#

步骤 1：获取可用支付方式#

步骤 2：采集用户支付信息#

步骤 3：提交令牌化请求#

步骤 4：执行附加操作#

步骤 5：提交令牌化附加信息#

步骤 6：查询令牌化结果#

步骤 7：展示令牌化结果#

创建网关令牌时同步创建网络令牌#

创建网络令牌时的 FIDO 认证#

异常处理#

支付时创建网关令牌

先创建网关令牌，之后再支付

步骤 1：获取可用支付方式

步骤 2：采集用户支付信息

步骤 3：提交令牌化请求

步骤 4：执行附加操作

步骤 5：提交令牌化附加信息

步骤 6：查询令牌化结果

步骤 7：展示令牌化结果

创建网关令牌时同步创建网络令牌

创建网络令牌时的 FIDO 认证

异常处理