Merchant Connect 支付 - 卡片端到端处理流程

Step 1: 获取可用支付方式

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

虽然我们强烈建议使用下方的接口来确保为客户提供最新可用的支付方式列表，但这一步是可选的。你也可以缓存接口响应，每周更新一次即可。

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

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

支持以下任一查询参数（每次请求只能使用一个）：

查询参数	必填	说明
`paymentBrand`	O	想要提供给用户的指定支付品牌。传入后将返回该品牌下可用的支付方式和所需信息。
`cardBIN`	O	用户打算使用的卡 BIN。传入后将返回该 BIN 对应的支付方式和所需信息。
`currency`	O	用户打算使用的币种。传入后将返回该币种对应的支付方式和所需信息。
`tokenize`	O	布尔值。表示是否查询支持 tokenization 的支付方式。`true` 时仅返回支持 tokenization 的支付方式。

若同时传入多个参数，系统会按 cardBIN → paymentBrand → currency 的优先级处理。
若不传任何参数，将返回与你的 EVO Cloud 集成相关联的所有支付方式和必填信息。

请求示例（不带查询参数）：

响应中包含 paymentBrandList 数组，每个支付方式包含以下字段：

brandName：支付方式的品牌名。

brandImage：品牌 Logo 图片的 URL，可用于在支付页展示。

paymentInfo：卡组织或电子钱包发起支付所需的信息。

authenticationInfo：卡组织发起用户认证所需的信息。

promotionInfo：该支付方式支持的促销名称列表。

完整字段定义请参见 EVO Cloud API Specification。

响应示例：

