API Unipay para comercios agente

Esta pagina es una referencia completa de integracion. Puede completar la integracion sin descargar el archivo YAML.

Resumen

Modelo de comercio

Los comercios agente usan enrutamiento ascendente transparente. No envie campos de ruta ascendente; el backend selecciona un canal ISV habilitado.

sign en los ejemplos es un marcador. Debe generarse con los campos reales segun las reglas de firma.

Estructura de respuesta

Campo	Tipo	Requerido	Descripcion
`code`	integer(int32)	Si	Codigo de respuesta de negocio.
`msg`	string	Si	Mensaje de respuesta de negocio.
`data`	object\|null	No	Carga util de respuesta.
`sign`	string	No	Response signature signed by the platform.
`resTime`	string(date-time)	No	Hora de respuesta.
`traceId`	string	No	Trace ID para diagnostico.

Lista de APIs

Ruta	API	Descripcion
`POST /unipay/pay`	Pago	Crea una orden de pago de cuenta virtual Mexico e inicia el procesamiento.
`POST /unipay/options/pay-methods`	Listar metodos de pago	Lista los metodos de pago disponibles para el comercio actual.
`POST /unipay/options/payee-types`	Listar tipos de beneficiario	Lista los tipos de beneficiario disponibles para transferencias.
`POST /unipay/options/payee-codes`	Listar codigos de beneficiario	Lista los codigos publicos de Ginx disponibles para un payeeType.
`POST /unipay/close`	Cerrar o cancelar pago	Cierra una orden de pago no finalizada, opcionalmente usando cancelacion.
`POST /unipay/inqury`	Consulta previa de transferencia	Valida la cuenta receptora antes de crear una transferencia.
`POST /unipay/transfer`	Transferencia	Crea y envia una orden de transferencia.
`POST /unipay/query/payOrder`	Consultar orden de pago	Consulta el estado actual y los detalles de una orden de pago.
`POST /unipay/query/transferOrder`	Consultar transferencia	Consulta el estado actual y los detalles de una transferencia.
`POST /unipay/sync/order/pay`	Sincronizar pago	Sincroniza el estado de pago desde el upstream y ajusta la orden local.

Pago

Crea una orden de pago de cuenta virtual Mexico e inicia el procesamiento.

Llamelo despues de crear la orden del comercio. Use mex_virtual_account como metodo. La respuesta devuelve el numero de orden, estado y cuerpo de pago de cuenta virtual.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/pay`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`bizOrderNo`	string	Si	minLength=1, maxLength=100	Numero de orden del comercio.
`title`	string	Si	minLength=1, maxLength=100	Titulo del pago.
`description`	string	No	maxLength=50	Descripcion del pago.
`expiredTime`	string(date-time)	No	Ninguna	Hora de expiracion.
`method`	string	Si	minLength=1, maxLength=32	Codigo de metodo de pago.
`limitPay`	string	No	maxLength=128	Codigo de restriccion de pago.
`amount`	number(double)	Si	minimum=0.01	Importe de la transaccion.
`extraParam`	string	No	maxLength=2048	Parametros extendidos en formato JSON string.
`attach`	string	No	maxLength=500	Datos adjuntos del comercio devueltos en callbacks.
`returnUrl`	string	No	maxLength=200	URL de retorno del navegador.
`quitUrl`	string	No	maxLength=200	URL de salida.
`notifyUrl`	string	No	maxLength=200	URL de callback asincrono.

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`bizOrderNo`	string	No	Numero de orden del comercio.
`orderNo`	string	No	Numero de orden de pago de plataforma.
`status`	string	No	Estado de negocio.
`payBody`	string	No	Cuerpo de pago para iniciar el pago.

Valores comunes

Metodo de pago

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

Restriccion de pago

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

Estado de pago

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

Ejemplo de respuesta exitosa

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"
}

Ejemplo de error

json

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

Callback

Callback de orden de pago

La plataforma envia un callback POST a notifyUrl cuando cambia el estado de la orden. Content-Type es application/json.

El cuerpo es DaxNoticeResult<PayOrderResult>. data usa los mismos campos que la respuesta de consulta de orden.

La plataforma firma sign con su llave privada. El comercio verifica con la llave publica de la plataforma y debe devolver texto plano SUCCESS cuando procese correctamente.

El timeout es 15 segundos. Los callbacks fallidos se reintentan hasta 16 veces. Procese el callback de forma idempotente por numero de orden de plataforma o numero de negocio del comercio.

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"
}

Respuesta del comercio

text

SUCCESS

Listar metodos de pago

Lista los metodos de pago disponibles para el comercio actual.

Use antes de mostrar metodos de pago o construir una solicitud de pago. Los comercios agente no reciben detalles del canal ascendente.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/options/pay-methods`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Ninguna

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`code`	string	No	Codigo de respuesta de negocio.
`name`	string	No	名称

