# Cobrar un monto exacto (/docs/collect-one-payment)

<Endpoint method="POST" path="/v1/funding-accounts" href="/docs/api/funding/create-funding-account" />

Con `amount`, la cuenta de cobro es un **pago único**: tu cliente paga exactamente ese monto, en la moneda de `currency`, y la cuenta se cierra cuando el pago termina.

| Campo | Obligatorio | Qué es |
| --- | --- | --- |
| `method` | Sí | `pix`, `bank_transfer`… |
| `currency` | Sí | Lo que paga tu cliente: `BRL`, `PEN`… |
| `amount` | Sí, en un pago único | El monto de tu orden. |
| `payer` | Según el método | Los datos del pagador que pide `payment_method_fields` en capabilities. |
| `settlement_currency` | No | En qué moneda se acredita tu saldo. Por defecto, el `settlement_asset` de capabilities. |

<Tabs items={["Brasil · PIX", "Perú · transferencia"]}>
<Tab value="Brasil · PIX">

PIX pide el nombre del pagador. La clave de `payer` es el nombre completo del campo, tal como lo da capabilities: `payer.name`.

```bash
curl "$CAIBO_API/v1/funding-accounts" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Idempotency-Key: cobro-orden-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "currency": "BRL",
    "amount": "250.00",
    "payer": { "payer.name": "Ana Souza" }
  }'
```

```json title="201"
{
  "id": "fa_01m3sg9w0000000000000000",
  "status": "pending",
  "method": "pix",
  "currency": "BRL",
  "settlement_currency": "USDT",
  "amount": "250.00",
  "created_at": "2026-10-18T12:00:00Z"
}
```

Cuando está `active`:

```json
{
  "id": "fa_01m3sg9w0000000000000000",
  "status": "active",
  "method": "pix",
  "currency": "BRL",
  "settlement_currency": "USDT",
  "amount": "250.00",
  "instructions": {
    "copy_paste_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "amount": "250.00",
    "currency": "BRL"
  },
  "created_at": "2026-10-18T12:00:00Z"
}
```

Muestra el QR (`qr_code_image_base64`, una imagen PNG en base64) y el código **PIX copia e cola** (`copy_paste_code`) para que tu cliente pague desde su banco.

</Tab>
<Tab value="Perú · transferencia">

En soles no hace falta ningún dato del pagador.

```bash
curl "$CAIBO_API/v1/funding-accounts" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Idempotency-Key: cobro-orden-8813" \
  -H "Content-Type: application/json" \
  -d '{ "method": "bank_transfer", "currency": "PEN", "amount": "1000.00" }'
```

Cuando está `active`:

```json
{
  "id": "fa_01m3sgaa0000000000000000",
  "status": "active",
  "method": "bank_transfer",
  "currency": "PEN",
  "settlement_currency": "USDT",
  "amount": "1000.00",
  "instructions": {
    "bank_account": "Banco … · Cuenta …",
    "expires_at": "2026-10-18T12:25:00Z",
    "amount": "1000.00",
    "currency": "PEN"
  },
  "created_at": "2026-10-18T12:00:00Z"
}
```

Muestra `bank_account` y el monto. Tu cliente debe transferir **el monto exacto**, antes de `expires_at`. Si `instructions` trae `reference`, pídele que la incluya en la transferencia.

</Tab>
</Tabs>

## Las instrucciones [#las-instrucciones]

`instructions` es un mapa de texto cuyas claves dependen del método. Muéstralas tal cual a quien va a pagar:

| Clave | Qué es |
| --- | --- |
| `amount`, `currency` | Lo que se paga: siempre el monto de tu orden. |
| `copy_paste_code` | El código para pegar en la app del banco (PIX copia e cola). |
| `qr_code_image_base64` | El QR, como imagen PNG en base64. |
| `bank_account` | La cuenta a la que transferir. |
| `reference` | La referencia que debe incluir la transferencia. |
| `payment_url` | Un enlace para pagar. |
| `expires_at` | Hasta cuándo se puede pagar, si el método vence. |

Puede aparecer una clave nueva en el futuro. Muéstrala o ignórala, pero no falles por ella.

<Callout title="Sin comisiones para tu cliente">
`instructions.amount` es siempre el monto de tu orden. Si el banco cobra por recibir, Caibo absorbe esa comisión: tu cliente paga 1,000.00 y no 1,002.70, y tu saldo recibe lo que valen los 1,000.00 completos.
</Callout>

## Esperar el pago [#esperar-el-pago]

Escucha los webhooks, o consulta la cuenta y sus eventos:

1. `funding_account.active` trae `instructions`. El monto está en `instructions.amount`; el `amount` de la cuenta está en `GET /v1/funding-accounts/{id}`.
2. `payin.completed` llega cuando el banco confirma el pago. Su `data` es el [cobro acreditado](/docs/payins), con lo que entró a tu saldo.
3. Si el pago vence o no se concreta, llega `payin.failed` y la cuenta pasa a `closed`.

```bash
curl "$CAIBO_API/v1/events?resource_id=fa_01m3sg9w0000000000000000" \
  -H "Authorization: Bearer $CAIBO_API_KEY"
```

## Errores al crear [#errores-al-crear]

| HTTP | `code` | Por qué |
| --- | --- | --- |
| 400 | `invalid_parameter` · `payer` | Falta un dato del pagador, no se reconoce o tiene mal formato. O enviaste `payer` sin `amount`. |
| 400 | `invalid_request` | `amount` no es un decimal positivo o la moneda no existe. |
| 422 | `amount_required` | Ese método y moneda se cobran con monto: envía `amount`. |
| 422 | `one_payment_unavailable` | Ese método y moneda abren una cuenta sin monto: no envíes `amount`. |
| 422 | `unsupported_method` | Ese método y moneda no están disponibles para cobrar. |
| 503 | `operation_suspended` | Está suspendido por ahora. |

Si la cuenta no se puede abrir, se crea igual y pasa a `failed` con `failure_code` (`provider_rejected`, `provider_unavailable`, `provider_amount_mismatch`, `no_route`). En ese caso crea otra, con un `Idempotency-Key` nuevo.