Pagos
La API de pagos ofrece un contrato normalizado aunque cada procesador use protocolos y estados diferentes. Las rutas aceptan API key o JWT de usuario. Con API key, el método debe estar habilitado para esa key; con JWT, operás sobre métodos propios del owner en el ambiente del deploy.
Endpoints
POST /v1/payments
GET /v1/payments/{payment_id}
POST /v1/payments/{payment_id}/cancel
POST /v1/payments/{payment_id}/refunds| Operación | Scope (API key) | Idempotency-Key |
|---|---|---|
| Crear | payments:create |
Obligatoria |
| Consultar | payments:read |
No aplica |
| Cancelar | payments:cancel |
Obligatoria |
| Reembolso | refunds:create |
Obligatoria |
Los reembolsos se documentan en Reembolsos.
Crear un pago
POST /v1/payments
Authorization: Bearer sk_live_7nWm...
Idempotency-Key: order-9821-payment-1
Content-Type: application/jsonBody
Campos requeridos: amount, external_reference, payment_method.
{
"amount": {
"value": "12500.00",
"currency": "ARS"
},
"external_reference": "order-9821",
"description": "Pedido #9821",
"payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
"metadata": {
"location_id": "019f705a-b885-7acf-b557-71406da93cff"
},
"configuration": {
"id_terminal": "123123123",
"id_sucursal": "123123"
},
"webhook_url": "https://example.com/webhook"
}| Campo | Uso |
|---|---|
amount |
Monto como string decimal + moneda ISO 4217. |
external_reference |
Referencia única por API key. |
payment_method |
UUID del método habilitado. |
description |
Opcional; texto visible en el pago. |
metadata |
Opcional; objeto libre no sensible. |
configuration |
Opcional; se valida contra el schema del método y hace merge sobre sus defaults. |
webhook_url |
Opcional; URL HTTPS para webhooks de este pago. |
El método debe estar activo y declarar capability payments. external_reference es única por API key: si ya existe, la API responde external_reference_conflict.
Response — QR pendiente
{
"data": {
"id": "019f7061-2010-7698-8827-e32f86e14298",
"status": "pending",
"amount": {
"value": "12500.00",
"currency": "ARS"
},
"external_reference": "order-9821",
"payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
"processor_reference": "qrg_854843903",
"action": {
"type": "display_qr",
"qr_data": "00020101021243650016COM.GETNET..."
},
"created_at": "2026-07-17T13:15:00.000Z",
"updated_at": "2026-07-17T13:15:01.121Z"
}
}Cómo interpretar action
action describe una acción que la aplicación debe realizar para continuar el flujo:
| Tipo | Comportamiento del cliente |
|---|---|
none |
No hay una acción adicional. Leer status. |
display_qr |
Mostrar qr_data sin alterarlo y esperar confirmación. |
Los clientes deben tolerar tipos futuros. La presencia de una acción no implica aprobación.
Response — POS aprobado
{
"data": {
"id": "019f7061-2010-7698-8827-e32f86e14298",
"status": "approved",
"amount": {
"value": "12500.00",
"currency": "ARS"
},
"external_reference": "order-9821",
"payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
"processor_reference": "trx_739204",
"action": {
"type": "none"
},
"created_at": "2026-07-17T13:15:00.000Z",
"updated_at": "2026-07-17T13:15:08.441Z"
}
}declined es un resultado de negocio concluyente y no debe reintentarse automáticamente. Una nueva tentativa requiere otra referencia externa.
Consultar un pago
GET /v1/payments/019f7061-2010-7698-8827-e32f86e14298
Authorization: Bearer sk_live_7nWm...Response
{
"data": {
"id": "019f7061-2010-7698-8827-e32f86e14298",
"status": "approved",
"amount": {
"value": "12500.00",
"currency": "ARS"
},
"external_reference": "order-9821",
"payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
"processor_reference": "trx_739204",
"created_at": "2026-07-17T13:15:00.000Z",
"updated_at": "2026-07-17T13:15:08.441Z"
}
}Cancelar un pago
POST /v1/payments/019f7061-2010-7698-8827-e32f86e14298/cancel
Authorization: Bearer sk_live_7nWm...
Idempotency-Key: order-9821-cancel-1Sin body. Scope: payments:cancel. El método debe tener capability cancellations.
Response
{
"data": {
"id": "019f7061-2010-7698-8827-e32f86e14298",
"status": "canceled",
"amount": {
"value": "12500.00",
"currency": "ARS"
},
"external_reference": "order-9821",
"payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
"processor_reference": "trx_739204",
"created_at": "2026-07-17T13:15:00.000Z",
"updated_at": "2026-07-17T13:16:02.000Z"
}
}Estados
created
pending
processing
approved
declined
failed
expired
canceled
partially_refunded
refundedUn timeout puede dejar el pago en pending o failed según las garantías del procesador. Nunca asumir declined sin una respuesta concluyente.
Transiciones y estados finales
created, pending y processing son estados no finales. approved, declined, failed, expired y canceled describen resultados del cobro; partially_refunded y refunded reflejan devoluciones posteriores.
No fuerces transiciones en tu base local solo por el orden de llegada. Un webhook atrasado no debe hacer retroceder un pago final. Compará updated_at, aplicá transiciones válidas y reconciliá por GET cuando haya dudas.
Webhooks y consulta
webhook_url define el destino para las novedades de este pago. La respuesta REST puede ser provisional y la entrega del webhook es asíncrona. Procesá eventos duplicados, fuera de orden y demorados; mantené GET /v1/payments/{payment_id} como reconciliación.
Manejo de errores
| Error | Acción recomendada |
|---|---|
external_reference_conflict |
Recuperar el pago original; no cambiar solo la idempotency key. |
payment_method_not_found |
Volver a listar métodos habilitados y revisar ambiente. |
unsupported_currency |
Corregir moneda o elegir otro método. |
processor_declined |
Mostrar un rechazo de negocio; no hacer retry automático. |
processor_timeout |
Conservar la intención y reconciliar; no asumir rechazo. |
processor_unavailable |
Reintentar solo si retryable es true, con la misma key y body. |
connector_configuration_invalid |
Escalar al administrador; no se corrige desde el request del pago. |
Reembolsos: ver Reembolsos.