Introducción
Pix Automático de Belvo es un método de pago recurrente establecido por el Banco Central de Brasil que simplifica cómo se inician las transferencias recurrentes de Pix al permitir que se procesen automáticamente después de una autorización única del usuario final (pagador).
Una vez autorizado, el comerciante puede iniciar pagos recurrentes subsecuentes sin requerir aprobación individual para cada transacción. Estos pagos recurrentes pueden configurarse para montos fijos o variables, dependiendo de la lógica específica del negocio.
Con Pix Automático, puedes seleccionar solicitar pagos por el mismo monto de tu usuario cada vez (Fijo) o establecer un monto variable (Variable).
- Fijo = Suscripciones recurrentes estables (como Netflix, Spotify, gimnasios)
- Variable = Suscripciones medidas (como electricidad, agua, gas)
En esta guía, aprenderás:
- Los requisitos previos que necesitas completar antes de hacer cualquier otra cosa.
- Cómo configurar una Autorización de Pago
- Cómo solicitar el pago de tus clientes (Cargos)
Requisitos previos
El recurso de Autorización de Pago requiere que envíes el encabezado X-Belvo-API-Resource-Version
configurado en Payments-BR.V2
.
Asegúrate de haber completado todos los pasos en nuestro artículo dedicado a los requisitos previos antes de continuar con esta guía. La guía te llevará a través de cómo:
- Configurar webhooks (requerido ya que nuestras soluciones de pago utilizan webhooks para informarte sobre el progreso de tus pagos, cualquier error que ocurra y cuando un pago se completa con éxito).
- Crear una cuenta bancaria de beneficiario (requerido para recibir fondos de pago).
- Configurar una URL de retorno (callback) (requerido ya que después de que tu usuario autorice su pago, necesita ser redirigido a tu aplicación).
Descripción general del flujo
Como puedes ver en el diagrama a continuación, el flujo de datos para crear un pago usando Pix Automático involucra:
- Crear una Autorización de Pago.
- Redirigir a tu usuario a la
authorization_url
para que pueda confirmar esa Autorización de Pago. Una vez confirmada, son redirigidos a lareturn_url
que proporcionaste. - Esperar un webhook
PAYMENT_AUTHORIZATION
con elstatus
configurado aAUTHORIZED
. - Solicitar el Cargo al menos dos días antes de que deba ocurrir el pago.
- El día del pago, esperar un webhook
CHARGES
con elstatus
configurado aSETTLED
.

