Skip to content
Última actualización

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
Requisitos previos

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:

  1. Crear un Cliente para tu usuario
  2. Crear un Enlace de Pago (que contiene la información base para que el pago sea procesado en la Red de Open Finance).
  3. Enviar a tu usuario la URL del Enlace de Pago para procesar el pago.
  4. Escuchar el webhook OBJECT_CREATED del recurso de transacciones.
  5. 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.

Create Customer Request Body
{
  "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ámetroRequeridoDescripción
identifiersiEl número de CPF o CNPJ del cliente.
nameopcional (pero recomendado)El nombre completo del cliente (altamente recomendado).
external_idopcional (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.
emailopcionalLa dirección de correo electrónico del cliente.
phoneopcionalEl número de teléfono del cliente.
addressopcionalLa 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.

Cuerpo de la Solicitud de Enlace de Pago
{
  "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ámetroRequeridoDescripción
amountsiEl monto del pago como una cadena de texto.
descriptionsiLa descripción del pago para tus propósitos internos.
statement_descriptionopcional (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.
customersiEl id del cliente previamente creado que realizará el pago.
allowed_payment_method_typessiEl 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_financesiEn 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_urlssiEn 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_insiEn 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á:

  1. Solicitado para seleccionar su institución
  2. Solicitado para confirmar la información del pago
  3. 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:

EventoRecursoDescripción
STATUS_UPDATEPayment IntentsLos 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_UPDATEChargesLos 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_CREATEDTransactionsEl 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:

Ejemplo de webhook de Transacción OBJECT_CREATED
{
  "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ámetroTipoDescripciónEjemplo
idstring (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:

Payload de Respuesta de Transacciones
{
  "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.