{
  "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": "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 Cloud 前需遵循 ISO 规范：

paymentBrandList 中的字段名	EVO Cloud API 字段名	ISO 规范
Country（收货地址）	`userInfo.deliveryAddress.country`	ISO-3166-1 alpha-3，如 SGP。
State or Province（收货地址）	`userInfo.deliveryAddress.stateOrProvince`	ISO-3166-2，如 North East。
Country（账单地址）	`userInfo.billingAddress.country`	ISO-3166-1 alpha-3，如 SGP。
State or Province（账单地址）	`userInfo.billingAddress.stateOrProvince`	ISO-3166-2，如 North East。

Step 2: 收集用户的支付信息

根据每种支付方式必填的字段，从用户处收集支付信息，然后发送到你的主机。

注意： 若用户选择用卡支付，商户必须满足 PCI DSS 合规要求。你有两种方式收集卡信息：
1.
使用 EVO Cloud 客户端 SDK 加密用户卡信息：只需提交 PCI DSS SAQ A 自评问卷。详见 EVO Cloud SDK Integration Guide。
2.
收集并发送原始卡数据：需要按 SAQ D（最严格的自评形式）评估 PCI DSS 合规。

Step 3: 发起支付

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

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

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

通用 Payment 字段

字段路径	必填	说明
`merchantTransInfo`	M	商户交易标识对象。
`storeInfo`	O	补充门店信息。
`transAmount`	M	支付的币种和金额，金额必须遵循该币种的最小单位。
`captureAfterHours`	O	控制立即 / 定时 / 手动 Capture 行为。
`paymentMethod`	M	支付方式对象。
`paymentMethod.type`	M	本文档场景下必须为 `card`。
`transInitiator`	M	终端发起上下文。
`transInitiator.platform`	M	POS 路由下必须为 `POS`。
`transInitiator.paymentScenario`	O	部署路由要求时填 `inStore`。
`transInitiator.terminalID`	O	已注册的终端标识符。

paymentMethod 对象补充说明

A. 用户选择离线卡支付时：

paymentMethod.type：在请求中设为 card。

paymentMethod.card.encryptedCardInfo：加密的卡信息。若使用 EVO Cloud 客户端 SDK 加密，前端从 SDK 拿到值后发送到主机，主机需原样转发给 EVO Cloud。

paymentMethod.card.cardInfo：原始卡数据。若收集原始卡数据发给 EVO Cloud，需在该对象中指定 cardNumber、expiryDate、可选的 cvc、track2 和 holderName。部分银联借记卡的 expiryDate 也可选。

若 encryptedCardInfo 和 cardInfo 同时存在，以 cardInfo 为准。

paymentMethod.card 字段

字段路径	必填	适用条件	说明
`paymentMethod.card`	M	`paymentMethod.type=card`	卡相关交易对象。
`paymentMethod.card.encryptedCardInfo`	O	经批准的加密卡集成	加密的卡信息。
`paymentMethod.card.cardInfo`	O	经批准的卡信息集成	卡信息容器。
`paymentMethod.card.cardInfo.cardNumber`	M	手工 / MOTO 或最终 schema 要求	卡号。示例和测试数据中严禁使用真实卡号。
`paymentMethod.card.cardInfo.expiryDate`	O	MOTO 要求	过期日期，格式 `MMYY`。
`paymentMethod.card.posEntryMode`	O	POS 卡路由	卡数据输入方式。
`paymentMethod.card.pinFlag`	O	终端支持 PIN	`true` 表示终端支持输入 PIN；`false` 表示不支持。
`paymentMethod.card.termReadability`	O	提供终端能力	终端卡数据输入能力。
`paymentMethod.card.icCardCondCode`	O	银联 IC 场景	银联卡条件码。
`paymentMethod.card.noSecretNoSignFlag`	O	银联场景	银联免密 / 免签标识。
`paymentMethod.card.cardInfo.track1`	O	磁条或通道特殊要求	Track 1 数据。最终字段名以批准后的 schema 为准。
`paymentMethod.card.cardInfo.track2`	O	磁条 / ICC / 非接 / fallback 要求	Track 2 数据。严禁以明文形式存储或记录日志。
`paymentMethod.card.cardInfo.cardSequenceNum`	O	ICC 或非接要求	IC 卡序列号。
`paymentMethod.card.cardInfo.icCardData`	O	ICC 或非接要求	EMV / ICC TLV 数据。
`paymentMethod.card.pin`	O	PIN 交易	PIN 容器（如最终 schema 包含）。
`paymentMethod.card.pin.encryptedPin`	M	PIN 交易	加密的 PIN 块。严禁以明文记录或持久化。
`paymentMethod.card.pin.pinEncryptMethod`	M	PIN 交易	经批准的 PIN 加密方法，如 `3DES`。
`paymentMethod.card.pin.checkValue`	O	启用密钥版本查找	用于定位适用工作密钥版本的值。

卡的 posEntryMode 取值

posEntryMode	交易活动	通常需提供的条件数据
`magnetic`	读取磁条	track2
`ICC`	接触式芯片插入	track2、icCardData、cardSequenceNum
`contactless`	NFC EMV 非接	track2、icCardData、cardSequenceNum（使用经批准的非接数据集）
`contactless magnetic`	非接交易走磁条路径	track2
`fallback`	EMV 降级到磁条	track2
`manual`	手工输入卡	cardNumber、expiryDate
`MOTO`	邮购 / 电话订购	cardNumber、expiryDate

字段名、长度、条件必填、PSP 特殊限制以最终 API schema 为准。

Purchase（消费）请求示例

以下示例中所有与环境相关和敏感值均使用占位符。

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "posEntryMode": "ICC",
      "pinFlag": true,
      "cardInfo": {
        "cardNumber": "6222021234567890123",
        "track2": "6222021234567890123=26122011234567890123",
        "icCardData": "9F02069F03069F1A029F26089F27019F36029F37049F1008",
        "cardSequenceNum": "001"
      },
      "pin": {
        "encryptedPin": "base64encodedPinBlock==",
        "pinEncryptMethod": "3DES",
        "checkValue": "A1B2C3"
      }
    }
  },
  "transInitiator": {
    "platform": "POS",
    "terminalID": "30100101",
    "paymentScenario": "inStore"
  },
  "transAmount": {
    "value": "100.00",
    "currency": "CNY"
  },
  "merchantTransInfo": {
    "merchantTransID": "POS2026080415480003",
    "merchantTransTime": "2026-08-04T15:48:00+08:00"
  },
  "captureAfterHours": "0"
}

Pre-authorization（预授权）请求示例

与消费请求相同，但 captureAfterHours 设为 "1"（或具体延时小时数）。

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "posEntryMode": "ICC",
      "pinFlag": true,
      "cardInfo": {
        "cardNumber": "6222021234567890123",
        "track2": "6222021234567890123=26122011234567890123",
        "icCardData": "9F02069F03069F1A029F26089F27019F36029F37049F1008",
        "cardSequenceNum": "001"
      },
      "pin": {
        "encryptedPin": "base64encodedPinBlock==",
        "pinEncryptMethod": "3DES",
        "checkValue": "A1B2C3"
      }
    }
  },
  "transInitiator": {
    "platform": "POS",
    "terminalID": "30100101",
    "paymentScenario": "inStore"
  },
  "transAmount": {
    "value": "100.00",
    "currency": "CNY"
  },
  "merchantTransInfo": {
    "merchantTransID": "POS2026080415480003",
    "merchantTransTime": "2026-08-04T15:48:00+08:00"
  },
  "captureAfterHours": "1"
}

响应与状态处理

消费响应示例

{
  "result": {
    "code": "S0000",
    "message": "Success"
  },
  "merchantTransInfo": {
    "merchantTransID": "{{merchantTransId}}"
  },
  "payment": {
    "status": "Captured",
    "transID": "{{platformTransactionId}}",
    "transAmount": {
      "currency": "{{currency}}",
      "value": "{{amount}}"
    }
  },
  "paymentMethod": {
    "type": "card"
  },
  "transInitiator": {
    "platform": "POS",
    "terminalID": "{{terminalId}}"
  }
}