Creando una Autorización de Pago
Una Autorización de Pago es el consentimiento que tu usuario te da para cargar (debitando dinero de) sus cuentas. Necesitas realizar una Autorización de Pago por cada ‘contrato’ (por ejemplo, si tu empresa maneja tanto electricidad como agua pero se facturan por separado, entonces crearás dos Autorizaciones de Pago separadas).
POST /payment-authorizations/
{
"payment_method": "PIX_OF_AUTOMATIC_FIXED",
"description": "Monthly gym subscription payment",
"external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
"return_url": "https://merchant.com/return",
"payer": {
"customer": {
"identifier": "12345678901",
"name": "João da Silva",
"external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73"
},
"institution": "ef685cf7-d143-4671-a1e5-4d1d019a3f5c",
"representative_identifier": "12345678901234"
},
"beneficiary": {
"type": "BANK_ACCOUNT",
"target": {
"holder": {
"identifier": "12345678901122",
"name": "Frangos Enlatados"
},
"details": {
"account_type": "CHECKINGS",
"agency": "0444",
"institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
"number": "457220"
},
"external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
"metadata": {
"internal_reference_id": "GGq73487w2"
}
}
},
"payment_method_configuration": {
"amount": 3000.01,
"statement_description": "Monthly Gym - Premium Plan",
"frequency": "MONTHLY",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"contract_id": "PREMIUMPLAN123456",
"contract_debtor": {
"identifier": "12345678901",
"name": "João da Silva"
},
"retries": true,
"first_payment": {
"date": "2025-05-15",
"amount": 3000.01
}
},
"metadata": {
"internal_reference_id": "GGq73487w2"
}
}
El método de pago a autorizar. Para pagos fijos, esto debe establecerse en PIX_OF_AUTOMATIC_FIXED
.
Una descripción interna para el comerciante.
(Muy Recomendado) El ID interno del comerciante para la autorización.
La URL a la que el usuario debe ser redirigido después de autorizar el pago en la institución.
Detalles sobre el pagador.
Detalles del cliente que realiza pagos al beneficiario. Puedes proporcionar el CPF o CNPJ del cliente, o su Belvo ID. Si proporcionas el Belvo ID, debe ser un UUID de un cliente que ya ha sido creado en Belvo. Si proporcionas el CPF o CNPJ, verificaremos si el cliente existe en Belvo. Si el cliente existe, devolvemos su Belvo ID. Si no, creamos un nuevo cliente y devolvemos el Belvo ID recién asignado.
Detalles del cliente que realiza pagos al beneficiario. Si el cliente existe, devolvemos su ID de Belvo. Si no, creamos un nuevo cliente y devolvemos el ID de Belvo recién asignado.
El CPF o CNPJ del cliente. Para CPF, debe tener 11 caracteres. Para CNPJ, debe tener 14 caracteres.
El nombre completo del cliente.
Un identificador único adicional para el recurso con fines internos.
👍 Altamente recomendado
Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
El ID de Belvo de la institución que el pagador utilizará para pagar el servicio del comerciante. Para obtener el ID de Belvo de una institución, utiliza el endpoint de Instituciones.
En el caso de que el cliente sea una empresa, este es el CPF del representante autorizado para realizar pagos en nombre de la empresa.
Detalles sobre el beneficiario del pago.
El tipo de cuenta del beneficiario. Actualmente, esto debe establecerse en BANK_ACCOUNT
.
Detalles sobre la cuenta bancaria que recibirá los fondos. Puedes proporcionar los detalles completos de la cuenta bancaria o el Belvo ID. Si proporcionas los detalles completos de la cuenta bancaria, verificaremos si la cuenta bancaria existe en Belvo. Si la cuenta bancaria existe, devolveremos su Belvo ID. Si no, crearemos una nueva cuenta bancaria y devolveremos el Belvo ID asignado recientemente.
Detalles de la cuenta bancaria que se va a registrar. Si la cuenta bancaria existe, devolvemos su ID de Belvo. Si no, creamos una nueva cuenta bancaria y devolvemos el ID de Belvo recién asignado.
Detalles del titular de la cuenta.
El CPF (11 dígitos) o CNPJ (14 dígitos) del titular de la cuenta.
En el caso de Pix Automático (payment_method
es PIX_OF_AUTOMATICO_FIXED
o PIX_OF_AUTOMATICO_VARIABLE
), el identifier
debe ser un CNPJ (14 dígitos).
El nombre completo o nombre comercial del titular de la cuenta.
Detalles de la cuenta bancaria.
El tipo de cuenta bancaria. Puede ser:
CHECKINGS
(también conocida como Conta Corrente en Brasil)SAVINGS
(también conocida como Conta Poupança en Brasil)PAYMENTS
(también conocida como Conta de Pagamento Instantâneo o Conta de Pagamento en Brasil)
La agencia (número de sucursal) de la institución donde se creó la cuenta.
El Belvo ID de la institución financiera.
El número de cuenta bancaria.
Solo puedes enviar números (^[0-9]+$
) en la cadena. Por ejemplo, "457220"
es un número de cuenta bancaria válido, mientras que "45722-0
" es inválido ya que contiene un guion (-
).
Un identificador único adicional para el recurso con fines internos.
👍 Altamente recomendado
Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.
Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
Detalles sobre el pago.
Solo para Pagos Fijos (PIX_OF_AUTOMATIC_FIXED
).
El monto que se le cobrará a su cliente.
La descripción que aparecerá en el extracto bancario de su cliente.
La frecuencia con la que se realizarán los pagos. Puede ser:
WEEKLY
MONTHLY
QUARTERLY
BIANNUAL
YEARLY
La fecha en que comenzará la autorización (y el primer pago del 'cycle'), en formato YYYY-MM-DD
. Debe ser al menos dos días a partir de la fecha actual.
Si conoces la fecha de finalización de la autorización, puedes enviarla. Si no, puedes omitir el envío de este campo. Sin embargo, no envíes una cadena vacía o null
como valor para este campo, ya que esto causará un error.
La fecha en que finalizará la autorización, en formato YYYY-MM-DD
. Si no se envía una end_date
, la Autorización de Pago será válida por un período indefinido.
El ID del contrato del comerciante con el cliente para el servicio.
Detalles sobre el "propietario" del contrato. Esta es la persona o entidad que está en deuda con el beneficiario (que puede ser diferente del pagador). Por ejemplo, el contrato podría estar a nombre de un padre (contract_debtor
), aunque es uno de los hijos quien realmente está realizando los pagos (payer
).
El CPF o CNPJ del deudor. Para CPF, debe tener 11 caracteres. Para CNPJ, debe tener 14 caracteres.
El nombre completo del deudor.
Boolean que indica si se permiten los reintentos de pago. Por defecto, esto se establece en false
.
Esta función está actualmente en beta y solo está disponible para clientes seleccionados. Si estás interesado en usar esta función, por favor contacta a tu representante de Belvo.
Detalles sobre el primer pago inmediato. (Solo aplicable para PIX_OF_AUTOMATIC_FIXED
y PIX_OF_AUTOMATIC_VARIABLE
.)
Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.
Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
En una solicitud API exitosa, Belvo responde con un 201 - OK
. Necesitarás redirigir a tu usuario al authorization_url
que recibes en la respuesta para que puedan autorizar los pagos en su institución. Una vez que completen el proceso de autorización en la aplicación de su institución, serán redirigidos de vuelta a la return_url
que proporcionaste.
{
"id": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432",
"created_at": "2025-05-20T09:55:02Z",
"updated_at": "2025-05-20T09:55:02Z",
"status": "AWAITING_AUTHORIZATION",
"status_reason_code": null,
"status_reason_message": null,
"status_updated_at": "2025-05-20T09:55:02Z",
"authorized_at": "2025-05-20T09:55:02Z",
"external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
"description": "Internal description used by the merchant only",
"return_url": "https://merchant.com/return",
"payment_method": "PIX_OF_AUTOMATIC_FIXED",
"payer": {
"customer": "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044",
"institution": "770932b4-8f1f-4b0f-8470-1c605903fdb2",
"representative_identifier": "12345678901122"
},
"beneficiary": {
"type": "BANK_ACCOUNT",
"target": "b6278377-f710-4d1a-a026-7bab757256d0"
},
"payment_method_configuration": {
"amount": "10000.05",
"statement_description": "Description to show on the bank statement",
"frequency": "WEEKLY",
"start_date": "2025-06-01",
"end_date": null,
"contract_id": "id-with-max-len-35",
"contract_debtor": {
"identifier": "12345678901",
"name": "João da Silva"
},
"retries": true,
"authorization_url": "url_to_redirect_user"
}
}
El proceso de Autorización de Pago, incluyendo la redirección y la obtención de todas las confirmaciones requeridas, debe completarse en un plazo de 60 minutos. Después de 60 minutos, la autorización se establece automáticamente como REJECTED
.
Una vez que el usuario confirma la autorización, necesitarás escuchar un webhook PAYMENT_AUTHORIZATION
con el status
configurado como AUTHORIZED
. Cuando recibas este webhook, el proceso de autorización está completo.
¡Ahora que tienes la Autorización de Pago, puedes comenzar a cobrar a tu cliente!
Cobrar a su Cliente
Una vez que tenga una Autorización de Pago con el estado AUTHORIZED
, para cada pago que desee recuperar de su cliente, necesita crear un Charge.
Un Charge representa el pago individual (débito) que su cliente realizará.
Cuando solicite un Charge, hay un par de reglas que debe seguir:
La solicitud debe hacerse entre dos y diez días desde que el Charge debe ocurrir. Por ejemplo, si desea debitar la cuenta de su cliente el 30.05.2025, debe hacer la solicitud entre el 20.05.2025 y el 28.05.2025.
Solo se puede hacer un Charge en un ‘ciclo’ de pago. Por ejemplo, si la
frequency
en la Autorización de Pago esWEEKLY
, entonces solo puede cobrar a su cliente una vez por semana. Esto significa que solo puede hacer una solicitud en el ciclo de pago.La
date
del Charge. Esta fecha debe alinearse con lafrequency
en la Autorización de Pago. Por ejemplo, si lafrequency
esMONTHLY
y lastart_date
es2025-06-01
, entonces cadadate
que proporcione debe estar de acuerdo con esta frecuencia y fecha (por ejemplo,2025-06-01
,2025-07-01
,2025-08-01
). Nota: Si el día cae en un fin de semana o un feriado bancario, debe cambiar ladate
para que sea el primer día hábil que ocurra después de la fecha original.
Para solicitar un Charge, deberá hacer la siguiente solicitud:
POST /payment-authorizations/payment_authorization_id/charges/
{
"amount": 10000.05,
"date": "2025-06-01",
"statement_description": "Descripción para mostrar en el estado de cuenta bancario",
}
El monto del pago.
- Para
PIX_OF_AUTOMATIC_FIXED
, este debe ser el mismo valor que enviaste en la autorización. - Para
PIX_OF_AUTOMATIC_VARIABLE
, este debe estar entre los valoresminimum
ymaximum
que enviaste en la autorización.
La fecha en la que se debe realizar el pago, en formato YYYY-MM-DD
. Debe ser al menos dos días después de la fecha actual.
La descripción que aparecerá en el extracto bancario de su cliente.
Un identificador único adicional para el recurso con fines internos.
👍 Altamente recomendado
Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.
Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
En una solicitud de Charge exitosa, recibirá esta respuesta:
{
"id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"created_at": "2022-02-09T08:45:50.406032Z",
"status_updated_at": "2025-06-09T08:45:50.406032Z",
"status": "PENDING",
"status_reason_code": null,
"status_reason_message": null,
"amount": "100.12",
"date": "2025-06-09",
"end_to_end_id": "1234567890abcdef",
"statement_description": "Super Shoe Store - Brown Sneakers",
"external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
"beneficiary": {
"bank_account": {
"id": "088bc38f-1430-40c5-a5d2-80bd67189d11",
"holder": {
"name": "Jane Smith",
"identifier": "12345678901"
},
"details": {
"institution": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"agency": "5678",
"number": "987654321",
"account_type": "SAVINGS",
"code": "678901"
}
}
},
"payer": {
"bank_account": {
"holder": {
"identifier": "12345678902"
},
"details": {
"institution": "f9f40aa0-a864-45d6-a5d4-43ce9d28dd0b",
"code": "123345",
"account_type": "CHECKING",
"agency": "1234",
"number": "123456789"
}
}
},
"metadata": {
"internal_reference_id": "GGq73487w2"
}
}
El día del pago, deberá escuchar un webhook CHARGES
con el estado configurado en SETTLED
, lo que indicará que el pago se completó.
¡Y eso es todo! Ahora, cada vez que necesite solicitar un pago de un cliente, solo necesita hacer otra solicitud de Charge.
Recursos Adicionales
Cambiar la cuenta bancaria para un Cargo individual
Puede haber una situación en la que necesites solicitar que el pago se realice a una cuenta bancaria diferente a la que proporcionaste inicialmente en la Autorización de Pago. ¡Y con Pix Automatico, eso es posible!
Sin embargo, la cuenta bancaria que proporciones debe estar asociada con el mismo CNPJ y Nombre de la Empresa que en la Autorización de Pago inicial. Por ejemplo, si en la cuenta bancaria inicial estaba registrada a Frangos Enlatados
con el CNPJ de 12345678901122
, entonces la nueva cuenta bancaria debe estar registrada con el mismo nombre e identificador de CNPJ. De lo contrario, cuando realices la solicitud, la Red de Open Finance generará un error.
Para solicitar un Cargo con una cuenta bancaria diferente, necesitarás realizar la siguiente solicitud:
POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/
{
"amount": 100.01,
"date": "2025-05-15",
"statement_description": "Monthly Gym - Premium Plan",
"beneficiary": {
"holder": {
"identifier": "12345678901122",
"name": "Frangos Enlatados"
},
"details": {
"account_type": "CHECKINGS",
"agency": "0444",
"institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
"number": "457220"
},
"external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
"metadata": {
"internal_reference_id": "GGq73487w2"
}
}
}
El monto del pago.
- Para
PIX_OF_AUTOMATIC_FIXED
, este debe ser el mismo valor que enviaste en la autorización. - Para
PIX_OF_AUTOMATIC_VARIABLE
, este debe estar entre los valoresminimum
ymaximum
que enviaste en la autorización.
La fecha en la que se debe realizar el pago, en formato YYYY-MM-DD
. Debe ser al menos dos días después de la fecha actual.
La descripción que aparecerá en el extracto bancario de su cliente.
Detalles de la cuenta bancaria que recibirá el pago.
El Belvo ID de la cuenta bancaria que registraste previamente y que recibirá fondos. Para obtener más información sobre cómo registrar una cuenta bancaria, consulta el endpoint Register Bank Account.
Un identificador único adicional para el recurso con fines internos.
👍 Altamente recomendado
Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.
Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
Reintentando un Cargo
En caso de que un Cargo falle, recibirás un webhook el día que indique qué Cargo falló. Si la Autorización de Pago permite reintentos (retries: true
), entonces puedes reintentar el pago e intentar debitar la cuenta del usuario nuevamente.
Con respecto a los reintentos, ten en cuenta lo siguiente:
- Por cada ciclo de pago, puedes reintentar el pago hasta tres veces.
- Puedes programar un reintento para el día siguiente a la solicitud. Por ejemplo, si el Cargo original falla el 01.06.2025, puedes reintentar el Cargo con la
date
establecida para el02.06.2025
. - Los Cargos reintentados están vinculados 1 a 1 con otro Cargo. Consulta la sección de Cargos Vinculados a continuación para una explicación detallada.
- Para ciclos semanales, lo más tarde que puedes hacer el reintento inicial es cinco días (exclusivo) después del primer Cargo fallido. Por ejemplo, si la fecha original del Cargo fue 01.06.2025, tienes hasta el 06.06.2025 para reintentar el pago.
- Para todos los demás ciclos, lo más tarde que puedes hacer el reintento inicial es siete días (exclusivo) después del primer Cargo fallido. Por ejemplo, si la fecha original del Cargo fue 01.07.2025, tienes hasta el 08.07.2025 para reintentar el pago.
Para reintentar un Cargo, necesitarás hacer la siguiente solicitud:
POST /payments/br/payment-authorizations/payment_authorization_id/charges/charge_id/retry/
{
"date": "2025-06-30" // La fecha en la que deseas reintentar el Cargo, en formato YYYY-MM-DD. Debe ser al menos un día en el futuro.
}
En un reintento exitoso, recibirás un nuevo ID de Cargo (y objeto). Por favor, consulta la sección de Cargos Vinculados a continuación para una explicación detallada.
Cargos Vinculados
Belvo utiliza una estructura de lista doblemente enlazada para representar el ciclo de vida de un Cargo y sus reintentos, permitiéndote rastrear todos los intentos individuales asociados con un Cargo. Cada vez que se reintenta un Cargo, se genera un nuevo Cargo y se enlaza al Cargo anterior. Puedes navegar a través de estos Cargos usando los campos previous
y next
. En el ejemplo a continuación, el Cargo ha sido reintentado tres veces:

