业务架构

澳门地区商户\机构接入 Alipay 线下收单,实现 AlipayCN,AlipayMO,AlipayHK,Kakaopay等电子钱包收单能力的方式,如下图所示:

• 业务架构说明

1. 澳门钱包和全球站同属于不同收单站点.分属不同的主体.商户需要分别同主体签约.
2. 澳门钱包和全球站的商户账号,密钥相互对立.
3. 收单机构需要在向 Alipay 发送下单支付请求前,区分是澳门钱包还是全球游钱包(Barcode\QRCode 区分)

域名

澳门站域名：https://open.alipaymo.com，全球站域名：https://open-sea.alipay.com

Note：

• API接口文档示例给出的是全球站的请求url地址例如下面示例，集成澳门收单站需要替换域名即可,

Main flows

商户/机构集成实现AlipayMO 钱包反扫支付,需要实现支付,查询,退款,撤销接口的集成.

Note:

• 当payQuery接口返回resultCode是ORDER_NOT_EXIST,需要调用payQuery接口发起查询.查询次数最佳实践建议为2次,实践间隔5~7S.因为payQuery请求因网络等原因导致比下单支付请求提前到达.

Barcode Payment

Barcode Payment 解决方案是用户提供Barcode或QrCode，商户通过POS/扫码枪扫用户的QrCode完成支付的解决方案。

Offline payment

Offline to online payment

Pay flow

商户/机构调用alipay.intl.acquiring.offline.pay API接口创建订单并完成用户扣款.

支付扣款流程:

在线支付

AlipayMO为了防止用户被盗或欺诈行为,会概率性要求用户输入用户支付密码完成支付.例如:

• AlipayMO 风控系统识别到用户交易行为可疑.
• AMCM 监管要求用户输入用户密码完成交易.

Currency

• 只支持 MOP

Payment result

如果下单支付返回结果为UNKNOWN_EXCEPTION,商户/机构需要调用alipay.intl.acquiring.offline.payQuery接口确认订单支付结果.

接口参数信息以及错误码信息请参阅 alipay.intl.acquiring.offline.pay和 alipay.intl.acquiring.offline.payQuery

Cancel flow

在支付整体流程中,有可能发生系统 exception, 网络连接超时等系统原因导致支付结果不确定.这种情况下商户\机构需要调用 cancel 接口 alipay.intl.acquiring.common.payCancel发起订单撤销

撤销流程:

Notes:

• cancel有效期为订单创建24小时内.
• cancel退 fee.
• 交易过程中发生异常,调用该接口发起交易冲正,保证不发生单边账.

接口参数信息以及错误码信息请参阅 alipay.intl.acquiring.common.payCancel.

Refund flow

消费者可以请求商户对于已经支付完成的交易发起全额退款或者部分退款.商户\机构可以调用退款接口alipay.intl.acquiring.common.refund发起退款流程.

退款流程:

Notes:

• 退款是否退 fee, 根据商户\机构签约协议决定.
• 商户退款周期依赖商户签约协议,一般有3个月\6个月\12个月可选在.
• 退款金额一定小于等于原始支付交易金额.

接口参数信息以及错误码信息请参阅 alipay.intl.acquiring.common.refund.

Order query flow

商户/机构可以在订单支付状态不确定的情况下调用 alipay.intl.acquiring.offline.payQuery发起查询.

查询流程:

接口参数信息以及错误码信息请参阅 alipay.intl.acquiring.offline.payQuery

Third-party Merchant QR Code Payment

Third-party Merchant QR Code Payment解决方案又称聚合码，是由AlipayMO合作机构提供的一种静态码，后背实现多渠道支付的一种解决方案。需要用户有网络条件以及输入金额确认支付。

Third-party Merchant QR Code Payment flow

Note：

• 聚合码需要商户或机构实现H5收银台页面，用于输入金额。
• 机构通过判断UA是否包含“Region/MO”，有则为AlipayMO wallet。
• AMCM对澳门地区正扫场景有限额要求，AlipayMO提供授权获取用户UID能力，帮助机构实现限额控制。
• 预下单preCreate接口中的userAgent参数需要传入https headers中UA完成参数。
• 接口参数信息以及错误码信息请阅

• 预下单：alipay.intl.acquiring.offline.preCreate
• 异步通知：alipay.intl.acquiring.offline.notify.pay
• 获取用户UID：alipay.intl.oauth.auth.applyToken

• 前端授权url请阅以下示例及参数说明

授权url示例：

https://render.alipay.com/p/w/oAuth/index.html?scene=thirdPartyMerchantQrCode&type=1&scopes=%5B%22auth_base%22%5D&response_type=code&redirect_uri=https%3A%2F%2Fopenauth.alipay.com%2F&merchant_id=xxx&client_id=xxx

授权url参数说明

Online Payment

Online Payment是商戶APP跳轉到支付寶APP進行支付的解决方案。

Online Payment Flow （Mobile)

Online Payment Flow （Web - Scan QRCode)

注意事項

• 接口参数信息以及错误码信息请参阅 

