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

Omnichannel integration solution

Note: Translation in progress.

这套方案适合于大型跨国公司在多个国家展业，业务场景包括线上支付与线下支付场景。通过一套方案解决客户在各种场景中的全部收单业务诉求。

适合的业务场景

1751440692777-cf7faf2b-050c-4059-8857-0aa0334b02c4.png

角色如下

  • 品牌方（T1）：多国展业的跨国公司，其与 Antom 做系统集成对接
  • 加盟商（T2）：其身份可以是加盟商、子公司、分公司等，其与 Antom 签约、结算主体 （与品牌方关系 1:n）
  • 门店（T3）：加盟商或者子公司开设的线下门店（与加盟商关系 1:n）
    • 收银机具：门店中具有独立下单功能的设备，可以是 Terminal POS、Kiosk 等 （与门店关系 1:n）
    • H5/APP： 属于品牌方为加盟商门店提供的线上下单支付手段（1）

一个跨国公司/品牌公司在多个国家展业，公司在本地有多个加盟商/子公司/分公司等业务实体。而在地的业务实体有 1～n 家门店。门店中有线上与线下支付场景。

提示:

  • “跨国公司/品牌公司” 技术团队与 Antom 做系统集成 （AKA 总对总合作）
  • “加盟商/子公司/分公司等业务实体” 和 Antom 签收单结算合约 ，交易结算到每个在地业务实体的银行账号。

角色在 API 中的关联

这里涉及5个角色需要在支付API中明确其身份：

角色身份

API 中对应的字段

长度限制

对账单中对应的字段

数量

如何产生

品牌方（T1）

client-id

（http hearder）

64

无

1

注册后分配（不同国家入驻后分配不同的client_id）

加盟商（T2）

无

64

customerId

1～n

注册后分配的 Antom merchant ID

order # merchant # referenceMerchantId

64

referenceMerchantId

1～n

由客户方定义的 merchant ID，报备时提供给Antom。（对应关系需要商户维护）

agent-token

（http hearder）

64

无

1～n

注册后分配的 Antom merchant token 集成信息。

门店（T3）

order # merchant # store # referenceStoreId

64

referenceStoreId

1～n

由客户方定义，报备时提供给 Antom。（对应关系需要商户维护）

机具

order # merchant # store # storeTerminalId

64

无

1～n

由客户方定义，报备时提供给 Antom。（对应关系需要商户维护）

H5/APP

env # terminalType

WEB/WAP/APP

无

1

由客户方开发时设置

应用场景

线上收单场景

包括有手机端的 H5 支付、APP 支付、PC 浏览器的支付

用户体验：

  1. H5/APP/PC 中选择支付方式后下单
  2. 跳转到支付方式也处理页面
  3. 支持的支付中确认支付
  4. 跳转回 H5/APP/PC 商户页面

提示：支付的支付方式请和 Antom 业务团队确认。

线下收单场景

包括 Kiosk 等设备上的展码支付、POS 设备的卡收单支付

用户体验1：（展码支付）

  1. 用户选择支付方式后下单
  2. 从 Antom 得到 QR Code （图片、链接等）
  3. 在用户可见屏幕上展示 QR Code
  4. 用户用相对应的支付 APP 扫此 QR Code

提示：只要是有屏幕显示的设备都可以支持，比如 Kiosk、双屏显示 POS 机、有屏幕的 Terminal 等。

用户体验2：（卡支付）

  1. 用户选择卡支付
  2. 从 POS 上下单或者在 terminal 上下单
  3. 用户在相应设备上刷卡完成支付

提示：支持设备列表请和 Antom 业务团队确认。

线上支付场景集成

支付流程

线上各类支付方式的支付流程由以下集成步骤组成：

Omnichannel flow.png

支付集成

开始集成，请按照以下步骤操作：

  1. 了解如何调用 Antom 接口
  2. 创建支付订单
  3. 获取跳转支付推进链接
  4. 获取支付结果

步骤 1: 了解如何调用 Antom 接口

为了和 Antom 服务器通信，请先阅读下面几篇文档了解如何调用 Antom 接口

步骤 2: 创建支付订单

调用 pay（单笔支付）接口，您需要收集买家的支付方式、订单信息、设备信息、支付金额等提交支付请求。

支付请求包含以下关键参数。

参数名称

是否必需

描述

referenceMerchantId

是

由客户方定义的 merchant ID，报备时提供给 Antom。

（对应关系需要商户维护）

agent-token

