Unipay Agent Merchant API

This page is a complete integration reference. You can complete integration from this page without downloading the YAML file.

Overview

Merchant Model

Agent merchants use transparent upstream routing. Do not pass upstream route fields; the backend selects an enabled ISV route.

sign in examples is a placeholder. Generate it from the actual request fields according to the signature rules.

Response Envelope

Field	Type	Required	Description
`code`	integer(int32)	Yes	Business response code.
`msg`	string	Yes	Business response message.
`data`	object\|null	No	Business response payload.
`sign`	string	No	Response signature signed by the platform.
`resTime`	string(date-time)	No	Response time.
`traceId`	string	No	Trace ID for troubleshooting.

Endpoint List

Path	API	Description
`POST /unipay/pay`	Pay	Create a Mexico virtual account payment order and start payment processing.
`POST /unipay/options/pay-methods`	List payment methods	List payment methods available to the current merchant.
`POST /unipay/options/payee-types`	List transfer payee types	List payee types available to the current merchant for transfers.
`POST /unipay/options/payee-codes`	List transfer payee codes	List Ginx public payee codes available to the current merchant for a payeeType.
`POST /unipay/close`	Close or Cancel Payment	Close an unfinished payment order, optionally using cancel mode.
`POST /unipay/inqury`	Transfer Account Inqury	Validate the payee account before creating a transfer.
`POST /unipay/transfer`	Transfer	Create and submit a transfer order.
`POST /unipay/query/payOrder`	Query Payment Order	Query the current status and details of a payment order.
`POST /unipay/query/transferOrder`	Query Transfer Order	Query the current status and details of a transfer order.
`POST /unipay/sync/order/pay`	Sync Payment Order	Synchronize payment status from upstream and adjust the local order.

Pay

Create a Mexico virtual account payment order and start payment processing.

Call this after creating a merchant order. Use mex_virtual_account as the method. The response returns the platform order number, payment status, and virtual account payment body.

Request

Field	Description
Method	POST
Path	`/unipay/pay`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`bizOrderNo`	string	Yes	minLength=1, maxLength=100	Merchant payment order number.
`title`	string	Yes	minLength=1, maxLength=100	Payment title.
`description`	string	No	maxLength=50	Payment description.
`expiredTime`	string(date-time)	No	None	Order expiration time.
`method`	string	Yes	minLength=1, maxLength=32	Payment method code.
`limitPay`	string	No	maxLength=128	Payment restriction code.
`amount`	number(double)	Yes	minimum=0.01	Transaction amount.
`extraParam`	string	No	maxLength=2048	Extension parameters in JSON string format.
`attach`	string	No	maxLength=500	Merchant attachment returned in callbacks.
`returnUrl`	string	No	maxLength=200	Browser return URL.
`quitUrl`	string	No	maxLength=200	Quit URL.
`notifyUrl`	string	No	maxLength=200	Asynchronous callback URL.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizOrderNo": "BIZ-PAY-20260414-001",
  "title": "Order Payment",
  "description": "Payment for order #001",
  "expiredTime": "2026-04-14 12:00:00",
  "method": "mex_virtual_account",
  "limitPay": "string",
  "amount": 12.5,
  "extraParam": "{\"scene\":\"mobile\"}",
  "attach": "{\"orderTag\":\"vip\"}",
  "returnUrl": "https://merchant.example.com/return",
  "quitUrl": "https://merchant.example.com/quit",
  "notifyUrl": "https://merchant.example.com/callback"
}

Response Data

Field	Type	Required	Description
`bizOrderNo`	string	No	Merchant payment order number.
`orderNo`	string	No	Platform payment order number.
`status`	string	No	Business status.
`payBody`	string	No	Payment body for starting payment.

Common Values

Payment method

value	Description
`mex_virtual_account`	MEX 虚拟账户入金

Payment restriction

value	Description
`no_credit`	限制信用卡支付

Payment status

value	Description
`wait`	待支付
`progress`	支付中
`success`	成功
`close`	支付关闭
`cancel`	支付撤销
`fail`	失败
`timeout`	支付超时

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizOrderNo": "BIZ-PAY-20260414-001",
    "orderNo": "P202604140001",
    "status": "success",
    "payBody": "{\"qrCode\":\"https://...\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Callback

