Direct API (Pix via 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 una intención de pago para recolectar pagos
• 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 una intención de pago (que contiene la información requerida para que el pago sea procesado en la Red de Open Finance).
2. Escuchar el OBJECT_CREATED webhook del recurso de transacciones.
3. Obtener los detalles de la transacción.

Crear una Intención de Pago

La Intención de Pago contiene toda la información necesaria para registrar y procesar el pago en la Red de Finanzas Abiertas. Para reducir la fricción para tu cliente, recomendamos que crees tu pantalla de pago de manera que puedas enviar toda la información en una sola llamada POST.

Para crear una Intención de Pago, necesitarás hacer una solicitud POST Crear una Intención de Pago con el siguiente payload:

{
  "amount": "1234.12",
  "description": "B23A-Shoe-Brown-Sneaker",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2",
  "confirm": si,
  "payment_method_details": {
    "open_finance": {
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6"
}

Una vez que crees exitosamente una Intención de Pago, necesitarás usar la URL en el parámetro payment_method_information.open_finance.redirect_url para redirigir a tu usuario a su institución financiera para confirmar el pago. Después de confirmar el pago, tu usuario es redirigido de vuelta a la callback_url que proporcionaste en la solicitud de Intención de Pago.

Payment Intents, Charges, and Transactions

Para cada pago, Belvo genera un objeto Charge dentro del cuerpo de respuesta de Payment Intent. Una vez que un Charge se procesa con éxito, Belvo genera una Transaction asociada con ese Charge.

Estados de pago y notificaciones

Una vez que creas un pago inmediato, recibirás actualizaciones de webhook para el Payment Intent, Charge y Transaction asociados.

A continuación, puedes ver un ejemplo de un pago inmediato y los estados asociados por los que pasará el pago. Recibirás notificaciones de webhook STATUS_UPDATE para cada estado que está marcado con un punto rojo (🔴).

Cuando recibas el evento de webhook OBJECT_CREATED de Transaction, esto indica que el pago dado fue liquidado.

Escuchar actualizaciones de estado de pago

Una vez que crees la Payment Intent, Belvo te proporcionará actualizaciones sobre el pago a través de webhooks. Como puedes ver en la imagen en la sección 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"
}