---
title: "Pagos"
description: "Crear, consultar y cancelar pagos con Idempotency-Key, estados normalizados y acciones (p.ej. display_qr)."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.pagofast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagos

# 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

```http
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](/resources/refunds).

## Crear un pago

```http
POST /v1/payments
Authorization: Bearer sk_live_7nWm...
Idempotency-Key: order-9821-payment-1
Content-Type: application/json
```

### Body

Campos requeridos: `amount`, `external_reference`, `payment_method`.

```json
{
  "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

```json
{
  "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

```json
{
  "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

```http
GET /v1/payments/019f7061-2010-7698-8827-e32f86e14298
Authorization: Bearer sk_live_7nWm...
```

### Response

```json
{
  "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

```http
POST /v1/payments/019f7061-2010-7698-8827-e32f86e14298/cancel
Authorization: Bearer sk_live_7nWm...
Idempotency-Key: order-9821-cancel-1
```

Sin body. Scope: `payments:cancel`. El método debe tener capability `cancellations`.

### Response

```json
{
  "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

```text
created
pending
processing
approved
declined
failed
expired
canceled
partially_refunded
refunded
```

Un 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](/resources/refunds).

Source: https://docs.pagofast.com/resources/payments/index.mdx