支付（收银台）
支付方式
如何添加 Alipay、AlipayHK 等支付方式？
请联系 Antom 业务运营团队。
支付方式可以同时接入多个支付方式，例如 Alipay、AlipayHK 等支付方式吗？
可以，只要和 Antom 签署了对应支付方式的合约，都可以接入该支付方式。
用户同时拥有本地支付方式和其他的国外支付方式，是否都支持支付？
这取决于您的展业情况以及该支付方式支持的能力。例如，支付方式 Alipay 在跨境交易场景下，海外用户不能用非大陆实名认证的Alipay 进行支付。
可以为用户提供多个支付币种选项吗？
这取决于支付方式是否支持多个币种。若支付方式支持多币种支付，那支付页面可以根据您的业务需求为用户展示多个币种选项。若支付方式不支持，那支付页面仅展示一个币种选项。
目前支付方式返回的 URL 类型会有变更吗？
一般情况下不会有变更，若后续有改动 Antom 会提前通知。请参阅支付方式返回链接了解更多 URL 类型信息。
卡支付场景下，首次支付和后续支付有哪些卡要素是必传呢？
请参阅卡的特殊支付要素了解更多信息。
支付方式中的游戏和充值的区别是什么？
- 游戏：指直接售卖游戏的商户，比如：用户购买游戏使用权、皮肤和道具。
- 充值：指直接充值类的商户，比如：购买虚拟币等，在支付方式侧就是充值。
建议联系业务运营团队确认具体的商户类型。
第三方的支付方式页面是否支持多语言配置？
这取决于各支付方式的支持能力。若支付方式能力较强，则支持用户切换多语言，但目前不支持由商户控制多语言设置。Antom 会优先获取浏览器的语言，和内部支持的语言做匹配。如果无法匹配，默认显示英文。
如何获取各支付方式的客服联系链接和 FAQ？
通常可以在各支付方式的应用内或官方网站上获取，建议您直接访问相关支付方式的官方网站或在应用内查找客服支持和帮助中心。如果遇到支付相关问题，请联系 Antom 技术支持。
支付失败等相关错误信息会显示在哪些页面呢？
Antom 页面（含支付方式页面）会提示错误信息，但依赖于支付方式的能力，部分支付方式可能不支持此功能。建议商户侧根据返回的错误码做提示，比如：提示支付异常和失败，引导用户重新购买或者充值。
如何为用户设置取消支付的机制呢？
根据各支付方式的能力不同会有差异。有些支付方式支持用户在支付方式侧取消，有些则不支持。您可以在商户侧设置取消按钮，在用户点击取消按钮以后，再调用 取消支付 接口。
手动请款和自动请款有什么区别？
手动请款需要您调用 请款 接口来发起请款请求，自动请款是 Antom 发起请款请求。通常情况下，自动请款会在买家完成授权支付后3s 左右完成。若遇到系统异常，可能存在延迟。请注意，只有在用户授权成功以后才能发起请款请求。请参阅请款了解更多信息。
集成
商户端是否需要集成客户端 SDK？
Antom 目前支持 API 和 SDK 两种方式，您可以根据您的业务情况接入。
用户是否需要完成 KYC 认证呢？
这取决于各支付方式的能力。例如：在 AlipayHK 场景，需要用户先完成 KYC 认证。
CVC 校验是必须的吗？
Antom 支持 CVC 校验，但这不是必传字段。对于国际卡，建议您在首次支付或非 COF 场景下传入 CVC 字段，如果商户侧有其他需要验证卡的场景也可以传入。传入后，Antom 会传给卡组进行校验。目前仅国际卡支持 CVC 检查，本地卡依据各支付方式能力决定。
3D 验证是必须的吗？
Antom 支持3D验证。若未购买 Antom 增值风控，您可以自己决策是否需要进行 3D 校验，但是否支持 3D 取决于发卡行的能力。若您购买了 Antom 增值风控，Antom 会决策是否进行 3D 校验，但是否支持 3D 同样取决于发卡行的能力。目前仅国际卡支持 3D 校验，本地卡依据各支付方式能力决定。您可以通过 is3DSAuthentication 字段设置，请参阅卡支付特性了解更多信息。
是否支持外部 MPI？
支持。请参阅 MPI 了解更多信息。
客户端是否支持 Flutter、React Native、Weex、Uniapp等第三方框架？
除了原生场景，Antom 暂时不支持其他框架。
遇到 SDK_CREATEPAYMENT_PARAMETER_ERROR 时该怎么办？
收到此事件代码时，请检查传递的 sessionData 是否正确且完整。
遇到 SDK_PAYMENT_ERROR 或渲染视图错误时该怎么办？
检查接口初始化时的网络请求是否出现异常，如网络超时。确保创建支付会话请求的环境与 SDK 实例化时的环境一致。检查 支付会话创建（收银台）接口中的参数传递是否正确。如果接口异常持续存在，请联系我们进行进一步的故障排除。
卡支付场景下，如果用户支付成功，我们在客户端是否一定能收到SDK_PAYMENT_SUCCESSFUL 事件码？
因用户网络原因或者关闭页面，即使用户支付成功，也不一定能够百分百收到事件码，需要以服务端状态推进订单状态。
中间页跳转
什么是 normalUrl ？
对于 Web 或 WAP 交易，Antom 会返回 normalUrl，服务器端需要将其传递给客户端进行重定向。当您再次为同一订单发起支付时，需要获取新的 normalUrl 进行重定向。
WAP 场景下，同时返回 normalUrl 和 applinkUrl 时，应该如何选择？
一般有 applinkUrl 返回时，如果您没有要求每次支付都要回跳至商户页面，建议选择 applinkUrl。
哪些支付方式会返回 applinkUrl？
只有当您在 terminalType 字段中传入 WAP 或者 APP 时会返回 applinkUrl。不同的支付方式会返回不同的 URL，请参阅支付方式返回链接获取对应支付方式返回的URL。
Kakao Pay 的 Web 端二维码和跳转 App 端支付流程，都是通过返回 URL 的形式实现吗？
是的。
收到 applinkUrl 后，需要判断用户是否下载过支付方式应用吗？
不需要判断。applinkUrl 通常有降级能力，例如：GCash 支持未安装支付方式应用时使用账密支付，Kakao Pay 会引导用户下载应用。
Web 端是使用跳转第三方收银台的方式来实现吗？
是的。
用户在商户侧应用点击支付按钮跳转至 Kakao Pay的应用时，是 webView 还是手机浏览器跳转？
调用 支付（收银台）接口后会返回 applinkUrl，这可以实现从商户侧应用到支付方式应用的端到端跳转，跳转过程中不会有中间页。applinkUrl 通常有降级能力，当用户没有安装支付方式应用时，会拉起手机浏览器跳转到降级页面。
APM 支付是否支持自动或点击按钮跳转至商户收银台？
大部分支付方式都支持回跳，目前 Pay-easy、Konbini 和 Konbini (7-Eleven) 不支持回跳。此外，从商户 WAP 端拉起支付方式应用后，不一定能够100%回跳至原商户页面浏览器，一般是回跳至默认浏览器。建议您提供弹窗提示，当用户手动切换到商家收银台时能够根据弹窗选择。
重定向到结果页面是否意味着支付成功了？
结果页面不能作为判断支付是否成功的依据：
- 买家成功支付后，由于网络或其他原因，可能不会被重定向到结果页面。
- 如果买家尚未完成支付，仍然存在可以重定向到结果页面的入口。
- Antom 不支持在 paymentRedirectUrl 字段中指定表示支付结果的信息。
异步通知
支付完成之后，如何设置异步通知地址？
您需要在 支付（收银台）接口的 paymentNotifyUrl 字段传入地址，或者在 Antom Dashboard 配置异步通知地址。若两者都完成设置，优先以接口设置为准。请注意，异步通知地址没有格式要求。
在调用接口时，传入了其他的参数，异步通知会返回这些参数值吗？
目前 Antom 仅支持异步通知接口的标准参数返回，请参阅 支付通知 了解更多参数信息。
非卡支付和卡支付收到的通知类型一样吗？
不一样。以下为不同支付方式对应的通知类型：
- 非卡支付：
PAYMENT_RESULT - 卡支付：
PAYMENT_RESULT和CAPTURE_RESULT
是否有字段标识卡支付和非卡支付？
在接口查询和异步通知结果中，没有特定的字段标识是卡支付或非卡支付。您可以通过传入的 paymentRequestId 来判断相应的支付方式。
异步通知里的 paymentTime 有时差，需要进行额外的处理吗？
您可以根据 paymentTime 字段返回的时区进行转换，请参阅 支付通知 了解更多时区信息。
为什么有些支付方式的异步通知返回的参数中没有 pspName 字段？
pspName 字段不是必返字段，只有 Alipay+ 支付方式才会返回此字段。建议您不要对该字段强依赖，请参阅 支付通知 了解更多参数信息。
异步通知验签 Content_To_Be_Validated 里的 URL 的值是使用设置的异步通知地址吗？
是的。此 URL 可以从异步通知的返回的参数中获得。请注意不要带 query 值，即如果返回的通知地址为"/payment/notify?order=123"，则 URL 为"/payment/notify"。
如何处理异步通知的验签？
请参阅签名和验签了解更多验签信息。其中，入参的 alipayPublicKey 字段，需要在 Antom Dashboard 配置公钥后才能传入，其余入参字段从 Antom 发送的异步通知中获取。
我可以配置多少种类型的异步通知？
Antom Dashboard 支持多种类型的异步通知，如支付、退款等。请参阅通知地址了解更多异步通知类型。
何时会发送通知？
这取决于支付是否完成：
- 如果支付成功完成，Antom 通常会在 3 到 5 秒内发送异步通知。对于某些支付方式，如柜台支付（OTC），通知可能会稍有延迟。
- 如果支付未完成，Antom 需要先关闭订单，然后发送异步通知。不同支付方式关闭订单所需的时间会有所不同，通常默认为 14 分钟。
异步通知会被重新发送吗？
对于以下情况，异步通知会在 24 小时内自动重新发送：
- 如果由于网络原因未收到异步通知。
- 如果您收到来自 Antom 的异步通知，但您没有按照处理通知的示例代码格式对通知做出响应。
通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时和 15 小时。
在响应异步通知时，我需要添加数字签名吗？
如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但不需要对响应进行签名。
我应该多久调用一次 支付结果查询 接口？
以 2 秒的间隔持续调用 支付结果查询 接口，直到获取最终的支付结果或收到异步支付结果通知为止。
为什么有时无法收到异步通知呢？
买家完成支付后，您可能无法收到支付结果。可能的原因包括：
- 支付完成后，Antom 服务器会发送异步通知，告知商户相应的支付结果。但对于某些支付方式，支付失败时不会发送异步通知。
- 异步通知不保证 100% 送达。
当出现这种情况时，您可以调用 支付结果查询 接口来获取准确的支付结果。
参数
什么是 paymentId ？
如果您需要存储相应的订单 ID 以备后续退款和对账，可以指定 paymentId。
请求参数的值可以使用特殊字符吗？
为了避免特定支付方式的不兼容问题，部分请求参数的值请勿使用特殊字符，如 paymentRequestId 和 referenceOrderId 字段，请参阅 支付（收银台）接口了解更多参数格式信息。
paymentRequestId 和 captureRequestId 字段可以传入相同的值吗？
可以。请注意，paymentRequestId 不超过64字符即可，无最小长度限制。
返回的 paymentId 字段是固定的64字符吗？
生产环境返回的 paymentId 一般为35字符（纯数字），沙箱环境为64字符（数字和字母）。建议您不要做长度限制，避免未来 Antom 侧升级时导致的线上问题。
pay 接口中，传入 referenceOrderId 字段时有特殊要求吗？
没有特殊要求。referenceOrderId 代表您的商家订单号，是商户端用于识别订单的专属 ID。
异步通知是否会返回 referenceOrderId？
异步通知不会返回 referenceOrderId，但会返回 paymentRequestId，您可以使用 paymentRequestId 去关联referenceOrderId。
当 terminalType 为 WAP 的时候，如何判断是安卓还是 iOS 呢？
您可以通过浏览器的 userAgent 获取到这个信息。极端场景下，若无法获取 userAgent 信息，建议您传入安卓类型。
在 pay 接口中，paymentMethodMetaData 字段中的 Card 选项有哪些字段是必传的呢？
请参阅卡特殊支付要素了解更多。
创建支付请求时，APM 支付需传入哪些参数？
请参阅 APM 支付了解更多支付参数信息。
对于同一笔交易，在网络超时等情况下如何做重试？
根据 paymentRequestId 做幂等，即保持 paymentRequestId 不变，直接发送原请求来重试。请参阅 支付 接口了解更多信息。
传入支付金额的值时，各币种的最小单位是什么呢？
请参阅币种的最小单位了解更多币种信息。
可以自行设置关单时间吗？
您可以通过 paymentExpiryTime 字段设置关单时间，但目前仅部分支付方式支持该能力。大部分支付方式的默认关单时间是14分钟，部分支付方式存在差异，请参阅支付方式了解更多支付特性内容和是否支持自定义关单时间。请注意，此处的关单时间是指二维码过期时间，即支付超时。
order.goods.goodsName 是必传字段吗？
goods 字段不是必传字段。如果需要进行风险控制，请指定此参数。此时，goodsName 为必传字段。请参阅 支付 接口了解更多参数信息。
在沙箱环境下用 Alipay 支付，为什么需要传入 settlementStrategy 字段？
若您只签署了一种结算币种合约，则不需要传入 settlementStrategy 字段值。若您签署了多种结算币种，则需要传入指定的结算币种。
接口的 result.resultStatus 字段返回 U，这代表什么状态？
resultStatus 字段会返回3种值，您可以使用这个字段判断接口调用状态。有效值如下：
S：表示接口调用成功。F：表示接口调用失败。U：表示接口调用可能成功、处理中或失败。请参阅结果处理逻辑了解详细信息。
支付结果查询 接口中 resultStatus 和 paymentStatus 之间的关系是怎样的？
在 支付结果查询 接口中，resultStatus 代表本次接口调用是否成功，paymentStatus 代表订单的实际状态。只有当 resultStatus 返回 S 时才需要消费 paymentStatus 的状态。如果 resultStatus 返回 U 或 F ，需要您发起新的接口调用请求，不需要消费 paymentStatus。
支付完成后跳转至商户页面时，会返回和 paymentRedirectUrl 不同的参数吗？
一般情况下不会返回其他参数，但是不排除从支付方式直接回跳时可能会返回其他参数的情况。
如何判断 paymentMethodRegion 传入的值？
若您接入的是双标卡，您可以指定该参数的发卡所属区域。若不传入该值，则由 Antom 智能决策。若您本次只通过 Antom 接入国际 Visa 卡，则可以不传入该值。请参阅卡品牌列表了解更多支付方式地区信息。
如何设置 terminalType ？
terminalType 的有效值为：
- 如果买家在 PC 端发起交易，需要将 terminalType 指定为
WEB。 - 如果买家在移动浏览器上发起交易，需要将 terminalType 指定为
WAP。添加 osType 参数，并根据买家的手机填写相应的系统参数ANDROID或IOS。 - 如果买家在应用内发起交易，需要将 terminalType 指定为
APP。
结果码
当返回 RISK_REJECT 错误码时应如何处理？
当出现风险控制时会返回此错误码，目前发卡侧和 Antom 侧都有可能返回此错误码，请联系 Antom 技术支持排查具体原因。
USER_PAYMENT_VERIFICATION_FAILED 错误码的返回场景是什么？
此错误码仅限于卡的3D 支付认证。在卡场景下，超过了最大认证次数时会返回此错误码。
当返回 ORDER_IS_CLOSED 错误码时，订单已经关闭了吗？
是的。如果用户没有在关单时间内完成支付，此时订单会关闭并返回此错误码。
什么场景下会触发 PAYMENT_PROHIBITED 错误码呢？
当交易涉及淫秽色情/赌博/毒品等场景时会返回此错误码，建议您自行排查是否触及此类场景。
使用 Grabpay MY 和 Maya 支付方式时，返回 PROCESS_FAIL 错误码应该如何处理？
当返回 PROCESS_FAIL 错误码时，可能有以下原因：
- Antom 与支付方式之间的审批未通过
- 请求参数错误
当返回此错误码时，请勿重试，建议联系 Antom 技术支持排查原因。
卡支付请款失败后，换号重试为什么会返回 MULTI_CAPTURE_NOT_SUPPORTED 错误码？
Antom 对于一笔订单只支持一次请款。第一次请款失败后，Antom 不支持再次发起请款请求，否则会返回此错误码。当请款失败后，建议您取消这笔交易，更新 paymentRequestId 后重新发起一笔交易。
对于同一个 disputeId，当返回 DISPUTE_JUDGED 结果码时，还会返回 DISPUTE_CANCELLED 吗？
不会。DISPUTE_JUDGED 和 DISPUTE_CANCELLED 都是终态，对于同一个 disputeId，Antom 只会返回其中一个结果码。
为什么会返回 INVALID_SIGNATURE 错误码？
如果在调用接口时返回了 INVALID_SIGNATURE 错误代码，您可以排查以下情况：
- 提交报文后，Antom 端的签名验证失败。
- 签名内容与消息不匹配
- 报文中的换行符和空格可能与签名内容不一致（例如，\r\n 和 \n 之间）。
- 特殊字符转义问题。
- 时间戳不匹配：报文中的时间戳与签名内容中使用的时间戳不符。
- 公钥和私钥不匹配
- 确认用于签名和验证的密钥是正确匹配的。
- 更新的密钥未生效
- 如果使用更新的密钥添加签名时，网关提示签名验证失败，请联系 Antom 技术支持寻求帮助。
- Antom 返回了报文，但签名验证失败。
- 检查您的签名验证逻辑是否存在错误。
- 确保 Antom 公钥是正确的。
- 检查签名验证消息是否为原始文本。
有关签名问题的更详细故障排除信息，请参阅集成指南。
当返回 SETTLE_CONTRACT_NOT_MATCH 错误码时应如何处理？
如果在调用接口时返回了 SETTLE_CONTRACT_NOT_MATCH 错误代码，您可以排查以下情况：
- 在调用 支付 接口时，您没有指定 settlementStrategy.settlementCurrency 字段，将会返回
SETTLE_CONTRACT_NOT_MATCH错误代码。
为了解决此问题，请确保在请求中包含 settlementStrategy.settlementCurrency 字段。
- 如果您已指定 settlementCurrency 字段，您可以在结算概述页面查看已签署的结算合同列表。当指定的结算货币与合同中的默认结算货币不匹配时，将返回错误代码
SETTLE_CONTRACT_NOT_MATCH。
为了解决此问题，您可以在 支付 接口请求中修改 settlementCurrency 字段，或联系 Antom 技术支持更新结算合同。
当返回 INVALID_CONTRACT 错误码时应如何处理？
如果在调用接口时返回了 INVALID_CONTRACT 错误代码，您可以检查请求中的域名信息是否与 Antom Dashboard 的集成资源部分提供的数据相匹配。
如果确认域名信息正确后错误代码仍然存在 ，请联系 Antom 技术支持以解决此问题。
