> ## 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/pay
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/pay:
post:
tags:
- 收单
summary: 消费
description: 发起消费交易，消费成功时会产生实际扣款
operationId: post-api-mapi-v1-payments-open-api-pay
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APIPay'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PayResponse'
examples:
Example 1:
value:
isSuccess: true
errCode: string
errMessage: string
status: string
traceId: string
data:
orderId: string
merchantNo: string
merchantOrderId: string
currency: string
payMethodResponse:
isRedirect: string
redirectMethod: string
termUrl: string
redirectParam: {}
codeUrl: string
transAmt: string
security:
- signature: []
servers:
- url: https://mpgwpre.payallglobal.com/mp-gateway/
description: 开发环境
- url: https://mpgw.payallglobal.com/mp-gateway/
description: 正式生产环境
components:
schemas:
APIPay:
title: Pay
examples:
- charset: UTF-8
version: 2.0.0
transType: PAY
accessType: s2s
signType: RSA
merchantId: '2023010558663764'
transChannel: ALIPAY_CN
transAmt: '5.67'
currency: USD
merchantOrderId: '20230424141154'
merchantOrderTime: '2025-10-24T15:00:00.500+08:00'
goodsName: 商品名称,多个商品 用";"隔开
carrierId: 测试
deviceChannel: PC/IOS/Android
payMode: H5
merchantRegion: HK
transTimeout: 20
redirectUrl: https://dash.proxy302.com/charge
notifyUrl: https://dash-api.proxy302.com/api/webhook/chinagpay_alipay
dcc: dcc
customerIp: 18.277.26.154
goods:
- referenceGoodsId: M1006
goodsName: 单品惠-6
goodsCategory: '1001'
goodsQuantity: '100'
goodsUnitAmount:
currency: php
value: '100.01'
goodsInfo: 商品信息描述
subMerchantId: '2258484869050'
reqReserved: reqReserved
reserved: reserved
payMethodInfo:
cardNo: 444433******1111
expirationMonth: '01'
expirationYear: '2026'
cvv: '123'
firstName: Bren
lastName: Qiu
phone: '18817536699'
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/APIBaseRequest'
- type: object
properties:
deviceChannel:
type: string
description: 设备渠道
transChannel:
type: string
enum:
- WEIXIN
- UNIONPAY
- ALIPAY_CN
- ALIPAY_HK
- GCASH
- BPI
- TNG
- BOOST
- DANA
- KAKAOPAY
- TRUEMONEY
- BRAZIL_PIX
- Ewallet_PicPay
- Khipu
- RABBIT_LINE_PAY
- ALIPAY_INSTORE
- NAVERPAY
- TOSSPAY
- MAYA
- BILLEASE
- GoPay
- OVO
- DOKU
- Dragonpay
- Konbini
- PayEasy
- GrabPay
- PAYCO
- MPAY
- PROMPT_PAY
- HIPAY
- TINABA
- KREDIVO_ID
- AKULAKU_PAYLATER
- KPLUS
- QRPH
- BANK_TRANSFER
- KOREAN_CARDS
- 'CARD: 国际卡支付'
description: >-
支付渠道，详见[支付渠道列表](https://docs.payallglobal.com/developers/start/payMethod)
transTimeout:
type: number
description: 订单有效时长(整数格式 单位:分钟)
examples:
- 20
carrierId:
type: string
description: 发生交易的网站域名或者APP名称
examples:
- 跨境
currency:
type: string
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码 eg.
USD, CNY, EUR
examples:
- USD
transAmt:
type: string
description: 订单金额 请按照4217币种的最小单位传递 eg.(CNY) 110.86 (JPY) 1110
examples:
- '20.01'
goodsName:
type: string
description: "商品名称,多个商品 用\";\"隔开\t"
examples:
- Iphone15
notifyUrl:
type: string
description: 异步通知地址
format: uri
minLength: 10
maxLength: 200
redirectUrl:
type: string
description: 前台回调地址
examples:
- http://www.gogole.com
merchantOrderId:
type: string
description: 商户订单号
examples:
- '20230424141154'
payMode:
type: string
enum:
- QRCODE
- MICROPAY
- JSAPI
- MINIPROGRAM
- APP
- H5
- 3D
- FIXEDCODE
- API（国际卡API支付）
description: |
交易类型
default: QRCODE
examples:
- QRCODE
merchantOrderTime:
type: string
description: 请求时间（ISO 8601 格式，带时区）
format: date-time
example: '2025-10-24T15:00:00.500+08:00'
merchantRegion:
type: string
description: 商户所在地区
examples:
- US
dcc:
type: string
description: 交易是否走DCC 传送：dcc
examples:
- dcc
customerIp:
type: string
description: 用户ip。国际卡支付必传
examples:
- 18.277.26.154,
goods:
type: array
items:
$ref: '#/components/schemas/Goods'
goodsInfo:
type: string
description: 商品信息
examples:
- 商品信息描述
subMerchantId:
description: 商户子商户号
type: string
examples:
- '20230424141154'
reqReserved:
type: string
description: 商户备注扩展字段
examples:
- 备注扩展
reserved:
type: string
description: 备注字段
examples:
- 测试
payMethodInfo:
$ref: '#/components/schemas/PayMethodInfo'
type: object
description: 卡信息。国际卡支付必传
shippingInfo:
$ref: '#/components/schemas/ShippingInfo'
billingInfo:
$ref: '#/components/schemas/BillingInfo'
required:
- transChannel
- currency
- transAmt
- merchantOrderId
- payMode
- merchantOrderTime
- merchantRegion
- transTimeout
- carrierId
- goodsName
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'
APIBaseRequest:
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_PREAUTH_COMPLETION
- REFUND
- VOIDS
- QUERY
- TRANSFER
- DOWNLOAD
- REGISTRATION
- FILEUPLOAD
- INQUIRYREGISTRATIONSTATUS
- AUTHORIZE
- CASHIER_PAY
- 'CARD: 国际卡支付'
description: 交易类型
default: PAY
accessType:
type: string
description: "接口访问类型\t"
default: s2s
examples:
- s2s
signType:
type: string
description: 报文签名类型
examples:
- RSA
merchantId:
type: string
description: "商户号\t"
examples:
- '2023010558663764'
required:
- charset
- version
- transType
- accessType
- signType
- merchantId
x-examples:
Example 1:
charset: UTF-8
version: 2.0.0
transType: string
accessType: PAY
signType: RSA
merchantId: stringstri
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
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
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'
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
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
````