Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

卡支付特性

在发起授权支付时，您可以根据服务需求选择是否使用更多功能。本篇解释了这些附加功能及其使用方法。

3D Secure2 验证

3D Secure 2（3DS2） 是一种增强型身份验证协议，专为无卡（CNP）交易设计，旨在通过多层验证机制提升支付安全性。该协议不仅可协助商户满足欧盟《支付服务指令修订版第二版》（PSD2）的强客户认证（SCA）要求（适用于欧洲经济区内的在线交易），同时支持通过责任转移规则降低交易争议风险。当持卡人完成认证后，发卡方将承担欺诈交易的主要责任。

优势

  • 对于有风险的交易，可以通过 3DS2 认证来降低盗卡率和拒付率。
  • 同时对于未来可能发生的拒付交易，将责任转移给发卡行。

用户体验

当您决策这笔交易需要 3D Secure2 验证（下面简称 3D 验证）时，发卡行会有以下两种形态，对应的用户体验如下：

需跳转到 3DS2 URL，但是无需买家操作，用于收集环境信息：

3d-1.png

设置 3D 验证

您可以通过指定是否需要进行 3D 验证的 is3DSAuthentication 参数来选择。

  • 不设置 is3DSAuthentication 参数：结果等同于将参数设置为 false，支付将不强制进行 3D 验证。
  • 将 is3DSAuthentication 设置为 false：支付将不强制进行 3D 验证。
  • 将 is3DSAuthentication 设置为 true：支付将强制启用 3D 验证。

注意：

智能交易恢复

交易恢复功能允许在需要 3D 验证的卡组织交易中自动发起 3D 验证过程。这使得无论您之前是否选择了 3D 验证，您都可以恢复这些交易。

您可以通过将 enableAuthenticationUpgrade 设置为 true，来为交易启用交易恢复功能。如果不启用此功能，且交易的卡种需要 3D 验证，但您未进行 3D 验证，卡组织会将此交易视为高风险并拒绝支付。

注意：

设置 3D 验证和自动交易恢复将共同决定交易是否最终走 3DS 验证。下表展示了这两个功能的设置对交易的影响：

设置 3D 验证：

is3DSAuthentication

设置自动交易恢复：

enableAuthenticationUpgrade

交易最终是否进行 3D 验证

false/留空

true/留空

无 3D 验证的支付失败后，此支付会自动触发 3D 验证，Antom 将返回渲染 3D 验证页面的链接。

false/留空

false

如果无 3D 验证的支付失败，Antom 将返回失败支付的结果。

true

true/false/留空

此支付需要进行 3D 验证，并且 Antom 会返回一个用于渲染 3D 验证页面的链接。

表 1. 两个功能的设置对交易是否进行 3D 验证的影响

对于 SDK 集成，SDK 会处理重定向到 3D 验证页面，您无需额外操作。对于接口集成，当 Antom 返回用于渲染 3D 验证页面的链接后，您需要显示验证页面并引导买家完成验证过程。以下代码示例展示了如何通过 支付（收银台）接口的响应返回链接：

copy
{
  "result": {
    "resultStatus": "U",
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "payment in process"
  },
  "normalUrl": "https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect/...",
  "paymentId": "20221111194010890100111650285726898",
  "paymentRequestId": "amsdmpay_cangxi_lj_20221111_104718_672",
  "redirectActionForm": {
    "redirectUrl": "https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect/...",
    "method": "GET"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "100"
  },
  "paymentCreateTime": "2022-11-10T18:47:20-08:00"
}

增值风险控制服务

如果您需要更高级别的支付风险控制服务，可以购买 Antom 提供的增值风险控制服务。此服务根据支付的风险级别提供智能风险控制策略。

启用增值风控服务、设置 3D 验证和自动交易恢复，将共同决定交易是否最终走 3D 验证。下表展示了这三个功能的设置对交易的影响：

增值服务风险控制

设置 3D 验证：

is3DSAuthentication

设置自动交易恢复： 

enableAuthenticationUpgrade

交易最终是否进行 3D 验证

启用

false/留空

false

风险控制服务决定是否执行 3D 验证。

启用

false/留空

true/留空

风险控制系统决定是否执行 3D 验证。如果风控认为此支付风险较高，该支付会被直接拒绝。

如果风险控制服务决定不请求 3DS 验证，Antom 将返回 3D 验证页面的渲染链接。

启用

true

true/false/留空

即使风险控制系统决定不执行 3D 验证，Antom 也会返回 3D 验证页面的渲染链接。

如果风控认为词支付风险较高，该支付会被直接拒绝。

表 2. 三个功能的设置对交易是否进行 3D 验证的影响

注意：

  • 如果您购买了增值风险控制服务，无需指定 is3DSAuthentication 参数。风险控制服务将为您提供风险控制策略，策略包括高风险拒绝，以及是否执行 3D 验证。
  • 对于某些在当地卡组织监管下的银行卡发起的支付，比如巴西银行卡和韩国银行卡，由于 3D 验证功能不可用，可能会影响增值风控的效果，请谨慎启用该功能。

AVS 检查

地址验证系统（AVS）检查会将交易中使用的账单地址与发卡行记录的持卡人地址信息进行对比，以检测欺诈行为。 通过发起AVS检查，系统会自动对比买家输入的账单地址和电子邮件地址与发卡行存储的信息。 如果这些信息不匹配，可能会导致支付被拒绝或需要额外的身份验证。

发起支付

在启用AVS检查服务后，您可以根据您的集成模式发起 AVS 检查：

注意：

  • 您可以通过从 支付通知 或 支付结果查询 接口响应中的 request.paymentResultInfo.avsResultRaw 参数获取 AVS 检查的结果。
  • 此功能仅适用于在美国卡方案监管下使用美国卡发起的支付。

接口集成

服务端-服务端模式

在服务端-服务端模式中，您需要获取买家的银行卡信息和账单地址信息，并通过 支付（收银台） 接口指定 billingAddress 参数来发起 AVS 校验。

以下是通过账单地址调用支付请求的示例：

