Ir al contenido

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.

Brasil y Colombia son despliegues separados: cada país tiene su propia URL.

EntornoURL base
Producción Brasilhttps://api.br.rivopaylatam.com
Producción Colombiahttps://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.

  • Brasil habilitado en tu cuenta (lo activa Rivopay). Sin eso el panel no te deja crear keys BR y la API responde 403.
  • 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: 409 FEE_NOT_CONFIGURED.

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 BR solo firma rutas /v1/br/*. Con una key CO, las rutas de Brasil responden 403.
  • IP whitelist obligatoria en la key (lista vacía = ninguna IP autorizada).
HeaderDescripción
x-client-idID de la API Key (región BR)
x-timestampISO 8601 actual
x-nonceString único por request (un solo uso)
x-signatureFirma ECDSA-SHA256 en Base64
x-content-sha256SHA-256 del body en hex minúscula (si la key exige hash del cuerpo)
x-idempotency-keyObligatoria en los POST que mueven dinero. Ver Idempotencia

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.

MétodoPathDescripción
POST/v1/br/payin/pix/instantCrear cobro Pix (QR + copia e cola)
GET/v1/br/payin/pix/{txId}Estado de un cobro
POST/v1/br/payout/pix/keyPago a una llave Pix
POST/v1/br/payout/pix/bankPago a datos bancarios
GET/v1/br/payout/pix/{txId}Estado de un pago
POST/v1/br/payin/pix/{txId}/reversalDevolución total o parcial de un cobro
GET/v1/br/balanceSaldo en Brasil
GET/v1/br/transactionsListado de cobros y pagos

Cobro: PENDING → COMPLETED | FAILED | REVERSED

EstadoSignificado
PENDINGQR generado, esperando pago
COMPLETEDPago confirmado — el monto neto se acreditó en tu saldo
FAILEDRechazado, o vencido sin pago (se notifica con payin.expired)
REVERSEDDevuelto 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

EstadoSignificado
PROCESSINGEnviado a la red, esperando confirmación
COMPLETEDPago acreditado — saldo debitado
FAILEDRechazado — el saldo retenido se libera
REVERSEDDevuelto por el banco receptor

El pago no vence por tiempo: si la red tarda, sigue en PROCESSING hasta que confirme.

  • Header X-Idempotency-Key obligatorio en POST /v1/br/payin/pix/instant, /v1/br/payout/pix/key y /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.codeHTTPCuándo
IDEMPOTENCY_KEY_REQUIRED400Falta el header
IDEMPOTENCY_KEY_INVALID400Formato inválido
IDEMPOTENCY_KEY_REUSED422Clave ya usada con otro cuerpo
IDEMPOTENCY_IN_FLIGHT409La primera petición con esa clave aún se está procesando

Ver también la guía general de Idempotencia.

HTTPerror.codeCuándo
400VALIDATION_ERRORCampos faltantes o inválidos (monto, amountFormat, amountType, expirationInSeconds, txIdSource fuera de 26–35, pixKeyType, accountType, monto > R$ 1.000.000)
400IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALIDVer 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"}
402INSUFFICIENT_FUNDSPago sin saldo; details: availableBalance, requiredAmount, currency
403FORBIDDENProducción no habilitada para la cuenta (con envoltorio)
404NOT_FOUNDTransacción inexistente o de otro aliado
409FEE_NOT_CONFIGUREDCuenta sin tarifa de Brasil
409IDEMPOTENCY_IN_FLIGHTVer Idempotencia
422PROVIDER_REJECTEDMonto fuera de los límites de tu tarifa ("El monto está fuera del rango permitido para este medio de pago")
422PROVIDER_REJECTEDLa red rechazó la operación (p. ej. llave Pix inexistente). Causas frecuentes: ver Errores de Pix
422IDEMPOTENCY_KEY_REUSEDVer Idempotencia
502PROVIDER_ERRORRed 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
503SERVICE_UNAVAILABLEServicio suspendido para la cuenta