Ir al contenido

Primeros pasos

En esta página

Pruebas

Prueba los cambios de estado de facturas y retiros con claves de prueba dedicadas, webhooks firmados y endpoints de simulación que no mueven fondos reales.

Prueba tu integración de extremo a extremo en Sandbox. La misma superficie de API que en producción, blockchain simulada, webhooks firmados y ningún dinero real en juego.

Sandbox y producción

Aspecto Sandbox Producción
URL base api.paymos.io/v1 api.paymos.io/v1
Claves de API IDs pk_test_ / rk_test_ con secretos sk_test_ IDs pk_live_ / rk_live_ con secretos sk_live_
Transacciones Simuladas Blockchain real
Webhooks Se envían con normalidad Se envían con normalidad
Fondos Sin valor real Cripto real

Simular pagos

Los pagos de Sandbox no se confirman solos por temporizador. Dispáralos de forma explícita:

POST/v1/sandbox/invoices/:invoice_id/simulate-payment

Cuerpo: { "stage": "paid" }. stage admite uno de estos valores: paid, overpaid, underpay o cancel. Autentícalo como cualquier otra llamada firmada a /v1; actúa únicamente sobre facturas de Sandbox, así que una clave de producción se rechaza con 403 not_sandbox. Dispara los mismos eventos de ciclo de vida y de webhook que un pago real en cadena, de modo que tu ruta de verificación es idéntica en Sandbox y en producción.

Simular retiros

Los retiros de Sandbox no se liquidan en una cadena real. Marca como completado un retiro pendiente de Sandbox para ejercitar todo tu flujo de pagos salientes:

POST/v1/sandbox/withdrawals/:withdrawal_id/simulate-completion

Sin cuerpo de petición. Autentícalo como cualquier otra llamada a /v1 con tu clave Payout; actúa únicamente sobre retiros de Sandbox. Lleva el retiro a completed y emite el mismo webhook withdrawal.completed que un envío real en cadena, de modo que tu ruta de conciliación es idéntica en Sandbox y en producción.

Simular depósitos en canales

Los canales de pago de Sandbox derivan sus direcciones en local y no vigilan ninguna cadena, así que los depósitos se crean de forma explícita:

POST/v1/sandbox/payment-channels/:payment_channel_id/simulate-deposit

Cuerpo: { "amount": "100", "currency": "USDT", "network": "TRC20", "stage": "confirmed" }. stage admite confirming, reorged o confirmed, y sin indicarlo vale confirmed. Fírmalo con tu clave Payment de Sandbox; una clave de producción se rechaza antes de crear nada. Cada llamada emite primero payment_channel.deposit.confirming, y la etapa que pediste decide qué evento llega después, de modo que tu ruta de webhooks es idéntica en Sandbox y en producción. El contrato completo está en Simular un depósito en el canal.

Probar webhooks en local

Expón tu servidor local a través de un túnel:

ngrok http 3000

Fija la URL del webhook en Panel → Desarrollador → Webhooks:

https://abc123.ngrok.io/api/paymos-webhook

Consola de webhooks

La documentación incluye una Consola disponible solo en Sandbox que entrega un evento completamente firmado a la URL que tengas registrada; resulta útil para verificar el tratamiento de la firma sin crear una factura.

  • 01Ve a Panel → Desarrollador → Documentación en el entorno de Sandbox
  • 02Abre Webhooks → Pruebas y selecciona la pestaña Consola
  • 03Elige un tipo de evento (invoice.paid, invoice.expired, withdrawal.completed, etc.) y pulsa Simula
  • 04Revisa los registros de tu servidor para ver el evento recibido y la cabecera X-Webhook-Signature

Lista de comprobación antes de pasar a producción

  • ☐La verificación de la firma del webhook funciona
  • ☐La creación de facturas devuelve los datos correctos
  • ☐El flujo de pago redirige correctamente
  • ☐El tratamiento de errores cubre las respuestas fuera de 2xx (validación 4xx, conflictos 409)
  • ☐La idempotencia con external_order_id funciona
  • ☐Cambiar los IDs de clave de pk_test_ / rk_test_ a pk_live_ / rk_live_, y los secretos de sk_test_ a sk_live_
Flujo de pago Autenticación