国际信用卡（INTERNATIONAL_CARD）

本节用于说明信用卡支付的 methodCode 与 methodData 字段要求。

createAndPay 请求示例（完整）

{
  "merchantOrderNo": "M202412220001",
  "amount": "100",
  "currency": "USD",
  "productName": "Integration Test Product",
  "productDesc": "Full flow integration test",
  "remark": "Step 2: Create And Pay",
  "methodCode": "INTERNATIONAL_CARD",
  "billingAddress": {
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "addressLine1": "123 Test Street",
    "postalCode": "94102"
  },
  "methodData": {
    "cardNumber": "4242424242424242",
    "expiryMonth": "12",
    "expiryYear": "27",
    "securityCode": "123",
    "holderName": "Test Visa"
  }
}

Java Map 示例：

Map<String, Object> requestBody = Map.ofEntries(
        Map.entry("merchantOrderNo", merchantOrderNo),
        Map.entry("amount", "100"),
        Map.entry("currency", "USD"),
        Map.entry("productName", "Integration Test Product"),
        Map.entry("productDesc", "Full flow integration test"),
        Map.entry("remark", "Step 2: Create And Pay"),
        Map.entry("methodCode", "INTERNATIONAL_CARD"),
        Map.entry("billingAddress", Map.of(
                "country", "US",
                "state", "CA",
                "city", "San Francisco",
                "addressLine1", "123 Test Street",
                "postalCode", "94102"
        )),
        Map.entry("methodData", Map.of(
                "cardNumber", "4242424242424242",
                "expiryMonth", "12",
                "expiryYear", "27",
                "securityCode", "123",
                "holderName", "Test Visa"
        ))
);

请求字段（顶层）

必填

字段	说明
merchantOrderNo	商户订单号（幂等）
amount	订单金额，最小 0.01
currency	币种
methodCode	支付方式编码（INTERNATIONAL_CARD）
methodData	支付方式数据（见下方）

可选

字段	说明
productName	商品名称
productDesc	商品描述
billingAddress	账单地址（结构见 地址结构）
shippingAddress	邮寄地址（结构见 地址结构）
remark	备注
returnUrl	同步跳转 URL（优先级低于商户配置）
extParams	扩展参数（JSON）
lineItems	订单行项目（结构见 LineItem 结构）

方法编码

• methodCode: INTERNATIONAL_CARD

地址结构（billingAddress / shippingAddress）

字段	是否必填	说明
country	否	国家（ISO-3166-1 alpha-2，例如 US / GB / CN）
state	否	省 / 州 / 省份（US: CA / NY，CA: ON / BC）
city	否	城市
postalCode	否	邮政编码 / 邮编
addressLine1	否	街道地址 1（门牌号 + 街道名）
addressLine2	否	街道地址 2（楼层 / 房号 / 单元，可选）
name	否	收件人或持卡人姓名

示例：

{
  "country": "US",
  "state": "CA",
  "city": "San Francisco",
  "postalCode": "94102",
  "addressLine1": "123 Test Street",
  "addressLine2": "Suite 5F",
  "name": "Test Visa"
}

LineItem 结构

字段	是否必填	说明
name	否	商品名称
quantity	否	数量
sku	否	SKU
unitPrice	否	单价（最小单位）
totalAmount	否	总金额（最小单位）
taxAmount	否	税额（最小单位）
taxPercentage	否	税率（百分比 * 100）

示例：

{
  "name": "T-shirt",
  "quantity": 2,
  "sku": "TSHIRT-RED-M",
  "unitPrice": 2500,
  "totalAmount": 5000,
  "taxAmount": 300,
  "taxPercentage": 600
}

methodData 字段

createAndPay 接口使用明文卡字段，不需要加密字段。加密字段仅用于收银台类接口。

明文卡信息（createAndPay 必填）

字段	是否必填	说明
cardNumber	是	明文卡号
expiryMonth	是	明文有效期月份
expiryYear	是	明文有效期年份
securityCode	是	明文安全码 (CVV/CVC)

createAndPay 使用明文卡字段；收银台接口只允许加密字段。

其他可选字段

字段	是否必填	说明
holderName	否	持卡人姓名
statementDescriptor	否	账单描述
captureMethod	否	扣款方式: auto_capture / manual
threeDsMode	否	3DS 模式: required / optional / disabled
enabledOneClick	否	是否启用一键支付
shopperReference	否	用户唯一标识 (用于一键支付)
payToken	否	支付令牌 (一键支付时使用)

methodData 示例

明文卡示例：

{
  "cardNumber": "4111111111111111",
  "expiryMonth": "12",
  "expiryYear": "27",
  "securityCode": "123",
  "holderName": "Test Visa"
}