copy
{
    "order": {
        "orderAmount": {
            "currency": "USD",
            "value": "100"
        },
        "orderDescription": "《Bad Romance》-Lady Gaga",
        "referenceOrderId": "ORDER_20231208164745347",
        "goods": [
            {
                "goodsCategory": "Digital Goods",
                "goodsName": "《Bad Romance》",
                "goodsQuantity": "1",
                "goodsUnitAmount": {
                    "currency": "USD",
                    "value": "100"
                },
                "goodsUrl": "https://www.youtube.com/watch?v=QdaG6pDOz5A",
                "referenceGoodsId": "GOODS_20231208164745347"
            }
        ],
        "shipping": {
            "shippingName": {
                "firstName": "lady",
                "fullName": "lady gaga",
                "lastName": "gaga"
            },
            "shippingPhoneNo": "123456789"
        },
        "buyer": {
            "buyerEmail": "gaga@gaga.com",
            "buyerName": {
                "firstName": "lady",
                "fullName": "lady gaga",
                "lastName": "gaga"
            },
            "buyerPhoneNo": "123456789",
            "referenceBuyerId": "88888888"
        }
    },
    "env": {
        "terminalType": "WEB",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
        "deviceLanguage": "zh_CN"
    },
    "paymentAmount": {
        "currency": "USD",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodMetaData": {
            "cardholderName": {
                "firstName": "Lady",
                "lastName": "Gaga"
            },
            "billingAddress": {
                "zipCode": "94043",
                "address2": "gongzhuan Road",
                "city": "Sunnyvale",
                "address1": "mountain view Road",
                "state": "CA",
                "region": "US"
            },
            "cvv": "850",
            "expiryMonth": "12",
            "expiryYear": "29",
            "cardNo": "4294097400915107"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "paymentNotifyUrl": "https://kademo.intlalipay.cn/payments/notifySuccess",
    "paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
    "paymentRequestId": "PAY_20231208164745347",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

SDK 集成

对于 SDK 集成，Antom 提供了买家输入支付和账单信息的页面，您无需进行额外的开发工作。

以下是一个不包含账单地址的 支付会话创建（收银台）接口调用示例：

copy
{
    "order": {
        "orderAmount": {
            "currency": "USD",
            "value": "100"
        },
        "orderDescription": "《Bad Romance》-Lady Gaga",
        "referenceOrderId": "ORDER_20231106113345977",
        "goods": [
            {
                "goodsCategory": "Digital Goods",
                "goodsName": "《Bad Romance》",
                "goodsQuantity": "1",
                "goodsUnitAmount": {
                    "currency": "USD",
                    "value": "100"
                },
                "goodsUrl": "https://www.youtube.com/watch?v=QdaG6pDOz5A",
                "referenceGoodsId": "GOODS_20231106113345977"
            }
        ],
        "shipping": {
            "shippingName": {
                "firstName": "lady",
                "fullName": "lady gaga",
                "lastName": "gaga"
            },
            "shippingPhoneNo": "123456789"
        },
        "buyer": {
            "buyerEmail": "gaga@gaga.com",
            "buyerName": {
                "firstName": "lady",
                "fullName": "lady gaga",
                "lastName": "gaga"
            },
            "buyerPhoneNo": "123456789",
            "referenceBuyerId": "88888888"
        }
    },
    "env": {
        "terminalType": "WEB",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
        "deviceLanguage": "zh_CN"
    },
    "paymentAmount": {
        "currency": "USD",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD"
    },
    "enableInstallmentCollection":true,
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "paymentNotifyUrl": "https://kademo.intlalipay.cn/payments/notifySuccess",
    "paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
    "paymentRequestId": "PAY_20234411061ooo133459707",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

Antom 为您的买家提供了以下信息收集页面以填写：

image.png

图 2. 支付信息收集页面（SDK）

接收支付结果通知

以下代码示例展示了支付结果通知中的 AVS 检查结果。

copy
{
  "actualPaymentAmount": {
    "currency": "USD",
    "value": "100"
  },
  "cardInfo": {
    "avsResultRaw": "Y",
    "cardBrand": "JCB",
    "cardNo": "************3566",
    "cvvResultRaw": "X",
    "funding": "CREDIT",
    "issuingCountry": "US",
    "networkTransactionId": "200719820486071",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "USD",
    "value": "100"
  },
  "paymentCreateTime": "2024-03-28T20:35:23-07:00",
  "paymentId": "20240329114010800100181570206917730",
  "paymentRequestId": "2024032938401734456237",
  "paymentResultInfo": {
    "avsResultRaw": "Y",
    "cardBrand": "JCB",
    "cardNo": "************3566",
    "cvvResultRaw": "X",
    "funding": "CREDIT",
    "issuingCountry": "US",
    "networkTransactionId": "200719820486071",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-03-28T20:35:29-07:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

常见问题

问： 如果为 billingAddress 指定错误的值，交易会失败吗？

答：如果 billingAddress 的值指定不正确，以下场景可能导致交易失败：

  • 异常参数值：当指定 billingAddress 参数时，需要提供 region 值。如果缺少必需的值，或者 region 值与指定的 state 值不匹配，调用 支付（收银台）接口时会异常返回错误代码。发生此错误时，支付会失败，Antom 不会发送支付失败的异步通知。
  • 信息不匹配：如果地址信息存在不一致，可能会导致交易失败。例如，如果买家在银行账户注册时提供的账单地址是 CA ，但请求中指定的 billingAddress 值是 FL ，则存在地址信息不匹配。在这种情况下，您可以根据 avsResultRaw 的值来决定是否继续发货。

问：如何理解 avsResultRaw 中不同枚举值的含义？

答：请参考 AVS 结果代码以获取更多信息。

问：如果我已经存储了支付和账单地址信息，我还需要在信息收集页面上收集这些信息吗？

  • 接口集成的托管模式：如果您已经存储了买家的支付和账单地址信息，将存储值传递给 支付（收银台）接口的 billingAddress 参数。这样，支付和账单地址信息将在 Antom 中间页面上显示，以避免买家重复填写信息，提升支付体验。
  • SDK 集成方式：如果您已经存储了买家的支付和账单地址信息，将存储值传递给 支付会话创建（收银台）接口的 billingAddress 参数。这样，支付和账单地址信息将在 Antom 中间页面上显示，以避免买家重复填写信息，提升支付体验。

银行卡信息存储

您可以允许买家添加他们的银行卡。也就是说， 买家在首次支付时可以选择保存他们的银行卡信息，以便后续支付时无需重新输入信息。 下图显示了在首次支付时保存了银行卡信息的买家进行后续支付时的结账页面。

卡支付特性1.png

图 3. 使用之前保存的银行卡信息进行后续支付的结账页面

接口集成

添加买家的银行卡方式因集成模式而异。对于服务器到服务器模式和托管模式，请按照以下步骤操作：

服务端-服务端模式

在服务端-服务端模式收集买家支付信息后，您可以选择自己存储银行卡信息或者让 Antom 替您存储。

  • Antom 存储银行卡信息（推荐）

当买家在您的页面存储银行卡信息时，通过 支付（收银台） 接口向 Antom 传递银行卡信息然后将 tokenize 设置为 true。Antom 为银行卡信息生成相应的银行卡令牌（cardToken）。在支付授权成功之后，通过接受异步通知或调用 支付结果查询 接口获取银行卡令牌（cardToken）和脱敏卡号（cardNo）。为了处理后续支付，您必须存储并关联获取的银行卡令牌，脱敏卡号以及其他买家相关信息。

以下示例代码展示了在您收集银行卡信息之后 Antom 存储银行卡信息时， 支付（收银台）接口发起的请求：

copy
{
  "settlementStrategy": {
    "settlementCurrency": "EUR"
  },
  "productCode": "CASHIER_PAYMENT",
  "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_GROUP&paymentMethodType=CARD",
  "paymentRequestId": "2****************2",
  "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=2023070458941025622196",
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodMetaData": {
      "recurringType": "",
      "cvv": "123",
      "is3DSAuthentication": false,
      "isCardOnFile": false,
      "expiryMonth": "05",
      "tokenize": true,
      "expiryYear": "26",
      "billingAddress": {
        "zipCode": "310000",
        "address2": "gongzhuan Road",
        "city": "hangzhou",
        "state": "zhejiang",
        "region": "CN"
      },
      "cardNo": "****1846"
    },
    "paymentMethodType": "CARD"
  },
  "paymentExpiryTime": "2025-11-27T12:00:01+08:30",
  "paymentAmount": {
    "currency": "EUR",
    "value": "8204"
  },
  "merchantRegion": "",
  "order": {
    "orderAmount": {
      "currency": "EUR",
      "value": "8204"
    },
    "referenceOrderId": "2********************0",
    "shipping": {
      "shippingName": {
        "firstName": "Li",
        "lastName": "Kyle",
        "fullName": "Kyle Li"
      },
      "shippingCarrier": "DHL",
      "shippingPhoneNo": "**********19",
      "shipToEmail": "exam***@163.com",
      "shippingAddress": {
        "zipCode": "310000",
        "address2": "gongzhuan Road",
        "city": "hangzhou",
        "state": "zhejiang",
        "region": "CN"
      }
    },
    "goods": [
      {
        "referenceGoodsId": "2******************7",
        "goodsUrl": "qinghailipipeng",
        "goodsCategory": "chemical",
        "goodsUnitAmount": {
          "currency": "EUR",
          "value": "8204"
        },
        "goodsQuantity": "1",
        "goodsName": "boom",
        "goodsSkuName": "boom boom room",
        "goodsBrand": "antom boom"
      }
    ],
    "env": {
      "clientIp": "1.1.1.1",
      "osType": "IOS",
      "terminalType": "WAP"
    },
    "orderDescription": "ANTOM_ZZ",
    "buyer": {
      "referenceBuyerId": "2******************7",
      "buyerName": {
        "firstName": "Li",
        "lastName": "Kyle",
        "fullName": "Kyle Li"
      }
    }
  }
}

下列代码示例展示了 支付 接口的响应：

copy
{
    "authExpiryTime": "2024-07-28T23:39:24-07:00",
    "paymentAmount": {
        "currency": "HKD",
        "value": "30000"
    },
    "paymentCreateTime": "2024-07-21T23:39:22-07:00",
    "paymentId": "202407221940108001001885G0208567301",
    "paymentRequestId": "PAY_202312440481411544445328",
    "paymentResultInfo": {
        "avsResultRaw": "I",
        "cardBrand": "VISA",
        "cardNo": "************8888",
        "cvvResultRaw": "P",
        "networkTransactionId": "20240722890313000005G3529937210",
        "threeDSResult": {
            "cavv": "",
            "eci": ""
        }
    },
    "paymentTime": "2024-07-21T23:39:24-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

当买家使用已保存银行卡发起支付时，请完成以下步骤：

  1. 在结算页面显示脱敏银行卡信息给买家。
  2. 通过 支付 接口传递以下参数：
  1. paymentMethodId：值与 cardToken 相同（从 支付通知 和 支付结果查询 中的 paymentResultInfo 中获取）。
  2. 额外的验证参数（如巴西银行卡的 cpf）
  3. isCardOnFile：设置为true。此参数用于识别后续使用已保存银行卡的支付。

以下代码展示了买家使用已保存银行卡支付时，支付 接口使用银行卡令牌发起请求：

copy
{
  "settlementStrategy": {
    "settlementCurrency": "EUR"
  },
  "productCode": "CASHIER_PAYMENT",
  "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_GROUP&paymentMethodType=CARD",
  "paymentRequestId": "2****************2",
  "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=2023070471913565376977",
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodId": "A********************************************************************************************=",
    "paymentMethodMetaData": {
      "recurringType": "SCHEDULED",
      "is3DSAuthentication": false,
      "isCardOnFile": true,
      "networkTransactionId": "2*************5"
    },
    "paymentMethodType": "CARD"
  },
  "paymentExpiryTime": "2025-11-27T12:00:01+08:30",
  "paymentAmount": {
    "currency": "EUR",
    "value": "3063"
  },
  "merchantRegion": "",
  "order": {
    "orderAmount": {
      "currency": "EUR",
      "value": "3063"
    },
    "referenceOrderId": "2****************1",
    "shipping": {
      "shippingName": {
        "firstName": "Li",
        "lastName": "Kyle",
        "fullName": "Kyle Li"
      },
      "shippingCarrier": "DHL",
      "shippingPhoneNo": "**********119",
      "shipToEmail": "exam***@163.com",
      "shippingAddress": {
        "zipCode": "310000",
        "address2": "gongzhuan Road",
        "city": "hangzhou",
        "state": "zhejiang",
        "region": "CN"
      }
    },
    "goods": [
      {
        "referenceGoodsId": "2********************9",
        "goodsUrl": "qinghailipipeng",
        "goodsCategory": "chemical",
        "goodsUnitAmount": {
          "currency": "EUR",
          "value": "3063"
        },
        "goodsQuantity": "1",
        "goodsName": "boom",
        "goodsSkuName": "boom boom room",
        "goodsBrand": "antom boom"
      }
    ],
    "env": {
      "clientIp": "1.1.1.1",
      "osType": "IOS",
      "terminalType": "WAP"
    },
    "orderDescription": "ANTOM_ZZ",
    "buyer": {
      "referenceBuyerId": "K*****************3",
      "buyerName": {
        "firstName": "Li",
        "lastName": "Kyle",
        "fullName": "Kyle Li"
      }
    }
  }
}

下列代码示例展示了 支付 接口的响应：

copy
{
    "authExpiryTime": "2024-07-28T23:39:24-07:00",
    "paymentAmount": {
        "currency": "HKD",
        "value": "30000"
    },
    "paymentCreateTime": "2024-07-21T23:39:22-07:00",
    "paymentId": "202407221940108001001885G0208567301",
    "paymentRequestId": "PAY_202312440481411544445328",
    "paymentResultInfo": {
        "avsResultRaw": "I",
        "cardBrand": "VISA",
        "cardNo": "************8888",
        "cvvResultRaw": "P",
        "networkTransactionId": "20240722890313000005G3529937210",
        "threeDSResult": {
            "cavv": "",
            "eci": ""
        }
    },
    "paymentTime": "2024-07-21T23:39:24-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}
  • 您自己存储银行卡信息

当买家在您的页面保存银行卡信息时，您需要保存并关联买家信息以及在您服务端相应的银行卡信息。当买家再次发起支付时，您需要通过 支付 接口传递银行卡信息并将 isCardOnFile 设置为true。isCardOnFile 通常用于识别后续使用已保存银行卡的支付。设置此参数有助于提高支付成功率。

以下示例代码展示了买家使用已支付银行卡支付时 支付 接口如何发起请求：

copy
{
  "env": {
    "terminalType": "APP",
    "clientIp": "112.80.248.78",
    "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
    "osType": "IOS",
    "deviceLanguage": "zh_CN",
    "colorDepth": 48,
    "screenHeight": 768,
    "screenWidth": 1024,
    "timeZoneOffset": 1
  },
  "order": {
    "orderAmount": {
      "currency": "EUR",
      "value": "30000"
    },
    "orderDescription": "Cappuccino #grande (Mika's coffee shop)",
    "referenceOrderId": "ORDER_2022111414171****",
    "goods": [
      {
        "referenceGoodsId": "383382011_SGAMZ-90452****",
        "goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
        "goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
        "goodsCategory": "Digital  Goods/Digital  Vouchers/Food  and Beverages",
        "goodsUnitAmount": {
          "currency": "EUR",
          "value": "30000"
        },
        "goodsQuantity": "10"
      }
    ],
    "shipping": {
      "shippingName": {
        "firstName": "Dehua",
        "lastName": "Liu",
        "fullName": "Dehua Skr Liu",
        "middleName": "Skr"
      },
      "shippingAddress": {
        "zipCode": "310000",
        "address2": "Xihu",
        "city": "Hangzhou",
        "address1": "Wuchang road",
        "state": "Zhejiang",
        "region": "CN"
      },
      "shippingCarrier": "FedEx",
      "shippingPhoneNo": "1234567****",
      "shipToEmail": "test@gmail.com"
    },
    "buyer": {
      "referenceBuyerId": "test12345678",
      "buyerPhoneNo": "1234567****",
      "buyerEmail": "alipay@alipay.com",
      "buyerName": {
        "firstName": "Dehua",
        "lastName": "Liu",
        "fullName": "Dehua Skr Liu",
        "middleName": "Skr"
      }
    }
  },
  "paymentAmount": {
    "currency": "EUR",
    "value": "30000"
  },
  "paymentMethod": {
    "paymentMethodType": "CARD",
    "paymentMethodMetaData": {
      "isCardOnFile": true,
      "enableAuthenticationUpgrade": false,
      "is3DSAuthentication": false,
      "cardholderName": {
        "firstName": "Tom",
        "lastName": "Jay"
      },
      "expiryMonth": "12",
      "billingAddress": {
        "zipCode": "310000",
        "address2": "Xihu",
        "city": "Hangzhou",
        "address1": "Wuchang road",
        "state": "Zhejiang",
        "region": "CN"
      },
        "expiryYear": "29",
        "cardNo": "411734780615****"
      }
      },
        "settlementStrategy": {
        "settlementCurrency": "EUR"
      },
        "paymentNotifyUrl": "https://www.alipay.com/notify",
        "paymentRedirectUrl": "https://www.alipay.com",
        "paymentRequestId": "PAY_2022111414171****",
        "productCode": "CASHIER_PAYMENT",
        "paymentFactor": {
        "isAuthorization": true
      }
      }

下列代码示例展示了 支付 接口的响应：

copy
{
    "authExpiryTime": "2024-07-31T00:33:18-07:00",
    "paymentAmount": {
        "currency": "KRW",
        "value": "30000"
    },
    "paymentCreateTime": "2024-07-24T00:33:17-07:00",
    "paymentId": "202407241940108001001882J0208558886",
    "paymentRequestId": "PAYMENT_20240724153316184_AUTO",
    "paymentResultInfo": {
        "avsResultRaw": "",
        "cardBrand": "BC",
        "cardNo": "************3803",
        "cvvResultRaw": "",
        "threeDSResult": {
            "cavv": "",
            "eci": ""
        }
    },
    "paymentTime": "2024-07-24T00:33:18-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

SDK 集成

在这种集成模式下，SDK 提供了一个支付信息收集页面。买家输入他们的银行卡信息，并可以选择保存信息，以便后续支付时无需再次输入。当买家选择保存卡信息时，Antom 会存储这些信息并生成对应的银行卡令牌（cardToken）。在授权此支付后，您可以通过接收异步通知或调用 支付结果查询 接口来获取买家的银行卡信息（cardInfo）。银行卡信息包括银行卡令牌（cardToken）和脱敏的银行卡信息。

当买家使用已保存的银行卡进行后续支付时，您需要在调用 支付会话创建（收银台）接口时将 paymentMethodId 设为 cardToken 的值。 以下代码示例展示了当买家使用已保存的银行卡进行后续支付时，您的服务器如何调用 支付会话创建（收银台）接口：

copy
{
    "productCode": "CASHIER_PAYMENT",
    "paymentRequestId": "55bf93a6-71a1-4ca9-b014-53273bd674eb",
    "order": {
        "referenceOrderId": "926e1c32-4a6c-442e-b5ce-8ec5b902e18c",
        "orderDescription": "xxxxx",
        "orderAmount": {
            "currency": "BRL",
            "value": "100"
        },
        "buyer": {
            "referenceBuyerId": "yeiasdasda",
            "buyerPhoneNo": "134******71"
        }
    },
    "paymentAmount": {
        "currency": "BRL",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodId": "alipayCardToken"
    },
    "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
    "paymentNotifyUrl": "https://www.yourNotifyUrl",
    "paymentFactor": {
        "isAuthorization": true
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    }
}

MIT

商户发起交易（MIT）是指一种预先授权的银行卡支付交易类型，即在无需买家参与的情况下进行的定期或不定期交易。

注意：

  • MIT 是一种无需 3D 验证的交易类型。
  • 在发起 MIT 之前，您必须获得买家的授权，这需要买家首次为支付完成 3D 验证。
  • 对于使用特定本地卡组织的银行卡发起的支付，此功能不可用。这些银行卡包括巴西银行卡、韩国银行卡、智利银行卡、墨西哥银行卡和 秘鲁银行卡。

您需要调用 支付（收银台）接口来发起 MIT。请注意以下参数的设置：

  • isCardOnFile ：值为 true ，表示该支付是使用已保存的银行卡进行的后续支付。
  • recurringType ： 值为 SCHEDULED 或 UNSCHEDULED ，用于指定此支付是定期还是非定期支付。
  • networkTransactionId ： Antom 需要确认您已获得买家授权以完成 MIT。因此，您必须向此参数传递一个专属 ID。 该 ID 由银行卡组织为识别首次授权的支付而分配。当买家使用首次授权完成支付时，您可以通过 支付通知 接口或 支付结果查询 接口获取该 ID。

支持服务器到服务器模式和托管模式的自动扣款。以下代码示例展示了您的服务器如何在服务器到服务器模式下调用 支付（收银台）接口来发起 MIT（免密支付）：

copy
{
    "env": {
        "browserInfo": {
            "acceptHeader": "*/*",
            "javaEnabled": true,
            "javaScriptEnabled": true,
            "language": "zh_CN",
            "userAgent": "Chrome/100"
        },
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe",
        "osType": "IOS",
        "deviceLanguage": "zh_CN",
        "colorDepth": 48,
        "screenHeight": 768,
        "screenWidth": 1024,
        "timeZoneOffset": 1
    },
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "30000"
        },
        "orderDescription": "Cappuccino #grande (Mika's coffee shop)",
        "referenceOrderId": "ORDER_20221114141714891",
        "goods": [
            {
                "referenceGoodsId": "383382011_SGAMZ-904520356",
                "goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
                "goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
                "goodsCategory": "Digital Goods/Digital Vouchers/Food  and Beverages",
                "goodsUnitAmount": {
                    "currency": "EUR",
                    "value": "30000"
                },
                "goodsQuantity": "10"
            }
        ],
        "shipping": {
            "shippingName": {
                "firstName": "Dehua",
                "lastName": "Liu",
                "fullName": "Dehua Skr Liu",
                "middleName": "Skr"
            },
            "shippingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "shippingCarrier": "FedEx",
            "shippingPhoneNo": "12345678912",
            "shipToEmail": "test@gmail.com"
        },
        "buyer": {
            "referenceBuyerId": "test12345678",
            "buyerPhoneNo": "12345678912",
            "buyerEmail": "alipay@alipay.com",
            "buyerName": {
                "firstName": "Dehua",
                "lastName": "Liu",
                "fullName": "Dehua Skr Liu",
                "middleName": "Skr"
            }
        }
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "30000"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodMetaData": {
            "isCardOnFile": true,
            "recurringType": "SCHEDULED",
            "networkTransactionId": "referenceNetworkTransactionId12345",
            "enableAuthenticationUpgrade": false,
            "is3DSAuthentication": false,
            "cvv": "850",
            "cardholderName": {
                "firstName": "Tom",
                "lastName": "Jay"
            },
            "expiryMonth": "12",
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "expiryYear": "29",
            "cardNo": "4117347806156383"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "paymentNotifyUrl": "https://www.alipay.com/notify",
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentRequestId": "PAY_20221114141714891",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

指定银行卡品牌

商家端收集明文银行卡信息，并使用接口集成银行卡支付。如果买家选择了双标卡进行授权支付，您可以通过 selectedCardBrands 参数指定交易中使用银行卡品牌的地区。

注意：

  • 如果不设置 selectedCardBrands ，Antom 将为您选择一个银行卡品牌进行授权支付。
  • 如果您接受欧洲双标卡，需要向买家提供清晰的支付方案。详情请参考双标卡合规性。

双标卡支付的处理流程如下图所示：

卡支付特性流程1.png

图 4. 双标卡支付流程

对应的请求示例如下：

copy
{
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "30000"
        },
        "orderDescription": "《Bad Romance》-Lady Gaga",
        "referenceOrderId": "ORDER_20231208111545328",
        "goods": [
            {
                "goodsCategory": "Digital Goods",
                "goodsName": "《Bad Romance》",
                "goodsQuantity": "1",
                "goodsUnitAmount": {
                    "currency": "HKD",
                    "value": "30000"
                },
                "goodsUrl": "https://www.youtube.com/watch?v=QdaG6pDOz5A",
                "referenceGoodsId": "GOODS_20231208111545328"
            }
        ],
        "shipping": {
            "shippingName": {
                "firstName": "lady",
                "fullName": "lady gaga",
                "lastName": "gaga"
            },
            "shippingPhoneNo": "123456789"
        },
        "buyer": {
            "buyerEmail": "gaga@gaga.com",
            "buyerName": {
                "firstName": "lady",
                "fullName": "lady gaga",
                "lastName": "gaga"
            },
            "buyerPhoneNo": "123456789",
            "referenceBuyerId": "88888888"
        }
    },
    "env": {
        "terminalType": "WEB",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
        "deviceLanguage": "zh_CN"
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "30000"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodMetaData": {
            "cardholderName": {
                "firstName": "Lady",
                "lastName": "Gaga"
            },
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "cvv": "850",
            "expiryMonth": "12",
            "expiryYear": "29",
            "cardNo": "4390807888888888",
            "selectedCardBrand": "VISA"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "SGD"
    },
    "paymentNotifyUrl": "https://kademo.intlalipay.cn/payments/notifySuccess",
    "paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
    "paymentRequestId": "PAY_2023154445445328",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

MPI

如果您让买家在发起授权支付前通过第三方完成 3D Secure 认证，通过 mpiData 传递 3D Secure 认证结果，并在调用 支付 接口时指定此支付为非 3D Secure 认证。

字段

描述

mpiData.threeDSVersion

由第三方认证机构返回的 3D Secure 协议版本。

mpiData.caav

由第三方认证机构返回的持卡人认证值。

mpiData.dsTransactionId

由第三方认证机构返回的专属 ID。

mpiData.eci

由第三方认证机构返回的电子 commerce 指示器（ECI）。

is3DSAuthentication

设置为false。买家已完成 3D Secure 认证。指定交易为非 3D 认证方式。

enableAuthenticationUpgrade

设置为false。买家已完成 3D Secure 认证。无需将交易升级为 3D Secure 认证。

表 3. MPI信息

注意：MPI 功能对于在任何韩国卡计划下使用韩国卡发起的支付不可用。

以下代码示例展示了调用 支付 接口时带有 mpiData 的请求：

copy
{
    "env": {
        "browserInfo": {
            "acceptHeader": "*/*",
            "javaEnabled": true,
            "javaScriptEnabled": true,
            "language": "zh_CN",
            "userAgent": "Chrome/100"
        },
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "e******************************************1",
        "osType": "IOS",
        "deviceLanguage": "zh_CN",
        "colorDepth": 48,
        "screenHeight": 768,
        "screenWidth": 1024,
        "timeZoneOffset": 1
    },
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "30000"
        },
        "orderDescription": "Cappuccino #grande (Mika's coffee shop)",
        "referenceOrderId": "O*******************1",
        "goods": [
            {
                "referenceGoodsId": "383382011_SGAMZ-90452****",
                "goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
                "goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
                "goodsCategory": "Digital  Goods/Digital  Vouchers/Food  and Beverages",
                "goodsUnitAmount": {
                    "currency": "EUR",
                    "value": "30000"
                },
                "goodsQuantity": "10"
            }
        ],
        "shipping": {
            "shippingName": {
                "firstName": "Dehua",
                "lastName": "Liu",
                "fullName": "Dehua Skr Liu",
                "middleName": "Skr"
            },
            "shippingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "shippingCarrier": "FedEx",
            "shippingPhoneNo": "1234567****",
            "shipToEmail": "test***@gmail.com"
        },
        "buyer": {
            "referenceBuyerId": "t**********4",
            "buyerPhoneNo": "********567",
            "buyerEmail": "exam***@alipay.com",
            "buyerName": {
                "firstName": "D****",
                "lastName": "L****",
                "fullName": "Dehua Skr****",
                "middleName": "S****"
            }
        }
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "30000"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodMetaData": {
            "isCardOnFile": false,
            "enableAuthenticationUpgrade": false,
            "is3DSAuthentication": false,
            "mpiData": {
                "eci": "02",
                "threeDSVersion": "2.2.0",
                "caav": "cavvSample",
                "dsTransactionId": "sample_dsTranascti****"
            },
            "cvv": "850",
            "cardholderName": {
                "firstName": "Tom",
                "lastName": "Jay"
            },
            "expiryMonth": "12",
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "expiryYear": "29",
            "cardNo": "****0615"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "paymentNotifyUrl": "https://www.alipay.com/notify",
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentRequestId": "P*******************1",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

以下代码示例展示了调用 支付会话创建（收银台）接口时带有 mpiData 的请求：

copy
{
    "env": {
        "clientIp": "112.80.248.78"
    },
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "30000"
        },
        "orderDescription": "Cappuccino #grande (Mika's coffee shop)",
        "referenceOrderId": "O********************1",
        "goods": [
            {
                "referenceGoodsId": "3********************2",
                "goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
                "goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
                "goodsCategory": "Digital  Goods/Digital  Vouchers/Food  and Beverages",
                "goodsUnitAmount": {
                    "currency": "EUR",
                    "value": "30000"
                },
                "goodsQuantity": "10"
            }
        ],
        "shipping": {
            "shippingName": {
                "firstName": "Dehua",
                "lastName": "Liu",
                "fullName": "Dehua Skr Liu",
                "middleName": "Skr"
            },
            "shippingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "shippingCarrier": "FedEx",
            "shippingPhoneNo": "1234567****",
            "shipToEmail": "test@gmail.com"
        },
        "buyer": {
            "referenceBuyerId": "test1234****",
            "buyerPhoneNo": "1234567****",
            "buyerEmail": "example@alipay.com",
            "buyerName": {
                "firstName": "D****",
                "lastName": "L****",
                "fullName": "Dehua Skr****",
                "middleName": "S****"
            }
        }
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "30000"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodMetaData": {
            "isCardOnFile": false,
            "enableAuthenticationUpgrade": false,
            "is3DSAuthentication": false,
            "mpiData": {
                "eci": "02",
                "threeDSVersion": "2.2.0",
                "caav": "cavvSample",
                "dsTransactionId": "sample_dsTranascti****"
            },
            "cvv": "850",
            "cardholderName": {
                "firstName": "Tom",
                "lastName": "Jay"
            },
            "expiryMonth": "12",
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "expiryYear": "29",
            "cardNo": "****0615"
        }
    },

分期付款

您可以为买家提供分期付款的能力，让他们可以选择分期付款方式。以下图示展示了分期付款的用户体验:

image.png

图 5. 分期付款的用户体验

上图中，买家选择银行卡分期付款方式后，系统会显示分期付款的相关信息，如分期数、每期金额等，然后买家进行首期付款。

买家完成首期付款后，Antom 根据合同规定的结算周期结算全部订单金额。

注意：使用分期付款服务时，您无需为买家提供任何资金。因此，建议您不要向买家收取分期付款费用。

获取银行卡品牌分期信息

您可以通过调用 咨询 接口获取支付方式的分期信息。返回的分期信息包括支持的银行卡品牌、可用的分期数以及可分期的最高和最低总金额。

支持分期付款的银行卡品牌如下表所示。

卡类型

分期功能

支持情况

巴西卡（Brazilian cards）

2-12期

仅支持信用卡

韩国卡（Korean cards）

2-12期

仅支持信用卡

表 4. 分期付款

以下代码示例展示了由 咨询 接口返回的银行卡分期信息：

copy
{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "success."
  },
  "paymentOptions": [
    {
      "paymentMethodRegion": [
        "BR"
      ],
      "paymentMethodCategory": "CARD",
      "installment": {
        "plans": [
          {
            "interestRate": "0.00",
            "installmentNum": "2",
            "interval": "MONTH",
            "minInstallmentAmount": {
              "currency": "BRL",
              "value": "500"
            },
            "enabled": true,
            "maxInstallmentAmount": {
              "currency": "BRL",
              "value": "6000000"
            }
          },
          {
            "interestRate": "0.00",
            "installmentNum": "3",
            "interval": "MONTH",
            "minInstallmentAmount": {
              "currency": "BRL",
              "value": "500"
            },
            "enabled": true,
            "maxInstallmentAmount": {
              "currency": "BRL",
              "value": "6000000"
            }
          },
          {
            "installmentNum": "4",
            "interval": "MONTH",
            "minInstallmentAmount": {
              "currency": "BRL",
              "value": "500"
            },
            "enabled": true,
            "maxInstallmentAmount": {
              "currency": "BRL",
              "value": "6000000"
            }
          },
          {
            "installmentNum": "5",
            "interval": "MONTH",
            "minInstallmentAmount": {
              "currency": "BRL",
              "value": "500"
            },
            "enabled": true,
            "maxInstallmentAmount": {
              "currency": "BRL",
              "value": "6000000"
            }
          },
          {
            "installmentNum": "6",
            "interval": "MONTH",
            "minInstallmentAmount": {
              "currency": "BRL",
              "value": "500"
            },
            "enabled": true,
            "maxInstallmentAmount": {
              "currency": "BRL",
              "value": "6000000"
            }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "7",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "500"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "6000000"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "8",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "500"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "6000000"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "9",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "500"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "6000000"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "10",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "500"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "6000000"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "11",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "500"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "6000000"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "12",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "500"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "6000000"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "2",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "3",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "4",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "5",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "6",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "7",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "8",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "9",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "10",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "11",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          },
          {
          "interestRate": "0.00",
          "installmentNum": "12",
          "interval": "MONTH",
          "minInstallmentAmount": {
          "currency": "BRL",
          "value": "4000"
          },
          "enabled": true,
          "maxInstallmentAmount": {
          "currency": "BRL",
          "value": "999999999900"
          }
          }
        ],
          "supportCardBrands": [
          {
          "logo": {
          "logoName": "AMEX",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/7a0284b0-7577-493b-bc96-6809ec2f7f79.svg"
          },
          "cardBrand": "AMEX"
          },
          {
          "logo": {
          "logoName": "HIPERCARD",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/42079be8-2bdd-48a5-9da9-eb7e0917f349.svg"
          },
          "cardBrand": "HIPERCARD"
          },
          {
          "logo": {
          "logoName": "MASTERCARD",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/bc7cb991-c8e2-4379-945f-aadae2bdf932.svg"
          },
          "cardBrand": "MASTERCARD"
          },
          {
          "logo": {
          "logoName": "VISA",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/9/26/dfd471f3-da7d-4ef1-8486-cfa4301045c6.svg"
          },
          "cardBrand": "VISA"
          },
          {
          "logo": {
          "logoName": "ELO",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/b252dbb2-1da4-41a1-b796-21eea0d20d75.svg"
          },
          "cardBrand": "ELO"
          }
        ]
          },
          "paymentOptionDetail": {
          "funding": [
          "CREDIT"
        ],
          "supportCardBrands": [
          {
          "logo": {
          "logoName": "AMEX",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/7a0284b0-7577-493b-bc96-6809ec2f7f79.svg"
          },
          "cardBrand": "AMEX"
          },
          {
          "logo": {
          "logoName": "HIPERCARD",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/42079be8-2bdd-48a5-9da9-eb7e0917f349.svg"
          },
          "cardBrand": "HIPERCARD"
          },
          {
          "logo": {
          "logoName": "MASTERCARD",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/bc7cb991-c8e2-4379-945f-aadae2bdf932.svg"
          },
          "cardBrand": "MASTERCARD"
          },
          {
          "logo": {
          "logoName": "VISA",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/9/26/dfd471f3-da7d-4ef1-8486-cfa4301045c6.svg"
          },
          "cardBrand": "VISA"
          },
          {
          "logo": {
          "logoName": "ELO",
          "logoUrl": "https://cdn.marmot-cloud.com/storage/2022/8/2/b252dbb2-1da4-41a1-b796-21eea0d20d75.svg"
          },
          "cardBrand": "ELO"
          }
        ]
          },
          "logo": {
          "logoName": "Credit and Debit Card",
          "logoUrl": "https://gw.alipay.com/icon/medium/default/ALIPAY_GENERAL_CARD.svg"
          },
          "paymentMethodType": "CARD",
          "enabled": true
          },
          {
          "paymentMethodRegion": [
          "BR"
        ],
          "paymentMethodCategory": "CHECKOUT",
          "logo": {
          "logoName": "mercado pago",
          "logoUrl": "https://gw.alipay.com/antom/icon/medium/default/MercadoPagoCheckout.svg"
          },
          "paymentMethodType": "MERCADOPAGO_BR",
          "enabled": true
          },
          {
          "disableReason": "CURRENT_CHANNEL_NOT_EXIST",
          "paymentMethodRegion": [
          "CL"
        ],
          "paymentMethodCategory": "CHECKOUT",
          "logo": {
          "logoName": "mercado pago",
          "logoUrl": "https://gw.alipay.com/antom/icon/medium/default/MercadoPagoCheckout.svg"
          },
          "paymentMethodType": "MERCADOPAGO_CL",
          "enabled": false
          },
          {
          "disableReason": "CURRENT_CHANNEL_NOT_EXIST",
          "paymentMethodRegion": [
          "MX"
        ],
          "paymentMethodCategory": "CHECKOUT",
          "logo": {
          "logoName": "mercado pago",
          "logoUrl": "https://gw.alipay.com/antom/icon/medium/default/MercadoPagoCheckout.svg"
          },
          "paymentMethodType": "MERCADOPAGO_MX",
          "enabled": false
          },
          {
          "disableReason": "CURRENT_CHANNEL_NOT_EXIST",
          "paymentMethodRegion": [
          "PE"
        ],
          "paymentMethodCategory": "CHECKOUT",
          "logo": {
          "logoName": "mercado pago",
          "logoUrl": "https://gw.alipay.com/antom/icon/medium/default/MercadoPagoCheckout.svg"
          },
          "paymentMethodType": "MERCADOPAGO_PE",
          "enabled": false
          }
        ]
          }

获取分期营销信息

下表列出了免息分期的规则：

银行卡类型

分期能力

手续费收取方式

巴西卡

2-12期免息

不收取额外手续费。

韩国卡

免息规则每月更新

如非免息，买家在完成支付后可查看相应手续费。

表 5. 分期付款规则

您可以通过以下两种方式获取韩国银行卡的分期营销信息：

  • 通过官方网站查看免息分期信息，可以定期查看每月最新的免息分期营销信息 。
  • 调用 咨询 接口以获取支付方式支持的分期免息规则。返回的分期信息包括支持的银行卡品牌（bankName）， 营销活动有效期（expireTime）以及 支持的免息分期期数（installmentFreeNums）。

以下是 咨询 接口的代码示例：

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "paymentOptions": [
        {
            "paymentMethodRegion": [
                "KR"
            ],
            "paymentMethodCategory": "",
            "logo": {
                "logoName": "alipayHK",
                "logoUrl": "https://resourcecenter-v2-internet-site-dev-s29001109997.alipay.net/antom/icon/medium/default/pix.svg"
            },
            "paymentMethodType": "alipayHK",
            "enabled": true,
            "promotionInfos": [{
                "promotionType": "DISCOUNT",
                "discount": {
                  "promotionName": "Marketing copy in default language",
                  "promotionTag": "Instant discount",
                  "estimateSavingsAmount": {
                      "currency": "HKD",
                      "value": "500"
                  },
                  "cardInterestFree": null
                }
              },
              {
                "promotionType": "CARD_INTEREST_FREE",
                "discount": null,
                "cardInterestFree": {
                  "bankName": "HYUNDAI",
                  "expireTime": "2023-04-27T23:33:09-07:00",
                  "installmentFreeNums": [2,3,4],
                  "installmentInterval": "MONTH",
                  "supportCurrency": "KRW",
                  "minPaymentAmount": {
                      "currency": "KRW",
                      "value": "50000"
                  },
                  "maxPaymentAmount": {
                      "currency": "KRW",
                      "value": "9999999"
                  }
                }
              }
            ]
        },
        {
            "disableReason": "CURRENT_CHANNEL_NOT_EXIST",
            "paymentMethodRegion": [
                "HK",
                "TH",
                "KR",
                "PH",
                "ID",
                "CN",
                "MY"
            ],
            "logo": {
                "logoName": "Alipay+",
                "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/CONNECT_WALLET.png"
            },
            "paymentMethodType": "CONNECT_WALLET",
            "enabled": false
        }
    ]
}

