Cobrar un monto exacto

Un pago único por el monto de tu orden. PIX en Brasil y transferencia bancaria en Perú.

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.

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

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" }
  }'

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:

{
  "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.

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.

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.

Esperar el pago

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

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

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

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.

Las instruccionesCopiar enlace

Esperar el pagoCopiar enlace

Errores al crearCopiar enlace

En esta página

Las instrucciones

Esperar el pago

Errores al crear