Enlaces de Pago (Pix a través de Open Finance)
Con la Iniciación de Pagos de Open Finance (OFPI) de Belvo, puedes cobrar pagos de tus clientes y optimizar su experiencia de pago. En esta guía, te mostraremos:
- el flujo general de datos
- cómo crear un Customer para solicitar fondos
- cómo crear un Payment Intent para enviar a tu usuario
- rastrear el estado de tus solicitudes de pago
Por favor, asegúrate de haber completado todos los pasos en nuestro artículo dedicado a los requisitos previos antes de continuar con esta guía.
Descripción general del flujo de datos
Como puedes ver en el diagrama a continuación, el flujo de datos para crear un pago usando Pix a través de Open Finance involucra:
- Crear un Cliente para tu usuario
- Crear un Enlace de Pago (que contiene la información base para que el pago sea procesado en la Red de Open Finance).
- Enviar a tu usuario la URL del Enlace de Pago para procesar el pago.
- Escuchar el webhook
OBJECT_CREATED
del recurso de transacciones. - Obtener los detalles de la transacción.

Crear un Cliente
Para cada usuario del que deseas recolectar fondos, necesitas crear un Cliente ([POST] Crear un nuevo cliente). Sin embargo, al solicitar pagos posteriores, solo necesitas usar el id
del Cliente que creaste.
{
"identifier": "10187609363",
"name": "Gustavo Veloso",
"external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2",
"email": "Gustavo.veloso@musicabrazil.br",
"phone": "+5511987654321",
"address": "Rua de Caetano Veloso 432, 70200 Brasilia"
}
Parámetro | Requerido | Descripción |
---|---|---|
identifier | si | El número de CPF o CNPJ del cliente. |
name | opcional (pero recomendado) | El nombre completo del cliente (altamente recomendado). |
external_id | opcional (pero recomendado) | Un identificador único adicional (UUID) para el recurso con fines internos. Esto puede ser útil para rastrear el recurso en tu sistema y para propósitos de depuración. |
email | opcional | La dirección de correo electrónico del cliente. |
phone | opcional | El número de teléfono del cliente. |
address | opcional | La dirección postal del cliente. |
Recibirás la siguiente respuesta de nuestra API, confirmando que el cliente fue creado. Asegúrate de guardar el id
que recibas, ya que este ID es necesario al crear un enlace de pago 🤓.
{
"id": "49f244ef-06cd-49cf-ad0c-f43796e370ad",
"created_at": "2020-04-23T21:30:20.336854+00:00",
"created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"customer_type": "INDIVIDUAL",
"name": "Caetano Veloso",
"country": "BRA",
"email": "caetano.veloso@musicabrazil.br",
"identifier": "23******00",
"identifier_type": "CPF",
}
Crear un Enlace de Pago
Para crear un Enlace de Pago, necesitas hacer una solicitud [POST] Create a payment link.
{
"amount": "1234.12",
"description": "B23A-Shoe-Brown-Sneaker",
"statement_description": "Super Shoe Store - Brown Sneakers",
"customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
"allowed_payment_method_types": ["open_finance"],
"payment_method_details": {
"open_finance": {
"beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
}
},
"callback_urls": {
"cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
"success": "https://www.acmecorp.com/checkout/3487548/success"
},
"expires_in": "7d"
}
Parámetro | Requerido | Descripción |
---|---|---|
amount | si | El monto del pago como una cadena de texto. |
description | si | La descripción del pago para tus propósitos internos. |
statement_description | opcional (pero recomendado) | La descripción que aparecerá en el estado de cuenta del banco del cliente (altamente recomendado). Nota: Si no utilizas el parámetro statement_description , se usará el valor de description como la descripción del estado de cuenta. |
customer | si | El id del cliente previamente creado que realizará el pago. |
allowed_payment_method_types | si | El parámetro allowed_payment_method_types indica qué método de pago debe usarse. Para pagos en Brasil, esto debe establecerse en ["open_finance"] . |
payment_method_details.open_finance | si | En el objeto open_finance , debes proporcionar los siguientes detalles sobre el pago: beneficiary_bank_account : El id de la cuenta bancaria que recibirá los fondos del pago. |
callback_urls | si | En el objeto callback_urls , proporcionas las URLs a las que tu usuario debe ser redirigido: cancel : La URL a la que el usuario debe ser redirigido si decide cancelar el proceso de pago o si ocurre un error. success : La URL a la que el usuario debe ser redirigido cuando complete el proceso de pago exitosamente. |
expires_in | si | En el parámetro expires_in , puedes proporcionar el período durante el cual el hosted widget del enlace de pago debe estar disponible. Por defecto, está establecido en 7 días (7d ). Puedes proporcionar el período expires_in en uno de los siguientes formatos: número entero + m para x cantidad de minutos. Por ejemplo: 15m para 15 minutos. número entero + h para x cantidad de horas. Por ejemplo: 12h para 12 horas. número entero + d para x cantidad de días. Por ejemplo: 7d para 7 días. |
Una vez que crees exitosamente un Enlace de Pago, necesitarás enviar a tu usuario a la URL en el parámetro payment_url
. Después de confirmar el pago, tu usuario es redirigido de vuelta a la callback_urls.success
que proporcionaste en la solicitud del Enlace de Pago.
Proceso de Enlace de Pago
Necesitas compartir el payment_url
con tu usuario para que puedan iniciar el hosted widget de Enlace de Pago de Belvo. El widget guiará a tu usuario a través del flujo de pago. Cuando el hosted widget de Enlace de Pago se inicie, tu usuario será:
- Solicitado para seleccionar su institución
- Solicitado para confirmar la información del pago
- Redirigido a su institución para completar el proceso de pago en su banco.
Para ayudarte a realizar un seguimiento del proceso de tu usuario dentro del widget de Enlace de Pago, Belvo envía eventos de webhook de actualización de status
de intención de pago. En los diagramas a continuación, anotamos qué evento de status
de intención de pago se enviará en cada paso del proceso.