发起分期付款

通过接口或 SDK 集成分期付款的关键点如下：

接口集成

如果买家选择分期付款方式，您需要在发起支付前收集相关分期信息，如分期数。然后在调用 支付（收银台）接口时，通过 creditPayPlan 对象传递分期信息。在 creditPayPlan 对象中，关键字段是 creditPayPlan.installmentNum，表示分期数。该字段的值范围为 2 到 12。

有关字段描述的更多信息，请参阅 支付（收银台）接口。

以下代码示例展示了调用 支付（收银台）接口时的分期付款请求：

copy
{
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "productCode": "CASHIER_PAYMENT",
    "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_online&paymentMethodType=CARD",
    "paymentRequestId": "amsdmpay_zy236564_20231016_100559_577",
    "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=amsdmpay_zy236564_20231016_100559_577",
    "paymentFactor": {
        "isAuthorization": true,
        "asyncPay": false,
        "captureMode": "MANUAL"
    },
    "paymentMethod": {
        "paymentMethodMetaData": {
            "cvv": "540",
            "cardholderName": {
                "firstName": "Tom",
                "lastName": "Jerry"
            },
            "expiryMonth": "01",
            "useStringType": false,
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Huanglong",
                "city": "Hangzhou",
                "address1": "Gongzhuan road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "expiryYear": "28",
            "cardNo": "4293380420642881"
        },
        "paymentMethodType": "CARD"
    },
    "creditPayPlan": {
        "installmentNum": 2
    },
    "enableInstallmentCollection":true,
    "paymentAmount": {
        "currency": "BRL",
        "value": "600"
    },
    "order": {
        "orderAmount": {
            "currency": "BRL",
            "value": "600"
        },
        "referenceOrderId": "amsdmorder_zy236564_20231016_100559_577",
        "goods": [
            {
                "referenceGoodsId": "amsdm_good_zy236564_20231016_100559_577",
                "goodsUrl": "HangZhou LeiFenTa",
                "goodsCategory": "card/ssr/adc",
                "goodsUnitAmount": {
                    "currency": "USD",
                    "value": "10000"
                },
                "goodsQuantity": "1",
                "goodsName": "Goods No.1",
                "goodsSkuName": "SKU1",
                "goodsBrand": "AMSDM"
            }
        ],
        "env": {
            "clientIp": "1.1.1.1",
            "osType": "IOS",
            "terminalType": "WEB"
        },
        "extendInfo": "{}",
        "orderDescription": "AMSDM_GIFT",
        "buyer": {
            "referenceBuyerId": "zy236564",
            "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
            "buyerName": {
                "firstName": "Dehua",
                "lastName": "Liu",
                "fullName": "Dehua Skr Liu",
                "middleName": "Skr"
            }
        }
    }
}

