# 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. Pagos Fijos versus Variables 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: 1. Los requisitos previos que necesitas completar antes de hacer cualquier otra cosa. 2. Cómo configurar una Autorización de Pago 3. Cómo solicitar el pago de tus clientes (Cargos) ## Requisitos previos Encabezado de Versión 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 API Version Como puedes ver en el diagrama a continuación, el flujo de datos para crear un pago usando Pix Automático involucra: 1. Crear una Autorización de Pago. 2. Redirigir a tu usuario a la `authorization_url` para que pueda confirmar esa Autorización de Pago. Una vez confirmada, son redirigidos a la `return_url` que proporcionaste. 3. Esperar un webhook `PAYMENT_AUTHORIZATION` con el `status` configurado a `AUTHORIZED`. 4. Solicitar el Cargo al menos dos días antes de que deba ocurrir el pago. 5. El día del pago, esperar un webhook `CHARGES` con el `status` configurado a `SETTLED`. Diagrama de secuencia de las llamadas API requeridas y webhooks enviados durante el proceso de Pix Automático ## 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). Fijo ```curl URL de Solicitud de Autorización de Pago POST /payment-authorizations/ ``` Fixed Pix Automatico { "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" } } Variable ```curl URL de Solicitud de Autorización de Pago POST /payment-authorizations/ ``` Variable Pix Automatico { "payment_method": "PIX_OF_AUTOMATIC_VARIABLE", "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": { "minimum_amount": 10000.01, "maximum_amount": 50000.5, "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.02 } }, "metadata": { "internal_reference_id": "GGq73487w2" } } 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. Fijo Ejemplo de Respuesta de Autorización de Pago Fijo { "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" // [!code highlight] } } Variable Ejemplo de Respuesta de Autorización de Pago Variable { "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_VARIABLE", "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": { "minimum_amount": "10000.01", "maximum_amount": "50000.5", "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" // [!code highlight] } } El proceso de Autorización de Pago, incluyendo la redirección y la obtención de todas las confirmaciones necesarias, debe completarse en un plazo de 60 minutos. Después de 60 minutos, la autorización se establece automáticamente como `FAILED`. 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. Cobrando a Tu Cliente ¡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**. ¿Qué es un Charge? Un **Charge** representa el pago individual (débito) que su cliente realizará. Reglas de Solicitud de Charge Cuando solicite un Charge, hay un par de reglas que debe seguir: 1. 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. 2. Solo se puede hacer un Charge en un ‘ciclo’ de pago. Por ejemplo, si la `frequency` en la Autorización de Pago es `WEEKLY`, entonces solo puede cobrar a su cliente una vez por semana. Esto significa que solo puede hacer **una** solicitud en el ciclo de pago. 3. La `date` del Charge. Esta fecha debe alinearse con la `frequency` en la Autorización de Pago. Por ejemplo, si la `frequency` es `MONTHLY` y la `start_date` es `2025-06-01`, entonces cada `date` 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 la `date` 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: ```curl Charge Request URL POST /payment-authorizations/payment_authorization_id/charges/ ``` ```json Charge Request Body { "amount": 10000.05, "date": "2025-06-01", "statement_description": "Descripción para mostrar en el estado de cuenta bancario", } ``` En una solicitud de Charge exitosa, recibirá esta respuesta: Ejemplo de Respuesta de Charge { "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ó. ¡Hecho! ¡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: Con Detalles de Cuenta Bancaria ```curl URL de Solicitud de Cargo POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/ ``` Cargo con Detalles de Cuenta Bancaria { "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" } } } Con ID de Cuenta Bancaria ```curl URL de Solicitud de Cargo POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/ ``` Cargo con ID de Cuenta Bancaria { "amount": 100.01, "date": "2025-05-15", "statement_description": "Monthly Gym - Premium Plan", "beneficiary": { "target": "046f9af7-1813-4830-b4e6-5231e8111ca1" } } ### Reintentando un Cargo En caso de que un Cargo falle, recibirás un webhook el día indicando 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 el `02.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: ```curl Retry a Charge Request URL POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/ ``` ```json Retry a Charge Request Body { "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: Explicación de listas doblemente enlazadas para Cargos en Belvo 1. El Cargo original (`1546`) falló. El parámetro `previous` está establecido en `null` (indicando que es el primer Cargo). El parámetro `next` está establecido en `3444`. 2. El primer reintento (`3444`) falló. El parámetro `previous` está establecido en `1546`. El parámetro `next` está establecido en `8342`. 3. El segundo reintento (`8342`) falló. El parámetro `previous` está establecido en `3444`. El parámetro `next` está establecido en `9977`. 4. El tercer reintento (9977) falló. El parámetro `previous` está establecido en `8342`. El parámetro `next` está establecido en `null` (indica que es el último reintento y no se realizaron más reintentos). ### Cancelar un Cargo individual Restricción de Tiempo para Cancelación 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: ```shell URL de Solicitud para Cancelar Cargo curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/' \ -u SECRET_ID:SECRET_PASSWORD \ -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \ ``` 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 Restricciones de Tiempo para Cancelación 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): ```shell URL de Solicitud de Cancelación de Autorización de Pago curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/cancel/' \ -u SECRET_ID:SECRET_PASSWORD \ -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \ ``` Si tiene éxito, Belvo responde con un `204 - No Content`. Recibirás una notificación de webhook confirmando la cancelación. ### Obtener detalles de un Cargo Cuando recibes una notificación de webhook sobre un Cargo, puedes solicitar los detalles del Cargo utilizando la siguiente solicitud: ```shell Get Charge Details Request URL curl --request GET 'https://api.belvo.com/payments/br/charges/{charge_id}/' \ -u SECRET_ID:SECRET_PASSWORD \ -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \ ``` ### Códigos y Mensajes de Razón de Estado Cuando una Autorización de Pago o Cargo encuentra un error, Belvo actualiza el `status` del recurso dado. Además, Belvo también proporciona información detallada sobre el cambio de estado en los parámetros `status_reason_code` y `status_reason_message` para ayudarte a entender qué salió mal. Por favor, consulta nuestro artículo dedicado Códigos y Mensajes de Error para obtener una lista más detallada de posibles códigos y mensajes.