Ejemplo de respuesta exitosa

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"
}

Ejemplo de error

json

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

Listar tipos de beneficiario

Lista los tipos de beneficiario disponibles para transferencias.

Use antes de mostrar tipos de beneficiario o construir solicitudes de inqury/transferencia.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/options/payee-types`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Ninguna

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`code`	string	No	Codigo de respuesta de negocio.
`name`	string	No	名称

Ejemplo de respuesta exitosa

json

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

Ejemplo de error

json

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

Listar codigos de beneficiario

Lista los codigos publicos de Ginx disponibles para un payeeType.

Use cuando el tipo de beneficiario requiere codigo de banco o institucion. Use los codigos devueltos por Ginx en inqury y transferencia; no envie codigos upstream de OPM/Fintoc.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/options/payee-codes`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`payeeType`	string	Si	minLength=1, maxLength=32	Tipo de cuenta receptora.

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`code`	string	No	Codigo de respuesta de negocio.
`name`	string	No	名称

Ejemplo de respuesta exitosa

json

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

Ejemplo de error

json

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

Cerrar o cancelar pago

Cierra una orden de pago no finalizada, opcionalmente usando cancelacion.

Use esta API cuando la orden expire, el usuario cancele o el comercio detenga el pago. Envie al menos un identificador.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/close`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`orderNo`	string	No	maxLength=100	Numero de orden de pago de plataforma.
`bizOrderNo`	string	No	maxLength=100	Numero de orden del comercio.
`useCancel`	boolean	No	Ninguna	Indica si se usa modo cancelacion.

Ejemplo de solicitud

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
}

Campo data de respuesta

data es null cuando la operacion es exitosa.

Ejemplo de respuesta exitosa

json

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

Ejemplo de error

json

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

Consulta previa de transferencia

Valida la cuenta receptora antes de crear una transferencia.

Use esta API para tarjeta bancaria, SPEI u otros escenarios que requieren validar la cuenta.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/inqury`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`bizInquryNo`	string	Si	minLength=1, maxLength=100	Numero de consulta del comercio.
`payeeType`	string	Si	minLength=1, maxLength=32	Tipo de cuenta receptora.
`payeeAccount`	string	Si	minLength=1, maxLength=100	Cuenta receptora.
`payeeName`	string	No	maxLength=50	Nombre del receptor.
`payeeCode`	string	No	maxLength=64	Codigo publico de Ginx devuelto por la API de payee-codes. No envie codigos upstream de banco o institucion.
`extraParam`	string	No	maxLength=2048	Parametros extendidos en formato JSON string.
`attach`	string	No	maxLength=500	Datos adjuntos del comercio devueltos en callbacks.

Ejemplo de solicitud

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\"}"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`bizInquryNo`	string	No	Numero de consulta del comercio.
`inquryNo`	string	No	Numero de consulta de plataforma.
`status`	string	No	Estado de negocio.
`accountValid`	boolean	No	Indica si la cuenta receptora es valida.
`uploadPayeeName`	string	No	Nombre del receptor enviado por el comercio.

Valores comunes

Tipo de receptor

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

Estado de consulta previa

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

Ejemplo de respuesta exitosa

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"
}

Ejemplo de error

json

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

Transferencia

Crea y envia una orden de transferencia.