Payment order callback

The platform sends a POST callback to notifyUrl when order status changes. Content-Type is application/json.

The body is DaxNoticeResult<PayOrderResult>. data uses the same fields as the order query response.

The platform signs sign with the platform private key. Verify it with the platform public key and return plain text SUCCESS for success.

Timeout is 15 seconds. Failed callbacks are retried up to 16 times. Handle callbacks idempotently by platform order number or merchant business number.

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizOrderNo": "BIZ-PAY-20260414-001",
    "orderNo": "P202604140001",
    "title": "Order Payment",
    "description": "Payment for order #001",
    "method": "mex_virtual_account",
    "limitPay": "string",
    "amount": 12.5,
    "fee": 0.01,
    "realAmount": 0.01,
    "status": "success",
    "settleStatus": "not_settle",
    "settleType": "D+1",
    "settleTime": "2026-04-14 12:00:00",
    "payTime": "2026-04-14 12:00:00",
    "closeTime": "2026-04-14 12:00:00",
    "expiredTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a",
  "noticeType": "order_status_changed",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

Merchant Response

text

SUCCESS

List payment methods

List payment methods available to the current merchant.

Call this before rendering payment methods or building a pay request. Agent merchants receive public method codes without upstream channel details.

Request

Field	Description
Method	POST
Path	`/unipay/options/pay-methods`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

None

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

Response Data

Field	Type	Required	Description
`code`	string	No	Business response code.
`name`	string	No	名称

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "code": "mex_virtual_account",
      "name": "MEX虚拟账户入金"
    }
  ],
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

List transfer payee types

List payee types available to the current merchant for transfers.

Call this before rendering transfer payee types or building inqury/transfer requests.

Request

Field	Description
Method	POST
Path	`/unipay/options/payee-types`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

None

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

Response Data

Field	Type	Required	Description
`code`	string	No	Business response code.
`name`	string	No	名称

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "code": "spei_transfer",
      "name": "SPEI 转账"
    }
  ],
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

List transfer payee codes

List Ginx public payee codes available to the current merchant for a payeeType.

Call this when a payee type requires a bank or institution code. Use returned Ginx codes directly in inqury and transfer requests; do not submit raw OPM/Fintoc upstream codes.

Request

Field	Description
Method	POST
Path	`/unipay/options/payee-codes`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`payeeType`	string	Yes	minLength=1, maxLength=32	Payee account type.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "payeeType": "spei_transfer"
}

Response Data

Field	Type	Required	Description
`code`	string	No	Business response code.
`name`	string	No	名称

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "code": "mx_banxico",
      "name": "BANXICO"
    }
  ],
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Close or Cancel Payment

Close an unfinished payment order, optionally using cancel mode.

Use this when the order expires, the user cancels, or the merchant stops payment. Provide at least one order identifier.

Request

Field	Description
Method	POST
Path	`/unipay/close`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`orderNo`	string	No	maxLength=100	Platform payment order number.
`bizOrderNo`	string	No	maxLength=100	Merchant payment order number.
`useCancel`	boolean	No	None	Whether to close by cancel mode.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "orderNo": "P202604140001",
  "bizOrderNo": "BIZ-PAY-20260414-001",
  "useCancel": true
}

Response Data

data is null when the operation succeeds.

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Transfer Account Inqury

Validate the payee account before creating a transfer.

Use this for bank card, SPEI, or other transfer scenarios that require account validation.

Request

Field	Description
Method	POST
Path	`/unipay/inqury`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`bizInquryNo`	string	Yes	minLength=1, maxLength=100	Merchant inqury number.
`payeeType`	string	Yes	minLength=1, maxLength=32	Payee account type.
`payeeAccount`	string	Yes	minLength=1, maxLength=100	Payee account.
`payeeName`	string	No	maxLength=50	Payee name.
`payeeCode`	string	No	maxLength=64	Ginx public payee code returned by the payee-codes options API. Do not submit raw upstream bank or institution codes.
`extraParam`	string	No	maxLength=2048	Extension parameters in JSON string format.
`attach`	string	No	maxLength=500	Merchant attachment returned in callbacks.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizInquryNo": "BIZ-INQURY-20260414-001",
  "payeeType": "spei_transfer",
  "payeeAccount": "6222020202020202",
  "payeeName": "ZHANG SAN",
  "payeeCode": "mx_banxico",
  "extraParam": "{\"scene\":\"mobile\"}",
  "attach": "{\"orderTag\":\"vip\"}"
}