注意：如果不通过 creditPayPlan 字段指定分期信息，付款将默认为非分期付款。

SDK 集成

如果买家选择了分期付款方式，您可以自己收集分期信息，也可以将收集工作委托给 SDK。

如果您选择自主收集分期付款信息，那么在发起支付前，您需要从买家处收集相关详情，例如分期期数。然后，在调用 支付会话创建（收银台）接口时通过 creditPayPlan 字段传入分期付款信息。在 creditPayPlan 对象中，关键字段为 creditPayPlan.installmentNum，表示分期期数。此字段的取值范围是从2到12。

关于字段描述的更多信息，请参见 支付会话创建（收银台）接口。

当您自行收集分期付款信息时，您发起的支付请求的代码示例如下：

copy
{
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "productCode": "CASHIER_PAYMENT",
  "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_online&paymentMethodType=CARD",
  "paymentRequestId": "amsdmpay20231016_100927_794",
  "agreementInfo": {
    "authState": "amsdemo_authState_zy236564_20231016_100927_794"
  },
  "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=amsdmpay_zy236564_20231016_100927_794",
  "paymentFactor": {
    "isAuthorization": true,
    "asyncPay": false,
    "captureMode": "MANUAL"
  },
  "paymentMethod": {
    "paymentMethodType": "CARD"
  },
  "creditPayPlan": {
    "installmentNum": 2
  },
  "enableInstallmentCollection":true,
  "paymentAmount": {
    "currency": "BRL",
    "value": "6000"
  },
  "order": {
    "orderAmount": {
      "currency": "BRL",
      "value": "6000"
    },
    "referenceOrderId": "amsdmorder_zy236564_20231016_100927_794",
    "goods": [
      {
        "referenceGoodsId": "amsdm_good_zy236564_20231016_100927_794",
        "goodsUrl": "HangZhou LeiFenTa",
        "goodsCategory": "card/ssr/adc",
        "goodsUnitAmount": {
          "currency": "USD",
          "value": "10000"
        },
        "goodsQuantity": "1",
        "goodsName": "Goods No.1",
        "goodsSkuName": "SKU1",
        "goodsBrand": "AMSDM"
      }
    ],
    "env": {
      "clientIp": "1.1.1.1",
      "osType": "IOS",
      "terminalType": "WEB"
    },
    "extendInfo": "{}",
    "orderDescription": "AMSDM_GIFT",
    "buyer": {
      "referenceBuyerId": "zy236564",
      "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
      "buyerName": {
        "firstName": "Dehua",
        "lastName": "Liu",
        "fullName": "Dehua Skr Liu",
        "middleName": "Skr"
      }
    }
  }
}