• 预下单：alipay.intl.acquiring.offline.preCreate，注意下述接口参数说明
• 异步通知：alipay.intl.acquiring.offline.notify.pay，请注意，这里的商户服务端接收到的是文档里request的描述，然后返回的是response的样式
• 查询：alipay.intl.acquiring.offline.payQuery

• 服務端调用预下单接口，请注意以下参数

• notifyUrl: 支付结果的异步通知的URL，
• merchantRedirectUrl: 结束支付后同步回跳，不一定包含支付结果，如支付结果不明确，请以异步通知结果为准，或主动做payQuery请求
• payScheme: 用于手机端跳转拉起支付宝收银台
• orderQrCode: 用于PC端展示付款二维码，用户扫一扫支付

• 最佳实践：

• 用户选澳门支付宝支付后，客户端需展示支付中页面（处理在支付过程中退出App的情况）并设置订单时效，如10分钟
• 待异步通知结果为Success/Fail则展示相应支付结果
• 支付后同步回跳若没有收到明确支付结果（不是Success/Fail），需主动做payQuery请求并有重试机制，建议每5-7秒，重试2-3次
• 若重试后仍没有明确支付结果，订单时效已过，则需要主动发起Cancel订单(使用merchantTransId以及requestMsgId撤销)

preCreate Online Payment 接口参数说明

Oauth

商户通过集成用户授权接口，可以获取AlipayMO提供的用户个人信息，实现用户免登陆，关联用户等。简化用户端体验流程，方便业务拓展。

静默授权

• 前端授权url请阅以下示例及参数说明

第一步：获取authCode

授权url示例：

location.replace("https://render.alipay.com/p/w/oAuth/index.html?scene=thirdPartyMerchantQrCode&type=1&scopes=%5B%22auth_base%22%5D&response_type=code&redirect_uri=https%3A%2F%2Fopenauth.alipay.com%2F&merchant_id=&client_id='

授权url参数说明

第二步：获取用户UID

• alipay.intl.oauth.auth.applyToken

用户主动授权

getAuthCode - 获取authCode

JSAPI获取authCode

• https://global.alipay.com/docs/ac/global/jsapi_macao#MlNMA

小程序获取authCode

• https://opendocs.alipay.com/mini/api/openapi-authorize

applyToken - 获取用户UID

• alipay.intl.oauth.auth.applyToken

getUserInfo - 获取用户手机号

• alipay.intl.user.query.getUserInfo

Signature

所有API调用，必须经过数字签名和验签。当对Alipay进行API调用时，使用RSA私钥对API请求进行签名。收到API请求后，支付宝将使用商户的RSA公钥来验证签名是否与API请求的内容匹配。收到支付宝API响应时，需要使用支付宝的RSA公钥来验证API响应的签名。必须在上线前交换RSA密钥，詳見https://global.alipay.com/docs/ac/gr/signature。

Settlement

AlipayMO 根据商户\机构签约协议周期发起结算.结算条件依赖于商户待结算余额.澳门地区节假日暂停结算任务.

Notes: 

• N根据合约配置

对帐文件

• 对账文件通过 AlipayMO 提供 SFTP 服务器以及账号密码登录获取，需提供IP白名单访问
• SFTP文件每7天清理，补帐单只能补30天内的，请务必每日下载到本地保存
• 路径：/download/<merchantId>/<date>
• 有交易文件（transaction file）及结算文件（settlement file）两类
• 文件获取时间下午14:00以后

交易文件（transaction file）

• 交易明细 - https://global.alipay.com/docs/ac/files/transaction_detail
• transaction file T+N 产出,当日如果没有发生交易,默认无帐单，可以提需求产出空账单

结算文件（settlement file）

• 结算明细 - https://global.alipay.com/docs/ac/files/settlement_detail
• 结算汇总 - https://global.alipay.com/docs/ac/files/settlement_summary
• settlement file, 若 T 日交易, T+N日满足结算限额(比如1000 MOP，根据合约配置),T+N日发起结算任务, T+N＋1日产出结算账单.

Barcode规则

商户\机构需要区分反扫和正扫是澳门本地钱包 AlipayMO 的用户,使用不同的账号发起下单请求.

Note：

• 码长度为24位， 码前缀25-30，第4-6位为003
• 正则表达式 ^((2[5-9])|(30))\d{1}(003)\d{18}$

帐单信息与接口对应取值

设X ＝ 优先级：storeName > sellerName > merchantName

POS打印信息

商户\机构对接 AlipayMO offline收单业务, POS打印小票需要的必要信息如下:

• 支付寶澳門地區服務(请用繁体) Alipay Service in Macao
• 支付金额，币种，时间。
• 商户交易号，AlipayMO交易号

对比全球站API差异

对比全球站204接口, AlipayMO下单支付\退款\查询\撤销接口请求参数完全和全球站2.0.4接口保持一致.因全球站是跨币种结算,而 AlipayMO 是本地币种结算,所接口响应参数有些许不一样的地方.

接口差异点:

账单:

• 账单格式完全同全球站账单格式(transaction 和 settlement)
• value 差异化