Enlaces de Pago (Pix a través de Open Finance)

Con la Iniciación de Pagos de Open Finance (OFPI) de Belvo, puedes recolectar 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 Cliente para solicitar fondos
• cómo crear una Intención de Pago para enviar a tu usuario
• rastrear el estado de tus solicitudes de pago

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.

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

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

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.

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:

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'

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