是

注册后分配的 Antom merchant Token 集成信息。用以指明为哪一个商户收款

referenceStoreId

是

由客户方定义，报备时提供给 Antom。（对应关系需要商户维护）

storeTerminalId

是

线下场景必传，由客户方定义，报备时提供给 Antom。（对应关系需要商户维护）

productCode

是

在此场景中，该字段设置为 CASHIER_PAYMENT。

transBusinessScene

是

用于指定支付场景。有效值为：

  • ONLINE：由线上系统生成订单，在个人设备上支付。
  • OFFLINE：由 POS 机生成二维码，需要买家现场扫码支付。

paymentRequestId

是

商户生成的专属 ID。

paymentAmount

是

支付金额，以支付货币的最小单位设置。

paymentMethod

是

支付方式枚举值。

paymentRedirectUrl

是

商户端支付结果页，需根据服务端结果展示，非固定为成功页。

paymentNotifyUrl

否

支付结果通知地址，可通过接口指定或在门户上设置固定值。

settlementStrategy

是

支付请求的结算策略。如果您签署了多个结算货币，需要在接口中指定。

order

是

包括订单金额、订单 ID 和订单描述的订单信息。

env.terminalType

是

买家发起交易的环境：

  • WEB：客户端终端类型为网站，通过 PC 浏览器打开。
  • WAP：客户端终端类型为 H5 页面，通过移动浏览器打开。
  • APP：客户端终端类型为移动应用。

env.osType

否

买家发起交易的环境。当在商户手机浏览器网站发起，则 env.osType = ANDROID 或者 IOS。

注意：建议您传入环境信息以提升支付成功率。

有关完整参数的更多信息，请参阅 pay（单笔支付）接口。

以下是调用 pay（单笔支付）接口的示例代码：

copy
{
  "transBusinessScene" : "ONLINE", // 支付场景（线上/线下）
  "env": {
    "osType": "ANDROID",
    "terminalType": "WAP", // 支付环境
  },
  "order": {
    "merchant": {
      "referenceMerchantId": "SM_001", // 加盟商
      "store" : {
        "referenceStoreId" : "store_01", // 加盟商门店
        "storeTerminalId" : "001" // 加盟商门店中的支付机具（线上场景不传）
      },   
    },
    "orderAmount": {
      "currency": "CNY",
      "value": "1314"
    },
    "orderDescription": "Cappuccino #grande (Mac's coffee shop)",
    "referenceOrderId": "ORDER_0656237919440XXXX"
  },
  "paymentAmount": {
    "currency": "CNY",
    "value": "1314"
  },
  "paymentMethod": {
    "paymentMethodType": "ALIPAY_CN"
  },
  "paymentNotifyUrl": "https://www.gaga.com/notify",
  "paymentRedirectUrl": "imeituan://",
  "paymentRequestId": "Mbu1XMcI8TsH6oIVbioGeyvXA544N9UTIeHJ0YMTLYhRomPU0n7Je2cp3kiCADbp",
  "productCode": "CASHIER_PAYMENT",
  "settlementStrategy": {
    "settlementCurrency": "USD"
  }
}

从支付接口返回值中可以获取跳转支付推进的链接。

响应代码中涉及以下关键参数。

参数名称

描述

result.resultStatus

指  pay（单笔支付）接口的调用状态。

normalUrl

将买家跳转到默认浏览器或嵌入式 WebView 中的 WAP 或 WEB 页面的链接。

applinkUrl

将买家跳转到已安装的目标应用中，或未安装目标应用的 WAP 页面中的链接。

schemeUrl

在 Android 或 iOS 系统中，应用安装完成后，将买家跳转到应用的 URL scheme。

下表展示了响应代码中 result.resultStatus 字段可能返回的值，请您根据指引进行处理：

result.resultStatus

信息

后续操作

S

支付成功。

无需进一步操作。

F

支付失败。

关闭当前交易订单或重新更换 paymentRequestId 后再次发起支付请求。

U

未知原因。

  • 若返回 PAYMENT_IN_PROCESS 结果码，获取任意一个链接 (applinkUrl/normalUrl/schemeUrl) 并打开收银页面。
  • 若返回其他结果码，关闭当前交易订单或重新更换 paymentRequestId 后再次发起支付请求。

注意：如果您未收到响应报文，可能是网络超时所致。关闭当前交易订单或重新更换 paymentRequestId 后再次发起支付请求。

常见问题

问：如何确认响应代码中需要消费的 URL 类型？

