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.

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

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:

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.

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

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

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.

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.

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

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ó.

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

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 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:

 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:

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).

Cancelación de un Cargo individual

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

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.