v1.0.9 · 2026-06-21

Documentación API de pagos Vietnam | ucake API Docs

APIs estándar del sistema de pagos de Vietnam, que cubren pagos salientes, consulta de pagos salientes, creación y cierre de cuentas virtuales, consulta de cuentas virtuales, consulta de saldo de empresa, creación de QR dinámico y notificaciones asíncronas.

Base path: /vnpay/api/v1

Endpoints API

API de pago saliente

POST /vnpay/api/v1/payment

Usa esta API para enviar fondos a la cuenta bancaria del usuario.

Campos de solicitud

  • amount - integer - Requerido - Importe de pago saliente. Rango: 50,000 a 50,000,000.
  • orderNo - string - Requerido - Número de orden del comercio. Debe ser único en cada solicitud.
  • accountName - string - Requerido - Nombre del usuario
  • phoneNo - string - Opcional - Teléfono del usuario
  • accountNo - string - Requerido - Número de cuenta del usuario
  • accountType - integer - Requerido - Tipo de cuenta: 0 número de cuenta, 1 número de tarjeta.
  • bankCode - string - Requerido - Código bancario
  • message - string - Requerido - Nota de pago saliente
  • returnURL - string - Requerido - URL de notificación de retorno
  • companyID - string - Requerido - ID de empresa asignado por el backend.
  • merchantID - string - Requerido - ID de comercio asignado por el sistema.
  • timestamp - number - Requerido - Marca de tiempo
  • sign - string - Requerido - Firma

Campos de respuesta

  • amount - integer - Importe de transacción
  • orderNo - string - Número de orden del comercio enviado en la solicitud.
  • tradeNo - string - Número de transacción
  • createTime - string - Hora de creación de la transacción. Formato: yyyy-MM-dd HH:mm:ss.
  • updateTime - string - Última hora de actualización de la transacción.
  • bankCode - string - Código bancario
  • phoneNo - string - Teléfono
  • accountName - string - Nombre del usuario
  • accountNo - string - Número de cuenta del usuario
  • accountType - integer - Tipo de cuenta
  • message - String - Nota

API de consulta de resultado de pago saliente

GET /vnpay/api/v1/paymentResult

Cuando un pago saliente está en proceso, puedes esperar la notificación o consultar el resultado manualmente.

Campos de solicitud

  • orderNo - string - Requerido - Número de orden enviado a la API de pago saliente.
  • tradeNo - string - Requerido - Número de transacción devuelto por la API de pago saliente.
  • companyID - string - Requerido - ID de empresa asignado por el backend.
  • merchantID - string - Requerido - ID de comercio asignado por el sistema.
  • sign - string - Requerido - Firma
  • timestamp - number - Requerido - Marca de tiempo

Campos de respuesta

  • amount - integer - Importe de transacción
  • orderNo - string - Número de orden del comercio
  • tradeNo - string - Número de transacción
  • createTime - string - Hora de creación de la transacción
  • updateTime - string - Última hora de actualización de la transacción.
  • bankCode - string - Código bancario
  • phoneNo - string - Teléfono
  • accountName - string - Nombre del usuario
  • accountNo - string - Número de cuenta del usuario
  • accountType - integer - Tipo de cuenta
  • message - string - Nota

Crear cuenta virtual

POST /vnpay/api/v1/createVirtualCard

Crea una cuenta virtual y devuelve número de cuenta, cadena QRCode y enlace de imagen VietQR.

Campos de solicitud

  • orderNo - string - Requerido - Número de orden de transacción
  • accountName - string - Opcional - Nombre de cuenta virtual
  • phoneNo - string - Opcional - Teléfono del usuario
  • bankCode - string - Opcional - Banco usado para solicitar la cuenta virtual.
  • companyID - string - Requerido - ID de empresa asignado por el backend.
  • merchantID - string - Requerido - ID de comercio asignado por el sistema.
  • timestamp - string - Requerido - Marca de tiempo
  • sign - string - Requerido - Firma
  • totalFee - Long - Opcional - Importe de cobro

Campos de respuesta

  • orderNo - string - Número de orden de transacción
  • bankCode - string - Código bancario
  • accountName - string - Nombre de cuenta
  • accountNo - string - Número de cuenta
  • accountStatus - integer - Estado: 0 cerrada, 1 activa.
  • createdTime - string - Hora de creación
  • expireTime - string - Hora de expiración
  • closeTime - string - Hora de cierre
  • QRCode - String - Datos de cadena del código QR
  • QRImgUrl - String - Enlace de imagen VietQR

Cerrar cuenta virtual

POST /vnpay/api/v1/closeVirtualCard

Cierra la cuenta virtual especificada y devuelve su estado después del cierre.

Campos de solicitud

  • accountNo - string - Opcional - Número de cuenta bancaria devuelto al crear.
  • bankCode - string - Opcional - Código bancario
  • companyID - string - Opcional - ID de empresa asignado por el backend.
  • merchantID - string - Opcional - ID de comercio asignado por el sistema.
  • timestamp - integer - Opcional - Marca de tiempo
  • sign - string - Opcional - Firma