答：不同支付方式在不同端类型下，Antom 可能会返回以下三种 URL 中的一种或多种：normalUrl、applinkUrl 和 schemeUrl。商户服务端需将这些 URL 传递给商户前端，可以选择任选一种 URL 进行跳转消费。更多信息请参阅

如何正确使用支付推进链接。

 

问：什么是 paymentId？

答：如果您需要存储相应的订单 ID 以备后续退款和对账，可以指定 paymentId。

 

问：如何设置 terminalType？

答：terminalType 的有效值为：

  • 如果买家在 PC 端发起交易，需要将 terminalType 指定为 WEB。
  • 如果买家在移动浏览器上发起交易，需要将 terminalType 指定为 WAP。添加 osType 参数，并根据买家的手机填写相应的系统参数 ANDROID 或 IOS。
  • 如果买家在应用内发起交易，需要将 terminalType 指定为 APP。

步骤 3: 获取跳转支付推进链接

商户服务端拿到 Antom 返回的支付推进链接后，将该地址传递给前端，由商户前端跳转至支付方式页面。不同类型的支付推进链接如下表所示：

类型

描述

示例 URL

normalUrl

一个 HTTPS 地址的链接，用于在同一浏览器页面上重定向到支付方式的网站页面。

URL=serverResponse.normal

applinkUrl

在支付过程中用于重定向的 Android App Link 或 iOS Universal Link。

URL=serverResponse.applink

schemeUrl

用于打开支付方式应用的 URL scheme。

URL=serverResponse.scheme

请参阅支付推进链接了解更多内容。

copy
if (URL != null) {
    window.open(URL, '_blank');
}

下图展示支付方式收银台页面的效果：

4.webp

不同支付方式在不同终端会返回不同的支付推进链接，Antom 基于您传入的 paymentMethod 和 terminalType 决策返回不同的支付推进链接。下表列举了不同终端返回的支付推进链接类型及其用户体验。关于具体的不同支付方式返回的支付推进链接内容，请参阅支付方式返回链接了解更多详情。

支付推进链接类型

功能

用户体验

applinkUrl

  • 买家已安装支付方式应用程序时可拉起应用程序。
  • 买家未安装支付方式应用程序时可拉起浏览器 H5 页面。
  • 可以自动判断买家是否安装支付方式应用程序。
  • 一般在买家从商户应用程序或手机网站发起支付时会返回该 URL，具体依赖于支付方式是否支持。
  • 买家已安装支付方式应用程序：

5.webp

  • 买家未安装支付方式应用程序：

6.webp

schemeUrl

  • 通过支付方式应用程序的 scheme 直接拉起应用程序。
  • 买家未安装支付方式应用程序时无法拉起且会显示异常，请参阅最佳实践了解更多详情。
  • 一般在买家从商户应用程序或手机网站发起支付时会返回该 URL，具体依赖于支付方式是否支持。
  • 买家已安装支付方式应用程序：

7.webp

  • 买家未安装支付方式应用程序：不支持

normalUrl

  • 支付方式的 H5 页面。
  • 不同支付方式的 H5 页面体验不同，部分支付方式支持登录后直接支付，还有部分支付方式需要中间页拉起支付方式应用程序后进行支付。
  • 买家从商户 Web 端发起支付时，均返回此 URL，具体依赖于支付方式是否支持。
  • Web 端支付：

8.webp

  • H5 页面支付：

9.webp

  • 中间页拉起支付方式应用程序：

10.webp

您在 pay（单笔支付）接口中指定的 paymentRedirectUrl 字段提供了一个 HTTPS 地址，该地址用于在商户端页面显示支付结果。以下为您的支付结果页面示例：

11.webp

常见问题

问：如何处理不同的支付体验？

答：您无需处理不同支付方式的不同体验，只需通过前端页面重定向到 normalUrl。不同的支付体验由 normalUrl 负责完成渲染和支付流程。

   

问：如何展示支付结果页内容？

答：在支付成功和失败的情况下，可能都有入口可以从支付方式端回跳到商户页面。为避免引起误解，请以服务端返回的结果为准，不要将 paymentRedirectUrl 固定为“支付成功页面”。如果从 App 端发起交易，paymentRedirectUrl 需设置为商户应用程序的 scheme 地址。

   

问：回跳至商户结果页面是否代表支付成功？

