Brasil — Descripción general
Brasil (BR) opera con Pix, el sistema de pagos instantáneos del Banco Central do Brasil. Todos los endpoints viven bajo el prefijo /v1/br/*:
- Cobro Pix — genera un QR + “copia e cola” para que el pagador pague desde su banco.
- Pago Pix — envía dinero a una llave Pix o a datos bancarios (banco, agencia, cuenta).
- Saldo y transacciones — consulta tu balance en reales y lista tus operaciones para conciliar.
URL base
Sección titulada «URL base»Brasil y Colombia son despliegues separados: cada país tiene su propia URL.
| Entorno | URL base |
|---|---|
| Producción Brasil | https://api.br.rivopaylatam.com |
| Producción Colombia | https://api.rivopaylatam.com (no sirve rutas /v1/br/*: responde 404) |
La misma cuenta (usuario del panel, clientId) sirve para los dos países; las API keys no.
Requisitos de la cuenta
Sección titulada «Requisitos de la cuenta»- Brasil habilitado en tu cuenta (lo activa Rivopay). Sin eso el panel no te deja crear keys
BRy la API responde403. - Producción habilitada en Brasil para operar en producción. Si no:
403"Producción no habilitada para esta cuenta". - Tarifa de Brasil configurada (cobros y pagos por separado). Si no:
409FEE_NOT_CONFIGURED.
API key
Sección titulada «API key»La autenticación usa los mismos headers firmados con ECDSA secp256k1 (v2) que Colombia. Ver Firma ECDSA.
- La API key es por país. Al crearla en el panel eliges la región: una key
BRsolo firma rutas/v1/br/*. Con una keyCO, las rutas de Brasil responden403. - IP whitelist obligatoria en la key (lista vacía = ninguna IP autorizada).
| Header | Descripción |
|---|---|
x-client-id | ID de la API Key (región BR) |
x-timestamp | ISO 8601 actual |
x-nonce | String único por request (un solo uso) |
x-signature | Firma ECDSA-SHA256 en Base64 |
x-content-sha256 | SHA-256 del body en hex minúscula (si la key exige hash del cuerpo) |
x-idempotency-key | Obligatoria en los POST que mueven dinero. Ver Idempotencia |
Formato de respuestas
Sección titulada «Formato de respuestas»Todas las respuestas viajan envueltas:
{ "success": true, "data": { "…": "…" }, "requestId": "…" }{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "…", "details": { } }, "requestId": "…" }En los ejemplos de estas páginas se muestra solo el contenido de data. Los campos extra de un error (p. ej. availableBalance en el 402) van en error.details.
Índice de endpoints
Sección titulada «Índice de endpoints»| Método | Path | Descripción |
|---|---|---|
POST | /v1/br/payin/pix/instant | Crear cobro Pix (QR + copia e cola) |
GET | /v1/br/payin/pix/{txId} | Estado de un cobro |
POST | /v1/br/payout/pix/key | Pago a una llave Pix |
POST | /v1/br/payout/pix/bank | Pago a datos bancarios |
GET | /v1/br/payout/pix/{txId} | Estado de un pago |
POST | /v1/br/payin/pix/{txId}/reversal | Devolución total o parcial de un cobro |
GET | /v1/br/balance | Saldo en Brasil |
GET | /v1/br/transactions | Listado de cobros y pagos |
Estados
Sección titulada «Estados»Cobro: PENDING → COMPLETED | FAILED | REVERSED
| Estado | Significado |
|---|---|
PENDING | QR generado, esperando pago |
COMPLETED | Pago confirmado — el monto neto se acreditó en tu saldo |
FAILED | Rechazado, o vencido sin pago (se notifica con payin.expired) |
REVERSED | Devuelto al pagador (lo ejecuta Rivopay) |
El cobro no vence por reloj: lo cierra la red Pix (por notificación o por consulta). Si la red lo da por vencido, queda FAILED y recibes el evento payin.expired.
Pago: PENDING (instante interno) → PROCESSING → COMPLETED | FAILED | REVERSED
| Estado | Significado |
|---|---|
PROCESSING | Enviado a la red, esperando confirmación |
COMPLETED | Pago acreditado — saldo debitado |
FAILED | Rechazado — el saldo retenido se libera |
REVERSED | Devuelto por el banco receptor |
El pago no vence por tiempo: si la red tarda, sigue en PROCESSING hasta que confirme.
Idempotencia
Sección titulada «Idempotencia»- Header
X-Idempotency-Keyobligatorio enPOST /v1/br/payin/pix/instant,/v1/br/payout/pix/keyy/v1/br/payout/pix/bank. - Máximo 128 caracteres; solo
A-Z a-z 0-9 _ - : . - La clave es por aliado y queda atada al cuerpo: misma clave + mismo cuerpo = reintento seguro (devuelve la operación original con
200); misma clave + cuerpo distinto =422. - Vigencia: 90 días.
error.code | HTTP | Cuándo |
|---|---|---|
IDEMPOTENCY_KEY_REQUIRED | 400 | Falta el header |
IDEMPOTENCY_KEY_INVALID | 400 | Formato inválido |
IDEMPOTENCY_KEY_REUSED | 422 | Clave ya usada con otro cuerpo |
IDEMPOTENCY_IN_FLIGHT | 409 | La primera petición con esa clave aún se está procesando |
Ver también la guía general de Idempotencia.
Errores
Sección titulada «Errores»| HTTP | error.code | Cuándo |
|---|---|---|
400 | VALIDATION_ERROR | Campos faltantes o inválidos (monto, amountFormat, amountType, expirationInSeconds, txIdSource fuera de 26–35, pixKeyType, accountType, monto > R$ 1.000.000) |
400 | IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID | Ver Idempotencia |
401 | — | Falta X-Client-Id. Sin envoltorio: {"message":"Unauthorized"} |
403 | — | Cualquier otro fallo de autenticación: firma, timestamp, nonce repetido, IP no autorizada, key de otro país, Brasil no habilitado. Sin envoltorio: {"message":"Forbidden"} |
402 | INSUFFICIENT_FUNDS | Pago sin saldo; details: availableBalance, requiredAmount, currency |
403 | FORBIDDEN | Producción no habilitada para la cuenta (con envoltorio) |
404 | NOT_FOUND | Transacción inexistente o de otro aliado |
409 | FEE_NOT_CONFIGURED | Cuenta sin tarifa de Brasil |
409 | IDEMPOTENCY_IN_FLIGHT | Ver Idempotencia |
422 | PROVIDER_REJECTED | Monto fuera de los límites de tu tarifa ("El monto está fuera del rango permitido para este medio de pago") |
422 | PROVIDER_REJECTED | La red rechazó la operación (p. ej. llave Pix inexistente). Causas frecuentes: ver Errores de Pix |
422 | IDEMPOTENCY_KEY_REUSED | Ver Idempotencia |
502 | PROVIDER_ERROR | Red no disponible. En reversos: estado desconocido, no reintentes con otra clave. Al crear un pago no se usa: la falta de confirmación devuelve 202 PENDING |
503 | SERVICE_UNAVAILABLE | Servicio suspendido para la cuenta |