Response Data

Field	Type	Required	Description
`bizInquryNo`	string	No	Merchant inqury number.
`inquryNo`	string	No	Platform inqury number.
`status`	string	No	Business status.
`accountValid`	boolean	No	Whether the payee account is valid.
`uploadPayeeName`	string	No	Payee name submitted by the merchant.

Common Values

Payee type

value	Description
`user_id`	用户 ID
`open_id`	OpenId
`login_name`	用户账号
`bank_card`	银行卡
`spei_transfer`	SPEI 转账

Inqury status

value	Description
`valid`	账户有效
`invalid`	账户无效
`unknown`	未知

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizInquryNo": "BIZ-INQURY-20260414-001",
    "inquryNo": "string",
    "status": "valid",
    "accountValid": true,
    "uploadPayeeName": "ZHANG SAN"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Transfer

Create and submit a transfer order.

Use this for payout scenarios such as withdrawals, bank card transfer, or SPEI transfer. Account inqury is recommended first.

Request

Field	Description
Method	POST
Path	`/unipay/transfer`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`bizTransferNo`	string	Yes	minLength=1, maxLength=100	Merchant transfer number.
`amount`	number(double)	Yes	minimum=0.01	Transaction amount.
`title`	string	No	maxLength=100	Payment title.
`reason`	string	No	maxLength=50	Reason or remark.
`payeeType`	string	Yes	minLength=1, maxLength=32	Payee account type.
`payeeAccount`	string	Yes	minLength=1, maxLength=100	Payee account.
`payeeName`	string	No	maxLength=50	Payee name.
`payeeCode`	string	No	maxLength=64	Ginx public payee code returned by the payee-codes options API. Do not submit raw upstream bank or institution codes.
`extraParam`	string	No	maxLength=2048	Extension parameters in JSON string format.
`attach`	string	No	maxLength=500	Merchant attachment returned in callbacks.
`notifyUrl`	string	No	maxLength=200	Asynchronous callback URL.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizTransferNo": "BIZ-TRANSFER-20260414-001",
  "amount": 12.5,
  "title": "Order Payment",
  "reason": "Manual operation remark",
  "payeeType": "spei_transfer",
  "payeeAccount": "6222020202020202",
  "payeeName": "ZHANG SAN",
  "payeeCode": "mx_banxico",
  "extraParam": "{\"scene\":\"mobile\"}",
  "attach": "{\"orderTag\":\"vip\"}",
  "notifyUrl": "https://merchant.example.com/callback"
}

Response Data

Field	Type	Required	Description
`bizTransferNo`	string	No	Merchant transfer number.
`transferNo`	string	No	Platform transfer number.
`status`	string	No	Business status.

Common Values

Payee type

value	Description
`user_id`	用户 ID
`open_id`	OpenId
`login_name`	用户账号
`bank_card`	银行卡
`spei_transfer`	SPEI 转账

Transfer status

value	Description
`progress`	转账中
`success`	转账成功
`close`	转账关闭
`fail`	转账失败

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizTransferNo": "BIZ-TRANSFER-20260414-001",
    "transferNo": "T202604140001",
    "status": "progress"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Callback

Transfer order callback

The platform sends a POST callback to notifyUrl when order status changes. Content-Type is application/json.

The body is DaxNoticeResult<TransferOrderResult>. data uses the same fields as the order query response.

The platform signs sign with the platform private key. Verify it with the platform public key and return plain text SUCCESS for success.