3D 交易中提前收集设备和浏览器信息

在 3D 交易中提前收集设备和浏览器信息可以提高无摩擦 3D 安全认证的可能性，从而提高用户体验和支付成功率。

无论支付时使用哪种认证方法，都必须收集设备和浏览器信息。这个收集过程需要用户等待，可能会影响支付体验。通过此功能，用户在选择卡号后但在提交支付前会收集这些信息。这样就避免了用户在支付过程中等待，从而提升支付体验。

工作流程

卡支付特性流程2.png

集成指南

目前此功能仅适用于接口集成模式 且仅在以下场景之一中：

  • 作为商户，您自行收集银行卡信息。
  • 作为商户，您使用银行卡令牌来接受支付。

步骤 1：获取设备数据收集链接 服务端

在用户选择卡号但提交支付之前，调用 认证初始化 接口来获取设备数据收集链接。考虑到收集信息需要时间，建议在用户选择支付方式时进行收集。

以下是请求报文的示例代码：

copy
{
    "authenticationRequestId": "202401abcdefg_sda_202404287_yf_gogo_23",
    "identityType": "CARD_PAN",
    "paymentRedirectUrl": "http://www.merchantsite.com",
    "authenticationType": "THREEDS",
    "identityValue": {
      "cardBrand":"VISA",
      "cardBin": "412408",
      "cardClass": "D"
    }
}