- El Cargo original (
1546
) falló. El parámetroprevious
está establecido ennull
(indicando que es el primer Cargo). El parámetronext
está establecido en3444
. - El primer reintento (
3444
) falló. El parámetroprevious
está establecido en1546
. El parámetronext
está establecido en8342
. - El segundo reintento (
8342
) falló. El parámetroprevious
está establecido en3444
. El parámetronext
está establecido en9977
. - El tercer reintento (9977) falló. El parámetro
previous
está establecido en8342
. El parámetronext
está establecido ennull
(indica que es el último reintento y no se realizaron más reintentos).
Cancelación de un Cargo individual
La última hora para cancelar un Cargo programado es a las 22:00:00 (GMT-3) del día anterior a la fecha del Cargo. Si no cumples con el tiempo límite, recibirás un error de API de Belvo y el pago se procesará.
Para cancelar un Cargo individual, necesitas enviar la siguiente solicitud:
POST /payments/br/payment-authorizations/payment_authorization_id/charges/charge_id/cancel/
Si tiene éxito, Belvo responde con un 204 - No Content
. Recibirás una notificación de webhook confirmando la cancelación.
Cancelación de una Autorización de Pago
La última hora para cancelar una Autorización de Pago es a las 22:00:00 (GMT-3) del día anterior a la fecha del próximo Cargo. Si no cumples con el tiempo límite, la Autorización de Pago será cancelada, pero el Cargo aún será procesado.
Para cancelar una Autorización de Pago, necesitas enviar la siguiente solicitud antes de las 22:00 (Hora de Brasilia):
POST /payments/br/payment-authorizations/payment_authorization_id/cancel/
Si tiene éxito, Belvo responde con un 204 - No Content
. Recibirás una notificación de webhook confirmando la cancelación.