Use esta API para pagos salientes como retiros, transferencia bancaria o SPEI. Se recomienda consulta previa.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/transfer`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`bizTransferNo`	string	Si	minLength=1, maxLength=100	Numero de transferencia del comercio.
`amount`	number(double)	Si	minimum=0.01	Importe de la transaccion.
`title`	string	No	maxLength=100	Titulo del pago.
`reason`	string	No	maxLength=50	Motivo o comentario.
`payeeType`	string	Si	minLength=1, maxLength=32	Tipo de cuenta receptora.
`payeeAccount`	string	Si	minLength=1, maxLength=100	Cuenta receptora.
`payeeName`	string	No	maxLength=50	Nombre del receptor.
`payeeCode`	string	No	maxLength=64	Codigo publico de Ginx devuelto por la API de payee-codes. No envie codigos upstream de banco o institucion.
`extraParam`	string	No	maxLength=2048	Parametros extendidos en formato JSON string.
`attach`	string	No	maxLength=500	Datos adjuntos del comercio devueltos en callbacks.
`notifyUrl`	string	No	maxLength=200	URL de callback asincrono.

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`bizTransferNo`	string	No	Numero de transferencia del comercio.
`transferNo`	string	No	Numero de transferencia de plataforma.
`status`	string	No	Estado de negocio.

Valores comunes

Tipo de receptor

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

Estado de transferencia

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

Ejemplo de respuesta exitosa

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"
}

Ejemplo de error

json

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

Callback

Callback de transferencia

La plataforma envia un callback POST a notifyUrl cuando cambia el estado de la orden. Content-Type es application/json.

El cuerpo es DaxNoticeResult<TransferOrderResult>. data usa los mismos campos que la respuesta de consulta de orden.

La plataforma firma sign con su llave privada. El comercio verifica con la llave publica de la plataforma y debe devolver texto plano SUCCESS cuando procese correctamente.

El timeout es 15 segundos. Los callbacks fallidos se reintentan hasta 16 veces. Procese el callback de forma idempotente por numero de orden de plataforma o numero de negocio del comercio.

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"
}

Respuesta del comercio

text

SUCCESS

Consultar orden de pago

Consulta el estado actual y los detalles de una orden de pago.

Use esta API cuando el estado sea incierto, el callback se retrase o se requiera conciliacion.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/query/payOrder`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`orderNo`	string	No	maxLength=100	Numero de orden de pago de plataforma.
`bizOrderNo`	string	No	maxLength=100	Numero de orden del comercio.

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`bizOrderNo`	string	No	Numero de orden del comercio.
`orderNo`	string	No	Numero de orden de pago de plataforma.
`title`	string	No	Titulo del pago.
`description`	string	No	Descripcion del pago.
`method`	string	No	Codigo de metodo de pago.
`limitPay`	string	No	Codigo de restriccion de pago.
`amount`	number(double)	No	Importe de la transaccion.
`fee`	number(double)	No	Importe de comision.
`realAmount`	number(double)	No	Importe neto recibido.
`status`	string	No	Estado de negocio.
`settleStatus`	string	No	Estado de liquidacion.
`settleType`	string	No	Tipo de liquidacion.
`settleTime`	string(date-time)	No	Hora de liquidacion.
`payTime`	string(date-time)	No	Hora de pago.
`closeTime`	string(date-time)	No	Hora de cierre.
`expiredTime`	string(date-time)	No	Hora de expiracion.
`attach`	string	No	Datos adjuntos del comercio devueltos en callbacks.

Valores comunes

Estado de pago

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

Estado de liquidacion

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

Tipo de liquidacion

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

Ejemplo de respuesta exitosa

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"
}

Ejemplo de error

json

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

Consultar transferencia

Consulta el estado actual y los detalles de una transferencia.