Payment 状态模型

Status	含义	商户处理
`Pending`	请求已受理但处理未完成	按集成合约查询交易或等待 Notification。
`Authorised`	授权成功但 Capture 未完成	发送 Capture 或等待自动 Capture。
`Captured`	授权 + Capture 完成	履单并保存最终交易标识。
`Failed`	校验、业务、风控或 PSP 处理失败	不可履单，查看 result code 和 message。
`Reversed`	超时或恢复处理后授权被冲正	不可视为已 Captured，需对账。

Notification 通知

配置 Payment Notification 后，商户通过它接收以下异步状态变更：

消费完成：Captured

预授权完成：Authorised

Capture 完成：Captured

PSP 拒付或处理失败：Failed

超时 / 冲正：以部署合约定义的最终状态为准

Notification 不得包含 PIN 块、密钥材料、CVV / CVC、完整磁道数据、原始 PAN 或未批准的原始 EMV 认证数据。

后续接口（Follow-up APIs）

操作	用途	期望源状态
`POST Capture`	完成预授权	`Authorised`
`POST Cancel`	在 Capture 之前撤销符合要求的授权	合约定义的授权状态
`POST Refund`	退款已 Capture 的交易	`Captured` 或符合要求的部分退款状态
`POST CancelOrRefund`	按交易状态自动选 Cancel 或 Refund	合约定义的状态
`GET Payment`	查询最新 Payment 状态	已有的交易标识符

这些操作复用现有的 Merchant Connect 交易生命周期，不创建独立的卡交易机制。

Step 4: 获取支付结果

从你的服务端向 EVO Cloud 发起 HTTP GET 请求查询支付结果：

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

参数	必填	说明
`merchantTransID`	M	待查询支付请求的 `merchantTransInfo.merchantTransID`。

查询响应示例：

{
  "result": {
    "code": "S0000",
    "message": "Success"
  },
  "merchantTransInfo": {
    "merchantTransID": "{{merchantTransId}}"
  },
  "payment": {
    "status": "Captured",
    "transID": "{{platformTransactionId}}",
    "transAmount": {
      "currency": "{{currency}}",
      "value": "{{amount}}"
    }
  },
  "paymentMethod": {
    "type": "card"
  },
  "transInitiator": {
    "platform": "POS",
    "terminalID": "{{terminalId}}"
  }
}

Step 5: 展示支付结果

用户完成支付、前端或客户端 APP 无需进一步操作时，使用 result.code 和 payment.status 向用户展示支付结果。

Result Code	说明
`S0000`	成功
`V0008`	字段 {} 不适用于 {...}
`C0004`	请求资源 merchantTransID {XXX} 不存在
`C0006`	请求资源 vault ID {XXX} 不存在
`C0008`	请求资源 paymentMethod token {XXX} 不存在
`B0005`	不支持的功能 {XXX}，请检查 EVO Cloud 的 profile 配置
`B0012`	交易状态 {XXX} 无效，无法完成请求
`B0019`	需要认证，请引导用户输入认证信息
`B0021`	用户认证结果显示高风险，{Payment / Tokenization} 失败，请让用户重试

其他可能的 result.code 值及推荐提示文案，请参见 EVO Cloud API Specification 附录。

若 result.code 为 S0000，还需进一步判断 payment.status：

Status	说明
`Authorised`	用于卡交易，表示授权成功、待 Capture（商户可发起 Cancel）。
`Captured`	卡交易：授权 + Capture 成功；电子钱包：交易成功完成。
`Failed`	支付失败。

其他可能的 payment.status 值及说明请参见 EVO Cloud API Specification。

错误处理

POST 请求给 EVO Cloud 后：建议至少等待 45 秒再判断是否超时。若该时间内未收到响应，需按 Step 4 主动查询结果。

GET 请求查询 EVO Cloud 时：可多次发起查询直到拿到结果，建议每次间隔至少 45 秒。多次查询仍无结果时，可按 capture 模式发起 Cancel 或 Refund 来结束交易。详见 After Payment 章节。

Payment

Merchant Connect 支付 - 卡片端到端处理流程#

Step 1: 获取可用支付方式#

Step 2: 收集用户的支付信息#

Step 3: 发起支付#

通用 Payment 字段#

paymentMethod 对象补充说明#

paymentMethod.card 字段#

卡的 posEntryMode 取值#

Purchase（消费）请求示例#

Pre-authorization（预授权）请求示例#

响应与状态处理#

消费响应示例#

Payment 状态模型#

Notification 通知#

后续接口（Follow-up APIs）#

Step 4: 获取支付结果#

Step 5: 展示支付结果#

错误处理#