请求体中使用的关键参数。

参数

描述

authenticationRequestId

用于与 认证初始化 和 支付 接口关联的请求 ID。

identityType

身份类型。有效值包括：

  • CARD_TOKEN：使用 Antom 提供的卡令牌进行支付。
  • CARD_NT：使用网络令牌进行支付。
  • CARD_PAN：通过收集卡号进行支付。

identityValue.cardToken

当 identityType 的值为CARD_TOKEN时，指定相应的令牌。

identityValue.cardBin

当 identityType 的值为CARD_NT或CARD_PAN时，指定卡号前六位（BIN）。

identityValue.cardBrand

当 identityType 的值为CARD_NT或CARD_PAN时，指定银行卡品牌。

identityValue.funding

当 identityType 的值为CARD_NT或CARD_PAN时，指定资金来源类型。

以下代码展示了响应报文的示例：

copy
{
    "authenticationId": "2024050716031241000190000162360",
    "authenticationRequestId": "202401abcdefg_sda_202404287_yf_gogo_24",
    "redirectActionForm": {
        "method": "POST",
        "parameters": "{\"ddcReferenceId\":\"af39d8b9-ff19-4013-a097-c54c8375efe2\",\"Bin\":\"412408\",\"JWT\":\"eyJraWQiOiJDQVJESU5BTF9KV1RfYWxpcGF5IiwiY3R5IjoiQ0FSRElOQUxfSldUX2FsaXBheSIsImFsZyI6IkhTMjU2In0.eyJPcmdVbml0SWQiOiI1ZDA5NDJmNmJiODc2ODE5NmMzMTYzYTciLCJSZWZlcmVuY2VJZCI6ImFmMzlkOGI5LWZmMTktNDAxMy1hMDk3LWM1NGM4Mzc1ZWZlMiIsIlJldHVyblVybCI6Im9wZW4tdGVzdC1kZS1ncm91cDIwMjQwNDE4MTQxNDEyLmRsLmFsaXBheWRldi5jb20vYXBpL29wZW4vdXJsX2NhbGxiYWNrX2dldC9jYXJkaW5hbC9jYXJkaW5hbDAwNy5odG0_c2lnbkRhdGE9UGJMendDMk9qYnJIRzNwJTJGOSUyRm1qV2ZCSE5WZmVObzRwJTJCR1NvV3JYNXJFZDY2T3RWVUI0VmNuaE1WcVdTQnZmR2NNdDRRV3pNbUFvek90UjgzRTlYNkVTZEpaRVdiQkQlMkZKS1ZjZHYlMkJpQlcxUHVmR0EzQWZtMGQ3M2lGWFZXNjlqT0ZzOTBqTCUyQm5qb0ZXQTRZWEklMkZ3UExwRVN3T2YlMkJscXhjbUNUVXlETFg2U3hJY0x3ZEF0Y2NZeG5oc0FaVmclMkZCMVFTdHl6diUyQk1sVEtXVUpzdmlYR0c4MDBFa3E5Q29YJTJGWjVNSnQlMkJZRG11WHBHZ0l6OUhKUmxrY0RxRGpySXUlMkY5VSUyRmpMa01VWWNoelJWYXNvdDZDY25uWG5FaktjSW1VeWw1ekxNdlE0Y2M1WGlPWElKdG5SdDdmNlZ3MnRacDNJWVVqMkM1Mld0bWh0JTJGejB4Z05abWlnJTNEJTNEJmluU2VyaWFsTm89MjAyNDA1MDcxNjAzMTM0MTAwMDE5MDAwMDE0NDU3MyZvdXRPcmRlck5vPTIwMjQwNTA3MTYwMzEzNDEwMDAxOTAwMDAxNDQ1NzMiLCJleHAiOjE3MTUwODE3MzgsImlhdCI6MTcxNTA4MDgzOCwiaXNzIjoiNWQwOTQ4MDlhZmE4MGQyMjUwMDQyODBkIiwianRpIjoiMjAyNDA1MDcxNjAzMTM0MTAwMDE5MDAwMDE0NDU3MyJ9.upNHVxubLYrAGzRWUhIM19v9kZ6yPyrR_JG4H54BWAU\"}",
        "redirectUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

响应体中使用的关键参数。

参数

描述

actionForm.redirectUrl

用于通过 POST 收集设备数据的链接。

actionForm.parameters.ddcReferenceId

支付方式 ID。

actionForm.parameters.JWT

密码。

actionForm.parameters.BIN

卡号前六位（BIN）。

步骤 2：收集设备数据 客户端

客户端开始访问上一步中 redirectUrl ，这是在 认证初始化 接口响应中返回的，通过发送 POST 请求实现。

以下是一个请求报文的示例：

copy
Request request = new Request();
request.setMethod("POST");
request.setParameters("{\"ddcReferenceId\":\"af39d8b9-ff19-4013-a097-c54c8375efe2\",\"Bin\":\"412408\",\"JWT\":\"eyJraWQiOiJDQVJESU5BTF9KV1RfYWxpcGF5IiwiY3R5IjoiQ0FSRElOQUxfSldUX2FsaXBheSIsImFsZyI6IkhTMjU2In0.eyJPcmdVbml0SWQiOiI1ZDA5NDJmNmJiODc2ODE5NmMzMTYzYTciLCJSZWZlcmVuY2VJZCI6ImFmMzlkOGI5LWZmMTktNDAxMy1hMDk3LWM1NGM4Mzc1ZWZlMiIsIlJldHVyblVybCI6Im9wZW4tdGVzdC1kZS1ncm91cDIwMjQwNDE4MTQxNDEyLmRsLmFsaXBheWRldi5jb20vYXBpL29wZW4vdXJsX2NhbGxiYWNrX2dldC9jYXJkaW5hbC9jYXJkaW5hbDAwNy5odG0_c2lnbkRhdGE9UGJMendDMk9qYnJIRzNwJTJGOSUyRm1qV2ZCSE5WZmVObzRwJTJCR1NvV3JYNXJFZDY2T3RWVUI0VmNuaE1WcVdTQnZmR2NNdDRRV3pNbUFvek90UjgzRTlYNkVTZEpaRVdiQkQlMkZKS1ZjZHYlMkJpQlcxUHVmR0EzQWZtMGQ3M2lGWFZXNjlqT0ZzOTBqTCUyQm5qb0ZXQTRZWEklMkZ3UExwRVN3T2YlMkJscXhjbUNUVXlETFg2U3hJY0x3ZEF0Y2NZeG5oc0FaVmclMkZCMVFTdHl6diUyQk1sVEtXVUpzdmlYR0c4MDBFa3E5Q29YJTJGWjVNSnQlMkJZRG11WHBHZ0l6OUhKUmxrY0RxRGpySXUlMkY5VSUyRmpMa01VWWNoelJWYXNvdDZDY25uWG5FaktjSW1VeWw1ekxNdlE0Y2M1WGlPWElKdG5SdDdmNlZ3MnRacDNJWVVqMkM1Mld0bWh0JTJGejB4Z05abWlnJTNEJTNEJmluU2VyaWFsTm89MjAyNDA1MDcxNjAzMTM0MTAwMDE5MDAwMDE0NDU3MyZvdXRPcmRlck5vPTIwMjQwNTA3MTYwMzEzNDEwMDAxOTAwMDAxNDQ1NzMiLCJleHAiOjE3MTUwODE3MzgsImlhdCI6MTcxNTA4MDgzOCwiaXNzIjoiNWQwOTQ4MDlhZmE4MGQyMjUwMDQyODBkIiwianRpIjoiMjAyNDA1MDcxNjAzMTM0MTAwMDE5MDAwMDE0NDU3MyJ9.upNHVxubLYrAGzRWUhIM19v9kZ6yPyrR_JG4H54BWAU\"}");
request.setRedirectUrl("https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect");
request.process();

为了提供更好的用户体验，建议您执行以下操作：

  • 通过 iframe 在当前页面生成一个像素点页面来加载信息收集链接，提供无缝且优化的支付体验。
  • 将收集过程延长至两秒以上，以获取更多信息。

步骤 3：收集浏览器信息 客户端

下表显示了信息收集的关键参数：

参数

描述

colorDepth

买家的浏览器色彩深度，以每像素位数表示。此信息需要通过浏览器的 screen.colorDepth 属性获取。接受的值：1，4， 8， 15， 16， 24， 30， 32 或 48 位色彩深度。

screenHeight

买家设备屏幕的总高度，以像素为单位。

screenWidth

买家设备屏幕的总宽度，以像素为单位。

timeZoneOffset

UTC 时间与买家浏览器本地时间之间的时差，以分钟为单位。

acceptHeader

买家的浏览器的 Accept 头值。

javaEnabled

表示买家的浏览器是否能够执行 Java 的布尔值。

javaScriptEnabled

表示买家的浏览器是否能够执行 JavaScript 的布尔值。如果字段未出现，则默认为true。

language

买家浏览器的 navigator.language 值（IETF BCP 47中定义）。

userAgent

买家浏览器的用户代理值。

步骤4：发起支付 服务端

指定在 initializeAuthentication.request.authenticationRequestId 字段，将其与步骤 1 关联，然后提供 9 项浏览器信息 。

以下代码展示了请求报文的示例：

copy
{
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "productCode": "CASHIER_PAYMENT",
    "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_dev&paymentMethodType=CARD",
    "paymentRequestId": "amsdmpay_yanfei_wzh_20240428_191505_xx_022",
    "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=amsdmpay_yanfei_wzh_20240111_191505_666",
    "paymentFactor": {
        "isAuthorization": true
    },
    "paymentMethod": {
        "paymentMethodMetaData": {
            "authenticationRequestId":"2024051419401080010018896022321932",
            "identityType": "CARD_PAN",
            "cvv": "682",
            "cardholderName": {
                "firstName": "Tom",
                "lastName": "Jerry"
            },
            "expiryMonth": "11",
            "expiryYear": "28",
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Huanglong",
                "city": "Hangzhou",
                "address1": "Gongzhuan road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "cardNo": "4124085486814126"
        },
        "paymentMethodType": "CARD"
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "7000"
    },
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "7000"
        },
        "referenceOrderId": "amsdmorder_yanfei_wzh_20240111_191505_666",
        "goods": [
            {
                "referenceGoodsId": "amsdm_good_yanfei_wzh_20240111_191505_666",
                "goodsUrl": "HangZhou LeiFenTa",
                "goodsCategory": "card/ssr/adc",
                "goodsUnitAmount": {
                    "currency": "USD",
                    "value": "10000"
                },
                "goodsQuantity": "1",
                "goodsName": "Goods No.1",
                "goodsSkuName": "SKU1",
                "goodsBrand": "AMSDM"
            }
        ],
        "env": {
            "clientIp": "1.1.1.1",
            "terminalType": "WEB",
            "osType": "IOS",
            "browserInfo": {
                "acceptHeader": "AcceptHeaded111",
                "javaEnabled": true,
                "javaScriptEnabled": false,
                "language": "EN",
                "userAgent": "agentagentagentagentagent"
            },
            "colorDepth":"12",
            "screenHeight":"50",
            "screenWidth":"50",
            "timeZoneOffset":"8"
    },
        "orderDescription": "AMSDM_GIFT",
        "buyer": {
            "referenceBuyerId": "yanfei.wzh",
            "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
            "buyerName": {
                "firstName": "Dehua",
                "lastName": "Liu",
                "fullName": "Dehua Skr Liu",
                "middleName": "Skr"
            }
        }
    }
}