Una vez que tu usuario confirma el pago en su institución, será redirigido de vuelta al hosted widget de Enlace de Pago y verá un estado de Procesando mientras Belvo confirma el pago. Dependiendo del resultado de su institución, tu usuario verá una pantalla de Pago Confirmado o Pago Fallido en el widget.
Por el momento, el widget mostrará un mensaje de error genérico. Pero actualmente estamos trabajando para mejorar tu experiencia y pronto volveremos con explicaciones más detalladas de todos los posibles errores que se pueden mostrar al usuario. 😉

Escuchar actualizaciones de estado de pago
Una vez que crees el Payment Link, Belvo te proporcionará actualizaciones sobre el pago a través de webhooks. Como puedes ver en la imagen en la sección de Descripción general del flujo de datos, recibirás los siguientes webhooks durante el proceso de pago:
Evento | Recurso | Descripción |
---|---|---|
STATUS_UPDATE | Payment Intents | Los eventos STATUS_UPDATE para Payment Intents indican la etapa del proceso de pago Pix vía Open Finance. Recibirás las siguientes actualizaciones de estado: REQUIRES_ACTION , PROCESSING y SUCCEEDED . > Nota: Aparte de responder al evento con un 200 OK , no se requiere ninguna acción adicional. |
STATUS_UPDATE | Charges | Los eventos STATUS_UPDATE para Charges indican la etapa del proceso de pago Pix vía Open Finance. Recibirás las siguientes actualizaciones de estado: SUCCEEDED . > Nota: Aparte de responder al evento con un 200 OK , no se requiere ninguna acción adicional. |
OBJECT_CREATED | Transactions | El evento OBJECT_CREATED para Transactions indica que los fondos del pago fueron transferidos de una cuenta a otra. > Nota: Aparte de responder al evento con un 200 OK , te recomendamos también hacer una solicitud de Obtener detalles de la transacción para obtener la información de la transacción. |
Obtener detalles de transacciones exitosas.
El webhook
OBJECT_CREATED
del recurso de Transacciones indica que el pago fue exitoso y los fondos fueron transferidos de una cuenta a otra. Esto significa que cada vez que el dinero se haya transferido exitosamente a tu cuenta, recibirás la siguiente notificación:
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "TRANSACTIONS",
"webhook_code": "OBJECT_CREATED",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {}, //Para los webhooks OBJECT_CREATED, el campo data devuelve un objeto vacío.
}
Puedes obtener los detalles sobre la transacción haciendo una llamada GET details usando el object_id
de la transacción (que recibes en el evento del webhook).
curl --request GET \
--url https://api.belvo.com/payments/br/transactions/{id}/ \
--header 'accept: application/json'
Parámetro | Tipo | Descripción | Ejemplo |
---|---|---|---|
id | string (uuid) | El transaction.id del que deseas obtener información detallada. Puedes recuperar este ID del campo object_id que recibiste en el webhook de transacciones OBJECT_CREATED . | a3b92311-1888-449f-acaa-49ae28d68fcd |
Recibirás la siguiente información sobre la transacción:
{
"id": "fd0f3303-cafb-47ea-9753-21155cb144ab",
"created_at": "2020-04-23T21:30:20.336854+00:00",
"created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"amount": "500",
"currency": "BRA",
"description": "Awesome training Sneaker",
"transaction_type": "INFLOW",
"beneficiary": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
"payer": {},
"payment_intent": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"customer": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
¡Y eso es todo! Siguiendo esta guía puedes realizar pagos usando el producto Pix de Belvo a través de Open Finance.