Campos de respuesta

  • bankCode - string - Código bancario
  • accountName - string - Nombre de cuenta
  • accountNo - string - Número de cuenta
  • accountStatus - integer - Estado: 0 cerrada, 1 activa.
  • createdTime - string - Hora de creación
  • expireTime - string - Hora de expiración
  • closeTime - string - Hora de cierre

Consultar cuenta virtual

GET /vnpay/api/v1/queryVirtualCard

Consulta el estado de la cuenta virtual por bankCode, accountName y accountNo.

Campos de solicitud

  • bankCode - string - Sí - Código bancario
  • accountName - string - Sí - Nombre de cuenta
  • accountNo - string - Sí - Número de cuenta
  • companyID - string - Sí - ID de empresa asignado por el backend.
  • merchantID - string - Sí - ID de comercio asignado por el sistema.
  • sign - string - Sí - Firma
  • timestamp - string - Sí - Marca de tiempo

Campos de respuesta

  • bankCode - string - Código bancario
  • accountName - string - Nombre de cuenta
  • accountNo - string - Número de cuenta
  • accountStatus - integer - Estado: 0 cerrada, 1 activa.
  • createdTime - string - Hora de creación
  • expireTime - string - Hora de expiración
  • closeTime - string - Hora de cierre

Consultar saldo de empresa

POST /vnpay/api/v1/queryBalance

Consulta el saldo actual de la cuenta de la empresa.

Campos de solicitud

  • companyID - string - Requerido - ID de empresa asignado por el backend.
  • merchantID - string - Requerido - ID de comercio asignado por el sistema.
  • sign - string - Requerido - Firma
  • timestamp - integer - Requerido - Marca de tiempo

Campos de respuesta

  • companyID - string - ID de empresa asignado por el backend.
  • merchantID - string - ID de comercio asignado por el sistema.
  • balance - string - Saldo actual de la empresa

Crear QR dinámico

POST /vnpay/api/v1/createDynamicQr

Crea un QR dinámico para un importe especificado y devuelve la cadena QR y su expiración.

Campos de solicitud

  • merchantID - string - Requerido - ID de comercio asignado por el sistema.
  • companyID - string - Requerido - ID de empresa asignado por el backend.
  • orderNo - string - Requerido - Número de orden de transacción
  • amount - Long - Requerido - Importe de cobro
  • message - string - Opcional - Nota
  • timestamp - string - Requerido - Marca de tiempo
  • sign - string - Requerido - Firma

Campos de respuesta

  • orderNo - string - Número de orden de transacción
  • amount - Long - Importe de cobro
  • expiresAt - string - Hora de expiración del QR dinámico
  • qrCode - String - Datos de cadena del QR

Callbacks

Notificación de resultado de pago saliente

URL enviada a la API de pago saliente.

Cuando un pago saliente en proceso obtiene resultado final, se llama la URL enviada a la API de pago saliente para notificar.

  • companyID - string - ID de empresa
  • merchantID - string - ID de comercio
  • orderNo - string - Número de orden del comercio
  • tradeNo - string - Número de transacción
  • bankCode - string - Código bancario
  • accountNo - string - Número de cuenta
  • amount - number - Importe de transacción
  • message - string - Nota de pago saliente
  • result - String - Motivo cuando la transacción falla.
  • updateTime - String - Hora de actualización de la transacción
  • status - number - Estado de transacción: 0 éxito, 3 fallida, 4 cancelada.
  • sign - string - Firma

Notificación de resultado de cobro

URL de notificación configurada en el panel del comercio.

Después de que la cuenta virtual recibe fondos, se envía la información de cobro al socio.

  • companyID - string - ID de empresa
  • merchantID - string - ID de comercio
  • orderNo - string - Número de orden del comercio
  • tradeNo - string - Número de transacción
  • bankCode - string - Código bancario
  • accountNo - string - Número de cuenta virtual
  • amount - number - Importe de cobro
  • message - string - Información de transacción devuelta por el sistema de pagos.
  • senderName - string - Pagador
  • senderAccount - string - Cuenta del pagador
  • senderBankCode - string - Código bancario del pagador
  • sign - string - Firma

Notificación de reembolso

URL de notificación de reembolso configurada en el panel del comercio.

Después de que el reembolso de la orden se completa, se envía la información de reembolso al socio.

  • companyID - string - ID de empresa
  • merchantID - string - ID de comercio
  • orderNo - string - Número de orden del comercio
  • tradeNo - string - Número de transacción
  • bankCode - string - Código bancario
  • accountNo - string - Número de cuenta bancaria
  • amount - number - Importe de transacción
  • updateTime - string - Hora de actualización
  • status - string - Estado: 5 reembolsado.
  • sign - string - Firma