> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payallglobal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 消费-收银台
> 发起消费交易，消费成功时会产生实际扣款。本接口用于收银台支付交易请求。
## OpenAPI
````yaml POST /api/mapi/v1/payments/open/api/cashier
openapi: 3.1.0
info:
version: '1.0'
title: PayAllGlobal开放平台接口文档
summary: ''
termsOfService: ''
contact:
name: 技术支持
email: support@payallglobal.com
url: ''
license:
url: https://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
servers:
- url: https://mpgwpre.payallglobal.com/mp-gateway/
description: 开发环境
- url: https://mpgw.payallglobal.com/mp-gateway/
description: 正式生产环境
security:
- signature: []
tags:
- name: 收单
- name: 其他交易类型
- name: 商户管理
- name: 文件下载
- name: 付款
paths:
/api/mapi/v1/payments/open/api/cashier:
post:
tags:
- 收单
summary: 消费-收银台
description: 发起消费交易，消费成功时会产生实际扣款。本接口用于收银台支付交易请求。
operationId: post-api-mapi-v1-payments-open-api-cashier
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutPay'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PayResponse'
'400':
description: Bad Request（请求参数错误、校验失败等）
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
examples:
参数缺失或格式错误:
value:
isSuccess: false
errCode: '00000002'
errMessage: 必填参数 merchantOrderId 缺失
status: FAIL
traceId: 33fae7b7aed1233f
'401':
description: Bad Request（请求参数错误、校验失败等）
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
examples:
签名验证失败:
value:
isSuccess: false
errCode: '00000002'
errMessage: 签名验证失败
status: FAIL
traceId: 33fae7b7aed1233f
security:
- signature: []
servers:
- url: https://mpgwpre.payallglobal.com/mp-gateway/
description: 开发环境
- url: https://mpgw.payallglobal.com/mp-gateway/
description: 正式生产环境
components:
schemas:
CheckoutPay:
title: Pay
examples:
- charset: UTF-8
version: 2.0.0
transType: PAY
accessType: s2s
signType: RSA
memberId: '2023010558663764'
merchantId: '2023010558663764'
deviceChannel: Brower
transTimeout: 10
carrierId: 跨境
currency: USD
transAmt: '20.01'
goodsName: Iphone15
dcc: dcc
notifyUrl: >-
https://mpgwdev.payallglobal.com/mp-gateway/api/mapi/v1/payments/open/api/unionPayTest1111
redirectUrl: >-
https://mpgwdev.payallglobal.com/mp-gateway/api/mapi/v1/payments/open/api/unionPayTest
merchantOrderId: '20230424141154'
payMethodInfo:
cardNo: 444433******1111
expirationMonth: '01'
expirationYear: '2026'
cvv: '123'
firstName: Bren
lastName: Qiu
phone: '18817536699'
merchantOrderTime: '2025-10-24T15:00:00.500+08:00'
merchantRegion: US
reqReserved: reqReserved
reserved: reserved
subMerchantId: '2258484869050'
goods:
- referenceGoodsId: M1006
goodsName: 单品惠-6
goodsCategory: '1001'
goodsQuantity: '100'
goodsUnitAmount:
currency: php
value: '100.01'
shippingInfo:
firstName: James
lastName: Smith
phoneNo: '903124360628'
email: James@example.com
address1: GOLGELI SOKAK NO.34, 06700
city: GAZIOSMANPASA/ANKAR
country: TR
state: CA
zipCode: '06700'
billingInfo:
firstName: James
lastName: Smith
phoneNo: '903124360628'
email: James@example.com
address1: GOLGELI SOKAK NO.34, 06700
city: GAZIOSMANPASA/ANKAR
country: TR
state: CA
zipCode: '06700'
allOf:
- $ref: '#/components/schemas/BaseRequest'
- type: object
properties:
deviceChannel:
type: string
description: 设备渠道
examples:
- Brower
transChannel:
type: string
enum:
- 'WEIXIN: 微信支付'
- 'UNIONPAY: 银联'
- 'ALIPAY_CN: 支付宝（大陆）'
- 'ALIPAY_HK: 支付宝（香港）'
- 'GCASH: GCash'
- 'BPI: BPI'
- 'TNG: Touch ''n Go'
- 'BOOST: Boost'
- 'DANA: DANA'
- 'KAKAOPAY: KakaoPay'
- 'TRUEMONEY: TrueMoney'
- 'BRAZIL_PIX: PIX'
- 'Ewallet_PicPay: PicPay'
- 'Khipu: Khipu'
- 'RABBIT_LINE_PAY: Rabbit LINE Pay'
- 'ALIPAY_INSTORE: 支付宝扫码支付'
- 'NAVERPAY: Naver Pay'
- 'TOSSPAY: Toss Pay'
- 'MAYA: Maya'
- 'BILLEASE: Billease'
- 'GoPay: GoPay'
- 'OVO: OVO'
- 'DOKU: DOKU'
- 'Dragonpay: Dragonpay'
- 'Konbini: Konbini'
- 'PayEasy: PayEasy'
- 'GrabPay: GrabPay'
- 'PAYCO: PAYCO'
- 'MPAY: mPAY'
- 'PROMPT_PAY: PromptPay'
- 'HIPAY: HiPay'
- 'TINABA: Tinaba'
- 'KREDIVO_ID: Kredivo'
- 'AKULAKU_PAYLATER: Akulaku PayLater'
- 'KPLUS: K PLUS'
- 'QRPH: QRPH'
- 'BANK_TRANSFER: 银行转账'
- 'KOREAN_CARDS: 韩国信用卡'
- 'CARD: 国际卡支付'
description: >-
支付渠道，详见[支付渠道列表](https://docs.payallglobal.com/developers/start/payMethod)
transTimeout:
type: number
description: 订单有效时长(整数格式 单位:分钟),示例值(10)
examples:
- 10
carrierId:
type: string
description: 发生交易的网站域名或者APP名称,示例值(跨境)
examples:
- 跨境
currency:
type: string
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码 eg.
USD, CNY, EUR
minLength: 3
maxLength: 3
examples:
- USD
transAmt:
type: string
description: 订单金额 请按照4217币种的最小单位传递 eg.(CNY) 110.86 (JPY) 1110
examples:
- '20.01'
goodsName:
type: string
description: "商品或订单的名称,多个名称之间用\";\"隔开\t"
examples:
- Iphone15;Macbook Pro
dcc:
type: string
description: 交易是否走DCC 传送：dcc
examples:
- dcc
notifyUrl:
type: string
description: 异步通知地址
format: uri
minLength: 10
maxLength: 200
examples:
- >-
https://mpgwdev.payallglobal.com/mp-gateway/api/mapi/v1/payments/open/api/unionPayTest1111
redirectUrl:
type: string
description: 前台回调地址
format: uri
examples:
- >-
https://mpgwdev.payallglobal.com/mp-gateway/api/mapi/v1/payments/open/api/unionPayTest
merchantOrderId:
type: string
description: 商户订单号，商户生成的唯一订单号。
examples:
- '20230424141154'
customerIp:
type: string
description: 用户ip
examples:
- 18.277.26.154
payMethodInfo:
$ref: '#/components/schemas/PayMethodInfo'
merchantOrderTime:
type: string
description: 请求时间（ISO 8601 格式，带时区）
format: date-time
example: '2025-10-24T15:00:00.500+08:00'
osType:
type: string
description: 手机操作系统类型(支付类型为APP时必传)
examples:
- IOS
merchantRegion:
type: string
description: 商户所在地区国家代码
examples:
- US
authCode:
type: string
description: "授权码(支付渠道为WEIXIN且支付类型为MICROPAY时需传值)\t"
examples:
- '133788758877188822'
appId:
type: string
description: 公众账号ID
examples:
- wxd678efh567hg6787
openId:
type: string
description: 应用内用户ID
examples:
- oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
reqReserved:
type: string
description: 商户备注扩展字段
examples:
- 备注扩展
reserved:
type: string
description: 备注字段
examples:
- 备注
subMerchantId:
description: 商户子商户号
type: string
examples:
- '20230424141154'
goods:
type: array
items:
$ref: '#/components/schemas/Goods'
shippingInfo:
$ref: '#/components/schemas/ShippingInfo'
billingInfo:
$ref: '#/components/schemas/BillingInfo'
required:
- transTimeout
- carrierId
- currency
- transAmt
- merchantOrderId
- merchantOrderTime
- merchantRegion
- goods
x-User: null
PayResponse:
examples:
- isSuccess: true
errCode: '00000003'
errMessage: 处理中
status: PENDING
traceId: 33fae7b7aed1233f
data:
orderId: TR1658354573473091584
merchantNo: '2023010558663764'
merchantOrderId: '20230424141154'
currency: USD
transAmt: '100.01'
payMethodResponse:
isRedirect: 'yes'
redirectMethod: get
termUrl: string
redirectParam: {}
codeUrl: weixin://wxpay/bizpayurl?pr=waUjCuPzz
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: object
properties:
orderId:
type: string
description: 交易订单号
examples:
- TR1658354573473091584
merchantNo:
type: string
description: 商户号
examples:
- '2023010558663764'
merchantOrderId:
type: string
description: 商户订单号
currency:
type: string
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码
eg. USD, CNY, EUR
examples:
- USD
transAmt:
type: string
description: 交易金额
examples:
- '100.01'
payMethodResponse:
type: object
description: 支付扩展信息
properties:
isRedirect:
type: string
description: "该笔交易是否需要重定向 yes：需要 no：不需要\t"
examples:
- 'yes'
redirectMethod:
type: string
description: "重定向方式，isRedirect=yes时返回。包含GET和POST\t"
examples:
- get
termUrl:
type: string
description: "继续支付跳转地址，isRedirect=y时返回\t"
redirectParam:
type: object
description: 重定向参数，商户需带着redirectParam重定向termUrl
codeUrl:
type: string
description: 二维码链接
examples:
- weixin://wxpay/bizpayurl?pr=waUjCuPzz
required:
- isRedirect
required:
- orderId
- merchantNo
- merchantOrderId
- currency
- transAmt
x-examples:
Example 1:
isSuccess: true
errCode: '00000003'
errMessage: 处理中
status: PENDING
traceId: 33fae7b7aed1233f
data:
orderId: '1551424900319940608'
merchantNo: '2001000000002036'
merchantOrderId: '20220725123000'
currency: HKD
payMethodResponse:
isRedirect: 'NO'
redirectMethod: GET
termUrl: normalUrl
redirectParam: {}
codeUrl: weixin://wxpay/bizpayurl?pr=waUjCuPzz
transAmt: '3.01'
BaseResponse:
type: object
properties:
isSuccess:
type: boolean
description: "是否成功，true表示成功，false表示失败\t"
examples:
- true
errCode:
type: string
description: "响应状态码，errCode为00000000表示响应成功，其他状态码表示响应失败。具体系统错误码可以参考系统错误码。\t"
examples:
- '00000003'
errMessage:
type: string
description: "错误消息\t"
examples:
- 处理中
status:
type: string
description: "订单状态(见补充说明)\t"
examples:
- PENDING：处理中
- SUCCESS：成功
- FAIL：失败
traceId:
type: string
description: "请求消息唯一标识。traceId为本次调用产生的流水号，接口调用异常，可以提供此流水号用于排查问题。\t"
examples:
- 33fae7b7aed1233f
required:
- isSuccess
- errCode
- errMessage
- status
- traceId
x-examples:
Example 1:
isSuccess: true
errCode: '00000003'
errMessage: 处理中
status: PENDING
traceId: 33fae7b7aed1233f
BaseRequest:
type: object
properties:
charset:
type: string
description: 交互数据的编码【utf-8】
default: UTF-8
examples:
- UTF-8
version:
type: string
description: "接口版本，当前版本为【2.0.0】,目前只能传2.0.0，不能不传\t"
examples:
- 2.0.0
transType:
type: string
enum:
- 'PAY: 消费支付'
- 'CREDIT_CARD: 信用卡支付'
- '3D_PREAUTH_VOIDS: 3D 预授权撤销'
- '3D_PREAUTH_COMPLETION: 3D 预授权完成'
- 'REFUND: 退款'
- 'VOIDS: 撤销'
- 'QUERY: 查询'
- 'TRANSFER: 转账'
- 'DOWNLOAD: 文件下载'
- 'REGISTRATION: 商户注册'
- 'FILEUPLOAD: 文件上传'
- 'INQUIRYREGISTRATIONSTATUS: 查询注册状态'
- 'AUTHORIZE: 授权'
- 'CASHIER_PAY: 收银台支付'
description: 交易类型
default: PAY
accessType:
type: string
description: 接口接入类型，固定为服务端到服务端(s2s)模式
default: s2s
examples:
- s2s
signType:
type: string
default: RSA
description: 报文签名类型，当前支持RSA。
examples:
- RSA
memberId:
type: string
description: 机构号，商户侧唯一标识
examples:
- '2023010558663764'
merchantId:
type: string
description: 商户号，商户唯一标识
examples:
- '2023010558663764'
required:
- charset
- version
- transType
- accessType
- signType
- memberId
- merchantId
x-examples:
Example 1:
charset: UTF-8
version: 2.0.0
transType: string
accessType: PAY
signType: RSA
memberId: stringstri
merchantId: stringstri
PayMethodInfo:
type: object
properties:
cardNo:
type: string
description: "交易卡号\t"
examples:
- 444433******1111
expirationMonth:
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
- '06'
- '07'
- '08'
- '09'
- 10
- 11
- 12
description: "卡片有效期月\t"
default: '01'
examples:
- '01'
expirationYear:
type: string
description: "卡片有效期年\t"
examples:
- '2026'
cvv:
type: string
description: "cvv\t"
examples:
- '123'
firstName:
type: string
description: "持卡人名,字母类型\t"
examples:
- Bren
lastName:
type: string
description: "持卡人姓,字母类型\t"
examples:
- Qiu
phone:
type: string
description: 手机号
examples:
- '18817536697'
x-examples:
Example 1:
cardNo: string
expirationMonth: string
expirationYear: string
cvv: string
firstName: string
lastName: string
phone: string
Goods:
type: object
properties:
referenceGoodsId:
type: string
description: "商品编号\t"
examples:
- M1006
goodsName:
type: string
description: "商品名称\t"
examples:
- 单品惠-6
goodsCategory:
type: string
description: "商品分类\t"
examples:
- '1001'
goodsQuantity:
type: string
description: "商品数量\t"
examples:
- '100'
goodsUnitAmount:
type: object
description: "商品单价\t"
properties:
currency:
type: string
description: "币种\t"
examples:
- php
value:
type: string
description: "金额\t"
examples:
- '100.01'
required:
- currency
- value
required:
- referenceGoodsId
- goodsName
- goodsCategory
- goodsQuantity
- goodsUnitAmount
x-examples:
Example 1:
referenceGoodsId: string
goodsName: string
goodsCategory: string
goodsQuantity: string
goodsUnitAmount: object
ShippingInfo:
type: object
description: 邮寄信息。国际卡支付必传
required:
- firstName
- lastName
- phoneNo
- email
- address1
- city
- country
- zipCode
properties:
firstName:
type: string
description: 收货人名
maxLength: 64
example: 张
middleName:
type: string
description: 收货人中间名
maxLength: 64
example: 大
lastName:
type: string
description: 收货人姓
maxLength: 64
example: 三
phoneNo:
type: string
description: 收货人手机号
maxLength: 32
example: '13800138000'
email:
type: string
description: 收货邮箱地址
maxLength: 255
example: zhangsan@example.com
address1:
type: string
description: 收货地址1（主要街道地址）
maxLength: 1024
example: 成都市高新区天府大道中段1234号
address2:
type: string
description: 收货地址2（补充信息，如楼号、单元号）
maxLength: 1024
example: XX大厦A座1808室
city:
type: string
description: 收货地址所在城市
maxLength: 64
example: 成都
region:
type: string
description: 收货地址所在区域（如区/县）
maxLength: 64
example: 高新区
state:
type: string
description: >-
ISO 3166-2中定义的州或省代码。例如，美国的CA或加拿大的ON。美国和加拿大必传。
maxLength: 32
example: CA
country:
type: string
description: 收货地址所在国家（ISO 3166-1 alpha-2 两位代码）
maxLength: 2
example: CN
zipCode:
type: string
description: 收货地址邮编
maxLength: 32
example: '610000'
BillingInfo:
type: object
description: 信用卡账单信息。国际卡支付必传
required:
- email
- address1
- city
- country
properties:
firstName:
type: string
description: 账单人名
maxLength: 64
example: 张
middleName:
type: string
description: 账单人中间名
maxLength: 64
example: 大
lastName:
type: string
description: 账单人姓
maxLength: 64
example: 三
phoneNo:
type: string
description: 账单人手机号
maxLength: 32
example: '13800138000'
phoneNoRegion:
type: string
description: 账单人手机号区号
email:
type: string
description: 账单邮箱地址
maxLength: 255
example: zhangsan@example.com
address1:
type: string
description: 账单地址1（主要街道地址）
maxLength: 1024
example: 成都市高新区天府大道中段1234号
address2:
type: string
description: 账单地址2（补充信息）
maxLength: 1024
example: XX大厦A座1808室
city:
type: string
description: 账单地址所在城市
maxLength: 64
example: 成都
region:
type: string
description: 账单地址所在区域
maxLength: 64
example: 高新区
state:
type: string
description: >-
账单地址所在州。ISO 3166-2中定义的州或省代码。例如，美国的CA或加拿大的ON。美国和加拿大必传。
maxLength: 32
example: CA
country:
type: string
description: 账单地址所在国家（ISO 3166-1 alpha-2 两位代码）
maxLength: 2
example: CN
zipCode:
type: string
description: 账单地址邮编
maxLength: 16
example: '610000'
securitySchemes:
signature:
type: apiKey
description: >-
Example: MIIEpQIBAAKCAQEA...（Base64编码的签名字符串）
## 加签
加签是开放平台和商户对于交互消息完整性的校验。加签行为主要发生两个部分：
1. 商户服务器端针对向PayAllGlobal开放平台发送的请求报文进行加签；
2. PayAllGlobal开放平台针对通知商户的异步消息进行加签。
PayAllGlobal平台要求使用 RSA 私钥进行加签， 使用 RSA 公钥进行验签。 因此，在以上两部分描述的交互中，
存在商户公私钥、PayAllGlobal 公私钥，开发者需要使用商户私钥，对第一部分报文进行加签，使用 PayAllGlobal
公钥对第二部分消息进行验签。
### 加签规则如下:
使用商户私钥对请求体进行 SHA256withRSA 签名后，再进行 Base64 编码的结果。
1. 使用 商户私钥对待 `request.body` 进行签名（SHA256WithRSA 计算原始数据的SHA-256哈希值。
使用私钥对哈希值进行签名，即使用私钥对哈希值进行RSA加密。此时得到的加密结果就是数字签名。）；
```java
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
// 计算 SHA256withRSA 签名时，需要以 utf-8 的编码转换 byte 流，否则可能导致含中文参数的签名计算不正确
signature.update(request.body);
byte[] signedHash = signature.sign();
```
2. 将加签内容进行 Base64 编码；
```java
String signature = Base64.getEncoder().encodeToString(signedHash);
```
3. 将编码后的内容放在请求头部 signature 参数中。
注意，加签是对 request.body 进行签名，当查询等 request.body 为空时，则无需加签。
name: signature
in: header
````