Timeout is 15 seconds. Failed callbacks are retried up to 16 times. Handle callbacks idempotently by platform order number or merchant business number.

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizTransferNo": "BIZ-TRANSFER-20260414-001",
    "transferNo": "T202604140001",
    "amount": 12.5,
    "fee": 0.01,
    "title": "Order Payment",
    "reason": "Manual operation remark",
    "payeeType": "spei_transfer",
    "payeeAccount": "6222020202020202",
    "payeeName": "ZHANG SAN",
    "payeeCode": "mx_banxico",
    "status": "success",
    "finishTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a",
  "noticeType": "order_status_changed",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

Merchant Response

text

SUCCESS

Query Payment Order

Query the current status and details of a payment order.

Use this when payment status is uncertain, callbacks are delayed, or reconciliation is required.

Request

Field	Description
Method	POST
Path	`/unipay/query/payOrder`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`orderNo`	string	No	maxLength=100	Platform payment order number.
`bizOrderNo`	string	No	maxLength=100	Merchant payment order number.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "orderNo": "P202604140001",
  "bizOrderNo": "BIZ-PAY-20260414-001"
}

Response Data

Field	Type	Required	Description
`bizOrderNo`	string	No	Merchant payment order number.
`orderNo`	string	No	Platform payment order number.
`title`	string	No	Payment title.
`description`	string	No	Payment description.
`method`	string	No	Payment method code.
`limitPay`	string	No	Payment restriction code.
`amount`	number(double)	No	Transaction amount.
`fee`	number(double)	No	Fee amount.
`realAmount`	number(double)	No	Net received amount.
`status`	string	No	Business status.
`settleStatus`	string	No	Settlement status.
`settleType`	string	No	Settlement type.
`settleTime`	string(date-time)	No	Settlement time.
`payTime`	string(date-time)	No	Payment completion time.
`closeTime`	string(date-time)	No	Close time.
`expiredTime`	string(date-time)	No	Order expiration time.
`attach`	string	No	Merchant attachment returned in callbacks.

Common Values

Payment status

value	Description
`wait`	待支付
`progress`	支付中
`success`	成功
`close`	支付关闭
`cancel`	支付撤销
`fail`	失败
`timeout`	支付超时

Settlement status

value	Description
`not_settle`	未结算
`settled`	已结算

Settlement type

value	Description
`REALTIME`	实时
`D+1`	D+1
`D+2`	D+2
`D+3`	D+3

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizOrderNo": "BIZ-PAY-20260414-001",
    "orderNo": "P202604140001",
    "title": "Order Payment",
    "description": "Payment for order #001",
    "method": "mex_virtual_account",
    "limitPay": "string",
    "amount": 12.5,
    "fee": 0.01,
    "realAmount": 0.01,
    "status": "success",
    "settleStatus": "not_settle",
    "settleType": "D+1",
    "settleTime": "2026-04-14 12:00:00",
    "payTime": "2026-04-14 12:00:00",
    "closeTime": "2026-04-14 12:00:00",
    "expiredTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Query Transfer Order

Query the current status and details of a transfer order.

Use this when transfer status is uncertain, callbacks are delayed, or reconciliation is required.

Request

Field	Description
Method	POST
Path	`/unipay/query/transferOrder`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`bizTransferNo`	string	No	maxLength=100	Merchant transfer number.
`transferNo`	string	No	maxLength=32	Platform transfer number.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizTransferNo": "BIZ-TRANSFER-20260414-001",
  "transferNo": "T202604140001"
}

Response Data

Field	Type	Required	Description
`bizTransferNo`	string	No	Merchant transfer number.
`transferNo`	string	No	Platform transfer number.
`amount`	number(double)	No	Transaction amount.
`fee`	number(double)	No	Fee amount.
`title`	string	No	Payment title.
`reason`	string	No	Reason or remark.
`payeeType`	string	No	Payee account type.
`payeeAccount`	string	No	Payee account.
`payeeName`	string	No	Payee name.
`payeeCode`	string	No	Ginx public payee code returned by the payee-codes options API. Do not submit raw upstream bank or institution codes.
`status`	string	No	Business status.
`finishTime`	string(date-time)	No	Finish time.
`attach`	string	No	Merchant attachment returned in callbacks.

Common Values

Payee type

value	Description
`user_id`	用户 ID
`open_id`	OpenId
`login_name`	用户账号
`bank_card`	银行卡
`spei_transfer`	SPEI 转账