请求体中使用的关键参数。

参数

描述

paymentMethod.paymentMethodMateData.authenticationRequestId

用于与步骤 1 关联的请求 ID。

pay.env.browserInfo

浏览器信息。

pay.env.colorDepth

颜色深度。

pay.env.screenHeight

屏幕高度。

pay.env.screenWidth

屏幕宽度。

pay.env.timeZoneOffset

时区偏移量。

以下代码展示了响应报文的示例：

copy
{
    "normalUrl": "https://iopensandbox-sea.alipay.com/xmock.json?xmockUrl=/api/Shadow/Channel/CHECKOUT/threeDS.htm/20240514890313000045C6835316965/false",
    "paymentActionForm": "{\"method\":\"POST\",\"paymentActionFormType\":\"RedirectActionForm\",\"redirectUrl\":\"https://iopensandbox-sea.alipay.com/xmock.json?xmockUrl=/api/Shadow/Channel/CHECKOUT/threeDS.htm/20240514890313000045C6835316965/false\"}",
    "paymentAmount": {
        "currency": "EUR",
        "value": "30000"
    },
    "paymentCreateTime": "2024-05-14T01:47:22-07:00",
    "paymentId": "202405141940108001001885C0204760163",
    "paymentRequestId": "PAY_2023154767445445328",
    "paymentResultInfo": {
        "avsResultRaw": "",
        "cardBrand": "VISA",
        "cardNo": "************8888",
        "cvvResultRaw": "",
        "networkTransactionId": "20240514890313000045C6835316965",
        "threeDSResult": {
            "cavv": "",
            "eci": ""
        }
    },
    "redirectActionForm": {
        "method": "POST",
        "redirectUrl": "https://iopensandbox-sea.alipay.com/xmock.json?xmockUrl=/api/Shadow/Channel/CHECKOUT/threeDS.htm/20240514890313000045C6835316965/false"
    },
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process",
        "resultStatus": "U"
    }
}

注意：提前收集设备数据和浏览器信息可以提高 3D Secure 无摩擦认证的可能性，但并不能确保生成的 3D Secure 链接始终无摩擦。用户仍有可能需要进行 3D Secure 认证。

适用范围

  • 适用模式：通过接口集成。
  • 适用地区：欧洲、英国、新加坡、香港、巴西、秘鲁、墨西哥和智利。