Saltar al contenido principal

Pagos (Pay In)

Este módulo permite a los Proveedores de Pago (Payment Providers) procesar órdenes de cobro en efectivo creadas por comercios para sus usuarios. Al igual que en los retiros, este flujo utiliza un mecanismo de bloqueo (locking) para evitar que una misma orden sea cobrada dos veces por distintos proveedores simultáneamente.

Firma cada petición con HMAC SHA-256, revisa el formato de errores para manejar respuestas no exitosas y consulta los países y monedas soportados. Si eres nuevo, empieza por la introducción para Proveedores.

Endpoint base

Todas las rutas descritas a continuación son relativas a la URL base de la API: /api/v1

Registro de redes de pago​

Antes de procesar transacciones, los proveedores deben registrar las redes de pago que utilizan. Cada red debe tener un identificador único (network_id) que se utilizará en todas las transiciones de estado.

Ejemplos de IDs de red:

  • 01
  • oxxo_network
  • seven_eleven_mx
  • farmacia_abc
  • network_123
Contacto

Para registrar tus redes de pago, contacta a tu ejecutivo comercial o escríbenos a contacto@pago46.com. Los IDs que proporciones serán los que deberás usar en las solicitudes de cobro.

Ciclo de vida de la orden​

El proceso asegura que el dinero sea recolectado y conciliado correctamente antes de liberar el servicio al usuario final.

  1. Consulta: El proveedor escanea o ingresa el código presentado por el usuario para ver el monto a cobrar y validar que el estado sea READY.
  2. Bloqueo: El proveedor "toma" la orden. El estado cambia a PAYMENT_STARTED. Esto asegura la intención de cobro.
  3. Confirmación: Una vez que el usuario entrega el efectivo y este ingresa a la caja, el proveedor confirma la transacción (estado COMPLETED).

1. Verificar orden​

Cuando el cliente se acerca a la caja para pagar, debes consultar el código para informar el monto exacto a cobrar.

Endpoint: GET /providers/orders/pay-in/{code}/

ParámetroUbicaciónDescripción
codePathEl código de pago presentado por el usuario (numérico o QR).
curl -X GET "https://api.dev.pago46.io/api/v1/providers/orders/pay-in/9876543210/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"
Validación de estado

Verifica siempre que el status sea READY. Si la orden está EXPIRED o COMPLETED, no debes recibir dinero del usuario.

2. Iniciar cobro (bloqueo)​

Antes de recibir el dinero, debes informar a Pago46 que estás atendiendo esta orden. Esto evita que el usuario intente pagar el mismo código en otro proveedor al mismo tiempo.

Endpoint: POST /providers/orders/pay-in/{code}/start-payment/

curl -X POST "https://api.dev.pago46.io/api/v1/providers/orders/pay-in/9876543210/start-payment/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'
CampoTipoDescripción
network_idstringID de la red de pago utilizada por el proveedor. Requerido.
pricestringOpcional. Si lo envías, debe coincidir con el price de la orden.
price_currencystringOpcional. Si lo envías, debe coincidir con el price_currency de la orden.
Subredes para proveedores

Como proveedor, debes suministrar el network_id que identifica la red específica utilizada para procesar esta transacción. Esto permite a Pago46 mantener un registro detallado de qué red procesó cada pago y proporcionar esta información al usuario final.

Momento del cobro

Una vez recibas el estado PAYMENT_STARTED, puedes proceder a solicitar y recibir el dinero del cliente con seguridad.

3. Confirmar cobro (finalización)​

Una vez que el dinero esté seguro en tu caja, confirma la transacción. En ese momento, Pago46 notificará al comercio que creó la orden para que entregue el producto o servicio al usuario.

Endpoint: POST /providers/orders/pay-in/{code}/confirm-payment/

curl -X POST "https://api.dev.pago46.io/api/v1/providers/orders/pay-in/9876543210/confirm-payment/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

Cancelación​

Si el usuario decide no pagar en el último momento o hay un problema con el efectivo, debes liberar la orden. Solo puedes hacerlo si la orden está en PAYMENT_STARTED y tu proveedor fue quien la bloqueó. Si otro proveedor la bloqueó, no puedes actuar sobre ella. Al liberarla, vuelve a READY para que pueda procesarse nuevamente.

Endpoint: POST /providers/orders/pay-in/{code}/cancel-payment/

curl -X POST "https://api.dev.pago46.io/api/v1/providers/orders/pay-in/9876543210/cancel-payment/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

Resumen de estados​

EstadoDescripciónAcción requerida del proveedor
READYLa orden está pendiente de pago.Verificar monto y llamar a start-payment.
PAYMENT_STARTEDLa orden está en proceso de cobro.Recibir dinero y llamar a confirm-payment.
COMPLETEDEl dinero fue recaudado exitosamente.Entregar comprobante al usuario.
CANCELLEDLa orden fue cancelada.No recibir dinero.