> ## 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/preAuth 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/preAuth: post: tags: - 收单 summary: 预授权 operationId: post-api-mapi-v1-payments-open-api-preAuth requestBody: content: application/json: schema: $ref: '#/components/schemas/Pay' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PayResponse' security: - signature: [] servers: - url: https://mpgwpre.payallglobal.com/mp-gateway/ description: Development server - url: https://mpgw.payallglobal.com/mp-gateway/ description: Live server components: schemas: Pay: title: Pay examples: - charset: UTF-8 version: 2.0.0 transType: PAY accessType: s2s signType: RSA memberId: '2023010558663764' merchantId: '2023010558663764' threeDsType: '2.0' deviceChannel: string transChannel: WEIXIN transTimeout: string carrierId: carrierId currency: USD transAmt: '20.01' goodsName: Iphone15 dcc: DCC notifyUrl: http://example.com redirectUrl: http://www.gogole.com merchantOrderId: '20230424141154' customerIp: 18.277.26.154 payMode: QRCODE payMethodInfo: cardNo: 444433******1111 expirationMonth: '01' expirationYear: '2026' cvv: '123' firstName: Bren lastName: Qiu phone: '18817536697' merchantOrderTime: '2019-08-24T14:15:22Z' osType: IOS merchantRegion: US authCode: '133788758877188822' appId: wxd678efh567hg6787 openId: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o reqReserved: reqReserved reserved: reserved buyerId: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o address: zipCode: '344104' region: US city: ShangHai state: ShangHai phone: '18817536697' email: string address1: Lou Lan street address2: Lou Lan street 2 customer: address: zipCode: '344104' region: US city: ShangHai state: ShangHai phone: '18817536697' email: string address1: Lou Lan street address2: Lou Lan street 2 certificate: number: string type: string subMerchantId: string userAgent: string goods: - referenceGoodsId: M1006 goodsName: 单品惠-6 goodsCategory: '1001' goodsQuantity: '100' goodsUnitAmount: '100.01' store: storeTerminalId: '0001' browserInfo: acceptHeader: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 javaEnabled: 'true' language: en-US colorDepth: '160' screenHeight: '1024' screenWidth: '648' browserTz: string browserIp: 8.8.8.8 userAgent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 allOf: - $ref: '#/components/schemas/BaseRequest' - type: object properties: threeDsType: type: string description: 使用3d交易必传(示例值 1.0 2.0) examples: - '2.0' 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 description: 支付渠道 transTimeout: type: string description: 订单有效时长(整数格式 单位:分钟) carrierId: type: string description: 发生交易的网站域名或者APP名称 examples: - carrierId 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 dcc: type: string description: 交易是否走DCC 传送：dcc examples: - DCC 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' customerIp: type: string description: 用户ip examples: - 18.277.26.154 payMode: type: string enum: - QRCODE - MICROPAY - JSAPI - MINIPROGRAM - APP - H5 - 3D - FIXEDCODE description: | 交易类型 更多描述参考 [支付方式](api#/#支付方式) default: QRCODE examples: - QRCODE payMethodInfo: $ref: '#/components/schemas/PayMethodInfo' merchantOrderTime: type: string description: 商户订单时间 format: date-time 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: - reqReserved reserved: type: string description: 保留字段 examples: - reserved buyerId: type: string description: 商户用户ID(支付渠道为BRAZIL_PIX必传) examples: - oUpF8uMuAJO_M2pxb1Q9zNjWeS6o address: $ref: '#/components/schemas/Address' customer: $ref: '#/components/schemas/Customer' subMerchantId: type: string userAgent: type: string goods: type: array items: $ref: '#/components/schemas/Goods' store: $ref: '#/components/schemas/Store' browserInfo: $ref: '#/components/schemas/BrowserInfo' required: - transChannel - currency - transAmt - merchantOrderId - payMode - merchantOrderTime - merchantRegion 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' 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 Address: type: object properties: zipCode: type: string description: 邮编 examples: - '344104' region: type: string description: "地区码/国家 ISO 3166-1规范两位字母的国家代码\t" examples: - US city: type: string description: 城市 examples: - ShangHai state: type: string description: 省份 examples: - ShangHai phone: type: string description: 手机 examples: - '18817536697' email: type: string description: "邮箱\t" address1: type: string description: "地址\t" examples: - Lou Lan street address2: type: string description: "地址\t" examples: - Lou Lan street 2 x-examples: Example 1: zipCode: string region: string city: string state: string phone: string email: string address1: string address2: string Customer: type: object properties: address: $ref: '#/components/schemas/Address' certificate: $ref: '#/components/schemas/Certificate' x-examples: Example 1: address: string certificate: 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 Store: type: object title: Store properties: storeTerminalId: type: string description: "店铺处理支付设备ID\t" examples: - '0001' BrowserInfo: type: object properties: acceptHeader: type: string description: "浏览器请求头\t" examples: - >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 javaEnabled: type: string description: "浏览器Java是否启用.javaEnabled属性\t" examples: - 'true' language: type: string description: "浏览器语言navigator\t" examples: - en-US colorDepth: type: string description: "浏览器像素screen.colorDepth属性\t" examples: - '160' screenHeight: type: string description: "浏览器屏幕高度screen.height属性\t" examples: - '1024' screenWidth: type: string description: "浏览器屏幕宽度screen.width属性\t" examples: - '648' browserTz: type: string description: "时差getTimezoneOffset()\t" browserIp: type: string description: "浏览器Ip\t" examples: - 8.8.8.8 userAgent: type: string description: "浏览器请求头User-Agent属性\t" examples: - >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 x-examples: Example 1: acceptHeader: string javaEnabled: string language: string colorDepth: string screenHeight: string screenWidth: string browserTz: string browserIp: string userAgent: string 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 Certificate: type: object title: Certificate properties: number: type: string type: type: string 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 ````