Use esta API cuando el estado sea incierto, el callback se retrase o se requiera conciliacion.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/query/transferOrder`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`bizTransferNo`	string	No	maxLength=100	Numero de transferencia del comercio.
`transferNo`	string	No	maxLength=32	Numero de transferencia de plataforma.

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`bizTransferNo`	string	No	Numero de transferencia del comercio.
`transferNo`	string	No	Numero de transferencia de plataforma.
`amount`	number(double)	No	Importe de la transaccion.
`fee`	number(double)	No	Importe de comision.
`title`	string	No	Titulo del pago.
`reason`	string	No	Motivo o comentario.
`payeeType`	string	No	Tipo de cuenta receptora.
`payeeAccount`	string	No	Cuenta receptora.
`payeeName`	string	No	Nombre del receptor.
`payeeCode`	string	No	Codigo publico de Ginx devuelto por la API de payee-codes. No envie codigos upstream de banco o institucion.
`status`	string	No	Estado de negocio.
`finishTime`	string(date-time)	No	Hora de finalizacion.
`attach`	string	No	Datos adjuntos del comercio devueltos en callbacks.

Valores comunes

Tipo de receptor

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

Estado de transferencia

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

Ejemplo de respuesta exitosa

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"
}

Ejemplo de error

json

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

Sincronizar pago

Sincroniza el estado de pago desde el upstream y ajusta la orden local.

Use esta API para callbacks retrasados, estados en proceso por mucho tiempo o recuperacion manual.

Solicitud

Campo	Descripcion
Metodo	POST
Ruta	`/unipay/sync/order/pay`
Content-Type	`application/json`

Parametros comunes

Campo	Tipo	Requerido	Restriccion	Descripcion
`mchNo`	string	Si	maxLength=32	Numero de comercio.
`appId`	string	No	maxLength=32	ID de aplicacion.
`reqTime`	string(date-time)	Si	yyyy-MM-dd HH:mm:ss	Hora de solicitud en formato yyyy-MM-dd HH:mm:ss.
`nonceStr`	string	No	maxLength=32	Nonce aleatorio. Use un valor unico por solicitud.
`sign`	string	Si	maxLength=1024	Firma de la solicitud.
`clientIp`	string	No	maxLength=64	Direccion IP del cliente.

Parametros de negocio

Campo	Tipo	Requerido	Restriccion	Descripcion
`orderNo`	string	No	maxLength=100	Numero de orden de pago de plataforma.
`bizOrderNo`	string	No	maxLength=100	Numero de orden del comercio.

Ejemplo de solicitud

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"
}

Campo data de respuesta

Campo	Tipo	Requerido	Descripcion
`orderStatus`	string	No	Estado de orden despues de sincronizacion.
`adjust`	boolean	No	Indica si los datos locales fueron ajustados.

Valores comunes

Estado de pago

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

Ejemplo de respuesta exitosa

json

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

Ejemplo de error

json

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

Descarga YAML

unipay-agent.yaml

API Unipay para comercios agente ​

Resumen ​

Modelo de comercio ​

Estructura de respuesta ​

Lista de APIs ​

Pago ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Valores comunes ​

Metodo de pago ​

Restriccion de pago ​

Estado de pago ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Callback ​

Callback de orden de pago ​

Respuesta del comercio ​

Listar metodos de pago ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Listar tipos de beneficiario ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Listar codigos de beneficiario ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Cerrar o cancelar pago ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Consulta previa de transferencia ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Valores comunes ​

Tipo de receptor ​

Estado de consulta previa ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Transferencia ​

Solicitud ​

Parametros comunes ​

Parametros de negocio ​

Ejemplo de solicitud ​

Campo data de respuesta ​

Valores comunes ​

Tipo de receptor ​

Estado de transferencia ​

Ejemplo de respuesta exitosa ​

Ejemplo de error ​

Callback ​

Callback de transferencia ​

Respuesta del comercio ​

Consultar orden de pago ​

Solicitud ​

Parametros comunes ​

API Unipay para comercios agente

Resumen

Modelo de comercio

Estructura de respuesta

Lista de APIs

Pago

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Valores comunes

Metodo de pago

Restriccion de pago

Estado de pago

Ejemplo de respuesta exitosa

Ejemplo de error

Callback

Callback de orden de pago

Respuesta del comercio

Listar metodos de pago

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Ejemplo de respuesta exitosa

Ejemplo de error

Listar tipos de beneficiario

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Ejemplo de respuesta exitosa

Ejemplo de error

Listar codigos de beneficiario

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Ejemplo de respuesta exitosa

Ejemplo de error

Cerrar o cancelar pago

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Ejemplo de respuesta exitosa

Ejemplo de error

Consulta previa de transferencia

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Valores comunes

Tipo de receptor

Estado de consulta previa

Ejemplo de respuesta exitosa

Ejemplo de error

Transferencia

Solicitud

Parametros comunes

Parametros de negocio

Ejemplo de solicitud

Campo data de respuesta

Valores comunes

Tipo de receptor

Estado de transferencia

Ejemplo de respuesta exitosa

Ejemplo de error

Callback

Callback de transferencia

Respuesta del comercio

Consultar orden de pago

Solicitud

Parametros comunes