Transfer status

value	Description
`progress`	转账中
`success`	转账成功
`close`	转账关闭
`fail`	转账失败

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizTransferNo": "BIZ-TRANSFER-20260414-001",
    "transferNo": "T202604140001",
    "amount": 12.5,
    "fee": 0.01,
    "title": "Order Payment",
    "reason": "Manual operation remark",
    "payeeType": "spei_transfer",
    "payeeAccount": "6222020202020202",
    "payeeName": "ZHANG SAN",
    "payeeCode": "mx_banxico",
    "status": "success",
    "finishTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Sync Payment Order

Synchronize payment status from upstream and adjust the local order.

Use this for delayed callbacks, long-running processing states, or manual operations recovery.

Request

Field	Description
Method	POST
Path	`/unipay/sync/order/pay`
Content-Type	`application/json`

Common Request Parameters

Field	Type	Required	Constraint	Description
`mchNo`	string	Yes	maxLength=32	Merchant number.
`appId`	string	No	maxLength=32	Application ID.
`reqTime`	string(date-time)	Yes	yyyy-MM-dd HH:mm:ss	Request time in yyyy-MM-dd HH:mm:ss format.
`nonceStr`	string	No	maxLength=32	Random nonce. Use a unique value for each request.
`sign`	string	Yes	maxLength=1024	Request signature.
`clientIp`	string	No	maxLength=64	Client IP address.

Business Parameters

Field	Type	Required	Constraint	Description
`orderNo`	string	No	maxLength=100	Platform payment order number.
`bizOrderNo`	string	No	maxLength=100	Merchant payment order number.

Request Example

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "orderNo": "P202604140001",
  "bizOrderNo": "BIZ-PAY-20260414-001"
}

Response Data

Field	Type	Required	Description
`orderStatus`	string	No	Order status after synchronization.
`adjust`	boolean	No	Whether local data was adjusted.

Common Values

Payment status

value	Description
`wait`	待支付
`progress`	支付中
`success`	成功
`close`	支付关闭
`cancel`	支付撤销
`fail`	失败
`timeout`	支付超时

Success Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderStatus": "success",
    "adjust": true
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Failure Response Example

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

YAML Download

unipay-agent.yaml

Unipay Agent Merchant API ​

Overview ​

Merchant Model ​

Response Envelope ​

Endpoint List ​

Pay ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Common Values ​

Payment method ​

Payment restriction ​

Payment status ​

Success Response Example ​

Failure Response Example ​

Callback ​

Payment order callback ​

Merchant Response ​

List payment methods ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Success Response Example ​

Failure Response Example ​

List transfer payee types ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Success Response Example ​

Failure Response Example ​

List transfer payee codes ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Success Response Example ​

Failure Response Example ​

Close or Cancel Payment ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Success Response Example ​

Failure Response Example ​

Transfer Account Inqury ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Common Values ​

Payee type ​

Inqury status ​

Success Response Example ​

Failure Response Example ​

Transfer ​

Request ​

Common Request Parameters ​

Business Parameters ​

Request Example ​

Response Data ​

Common Values ​

Payee type ​

Transfer status ​

Success Response Example ​

Failure Response Example ​

Callback ​

Transfer order callback ​

Merchant Response ​

Query Payment Order ​

Request ​

Common Request Parameters ​

Unipay Agent Merchant API

Overview

Merchant Model

Response Envelope

Endpoint List

Pay

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Common Values

Payment method

Payment restriction

Payment status

Success Response Example

Failure Response Example

Callback

Payment order callback

Merchant Response

List payment methods

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Success Response Example

Failure Response Example

List transfer payee types

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Success Response Example

Failure Response Example

List transfer payee codes

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Success Response Example

Failure Response Example

Close or Cancel Payment

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Success Response Example

Failure Response Example

Transfer Account Inqury

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Common Values

Payee type

Inqury status

Success Response Example

Failure Response Example

Transfer

Request

Common Request Parameters

Business Parameters

Request Example

Response Data

Common Values

Payee type

Transfer status

Success Response Example

Failure Response Example

Callback

Transfer order callback

Merchant Response

Query Payment Order

Request

Common Request Parameters