答：不能仅凭回跳至商户页面来判断支付是否成功，可能存在以下情况导致回跳商户页失败：

  • 买家支付成功后，可能因网络等原因导致未能回跳至商户页面。
  • 当买家未完成支付时，也可能通过支付方式端的入口回跳至商户页面。
  • Antom 不会在 paymentRedirectUrl 拼接表示支付结果的字段信息。

步骤 4: 获取支付结果

当买家完成支付或支付超时，您可以通过 Antom 异步通知或主动查询支付结果来获取相应的支付结果。

从异步通知和 inquiryPayment 获取的响应包含授权支付结果以及其它关键信息，例如：

接口

授权结果

AVS 信息

CVV 信息

3DS 身份验证信息

notifyPayment

resultStatus

avsResultRaw

cvvResultRaw

threeDSResult（仅 3DS 身份验证授权时可用）

inquiryPayment

paymentStatus

avsResultRaw

cvvResultRaw

threeDSResult（仅 3DS 身份验证授权时可用）

接收异步通知

完成支付或支付失败时，Antom 会通过 pay（单笔支付）接口中的参数 paymentNotifyUrl 指定的地址发送异步通知（notifyPayment）。

  1. 您可以选择以下两种方法中的一种来设置接收通知的地址：
    • 若您的每个订单都有单独的通知 URL，建议在每笔请求中设置通知 URL。您可以通过 pay（单笔支付）接口请求的 paymentNotifyUrl 字段中传入该笔订单的异步通知接收地址。
    • 若您的所有订单有统一的通知 URL，您可以在 Antom Dashboard > 开发者 > 通知地址 中设置通知 URL。具体操作请参阅通知地址。

支付通知中涉及以下关键参数：

参数名称

是否必需

描述

resultStatus

是

表示订单支付结果的状态。

paymentRequestId

是

商户发起支付的唯一 ID。

paymentAmount

是

表示支付金额。

有关完整参数的更多信息，请参阅 notifyPayment。

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

copy
{
  "notifyType": "PAYMENT_RESULT",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentRequestId": "2020010123456789XXXX",
  "paymentId": "2020010123456789XXXX",
  "paymentAmount": {
    "value": "8000",
    "currency": "EUR"
  },
  "paymentCreateTime": "2020-01-01T12:01:00+08:30",
  "paymentTime": "2020-01-01T12:01:01+08:30"
}

下表展示了支付结果的异步通知中 result.resultStatus 字段可能返回的值，请您根据指引进行处理：

result.resultStatus

信息

后续操作

S

支付成功。

可从中获取以下字段信息：

  • paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。

F

支付失败。

关闭当前交易订单或更换 paymentRequestId 后再次发起支付请求。

完成支付或支付失败时，商户的服务端都会收到异步通知。但当部分失败场景（如参数异常）时，pay（单笔支付） 接口会同步返回 F，Antom 不会发送异步通知，您可根据返回的 F 状态直接关闭订单。

当您收到 Antom 的异步通知，需要您在返回中按照示例代码格式返回响应，但无需做加签处理。

查询支付结果

Antom 提供发送异步通知的功能，同时也支持主动查询支付结果。调用 inquiryPayment 接口，通过以下参数查询支付结果：

参数名称

是否必需

描述

paymentRequestId

否

商户生成的支付请求 ID。

有关完整参数的更多信息，请参阅 inquiryPayment 接口。

以下为调用 inquiryPayment 接口的代码示例：

copy
public static void inquiryPayment() {
    AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

    // 替换您的 paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // 处理错误情况
    }
}

以下为请求示例：

copy
{
    "paymentRequestId": "REQUEST_20250327164938236"
}

以下为响应的代码示例：

copy
{
  "actualPaymentAmount": {
    "currency": "THB",
    "value": "299"
  },
  "paymentAmount": {
    "currency": "THB",
    "value": "299"
  },
  "paymentId": "20250217194010800100188760278262487",
  "paymentMethodType": "TRUEMONEY",
  "paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
  "paymentRequestId": "3IOS47F3C9B7D96",
  "paymentResultCode": "SUCCESS",
  "paymentResultMessage": "success.",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2025-02-17T08:06:43-08:00",
  "pspCustomerInfo": {
    "pspName": "TRUEMONEY"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

请根据响应中的 paymentStatus 字段进行处理：

paymentStatus

描述

后续操作

SUCCESS

支付成功。

无需后续操作。

FAIL

支付失败。

关闭订单或更换 paymentRequestId 再次发起请求。

PROCESSING

支付进行中。

建议等待一段时间后继续查询状态或关闭订单再重新查询。

常见问题

问：调用 支付结果查询 接口时应该消费哪些字段？

答：请注意以下关键参数：

  • result：表示本次 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：
    • SUCCESS 和 FAIL 表示最终结果。
    • PROCESSING 表示处理中。
  • paymentAmount：表示支付的金额。

   

问：发起查询的推荐间隔是多久？

答：推荐以轮询的形式调用 支付结果查询 接口，间隔 2 秒，直到获取最终的支付结果或收到异步支付结果通知为止。

支付后操作

以下内容将介绍支付后如何通过服务端发起交易取消以及退款操作的具体方法，帮助您实现稳定可靠的支付管理体验。

取消交易 服务端

对于支付成功后的订单，如果买家在当天内申请取消订单或退款，您可以通过 Antom 提供的取消支付能力将订单状态取消或解冻。此外，对于尚未完成支付的订单，您也可以直接进行取消。请参阅取消交易了解关于取消支付集成方案的更多内容。

退款 服务端

在支付成功后，您可以通过以下两种方法发起退款：

Antom 支持的退款能力如下：

  • 支持全额退款。
  • 支持部分多次退款，多次退款的总金额需小于等于请款金额。

请参阅退款了解关于退款集成方案的更多内容。

支付方式特性

本部分内容旨在系统阐述各类支付方式在支持特性方面的差异，具体内容涵盖以下几个方面：

取消交易能力

不同支付方式的取消交易窗口期有差异，请参阅取消交易了解详情。

退款能力

不同支付方式的退款能力不同，主要为能否支持退款和支持退款的周期。请参阅支持的支付方式，了解更多关于退款能力的内容。

默认关单时间

以下为不同支付方式支持的默认关单时间。

支付方式

默认关单时间

QRIS, PayPay

5 分钟

Alipay, AlipayHK, DANA, Kredivo, ShopeePay, Boost, Bancontact, Pix, Pagaleve, OVO, JKOPay, GoPay, Touch'n Go eWallet, Grabpay, FPX, iDEAL, BPI, GCash, BillEase, Maya, UnionBank, PayU, P24, BLIK, PayNow, Kakao Pay, NAVER Pay, Toss Pay, Express Bank Transfer, LINE Pay, TrueMoney, KrungThai Bank, Siam Commercial Bank, Bangkok Bank, Bank of Ayudhya, Kbank, Promptpay, K PLUS, ZaloPay, MoMo

14 分钟

BANCOMAT Pay

1 小时

Maybank, BNI, Permata, CIMB Niaga VA, BSI, ATM Bersama/Prima/Alto, KrungThai Bank, Siam Commercial Bank, Bangkok Bank, Bank of Ayudhya, Kbank, Government Savings Bank

48 小时

Mercado Pago, Card, Konbini, Konbini (7-Eleven), Pay-easy, Pay by Bank

7 天

请参阅支付方式库，了解更多关于支付方式支持的关单详情。

集成特性

以下为不同支付方式的集成特性及建议方案。

支付方式

特性

建议方案

PayPay

  • 对 paymentRedirectUrl 字段有长度限制。
  • 退款次数不能超过 20 次。

paymentRedirectUrl 字段长度不要超过 255 字符。

QRIS

存在单边账情况。

为支付方式接入反转。

PromptPay

存在单边账情况。

为支付方式接入反转。

Maybank

支付完成后，会延迟 5 分钟发送异步通知。

为买家展示订单确认中的状态提示。

OVO/Pix/BANCOMAT Pay

无法自动拉起钱包。

需手动拉起钱包完成支付。

Siam Commercial Bank

  • 支付有手续费。
  • 不支持 PC 端。

提示买家可能存在支付手续费（由买家在银行的等级决策收取的费用金额）。

Bank of Ayudhya

  • 支付有手续费。
  • 不支持 PC 端。

提示买家可能存在支付手续费（由买家在银行的等级决策收取的费用金额）。

GoPay/Bangkok Bank/KrungThai Bank

不支持 PC 端。

无

NAVER Pay

PC 客户端需额外集成：买家登录后，支付不会在原页面直接完成，而是自动打开一个新的标签页重定向。

开启浏览器弹窗权限，并在代码中通过创建新的 browser 对象（或窗口）打开弹窗页面进行支付处理。

Mercado Pago (BR)

会消费 buyerEmail 字段从而导致支付直接失败。

传入 payerEmail 字段。

参考材料