# Guía de API Directa (Beneficiario de Cuenta Bancaria) Con la Iniciación de Pagos de Finanzas Abiertas (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 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 una Payment Intent (que contiene la información necesaria para que el pago sea procesado en la Red de Open Finance). 2. Escuchar el webhook `OBJECT_CREATED` del recurso de transacciones. 3. Obtener los detalles de la transacción. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Payment Institution App->>Belvo: POST /payment-intents/ Note over App,Belvo: Body: Payment Intent Details Belvo->>Inst: Payment information sent to institution Belvo-->>App: 201 - Created Note over App,Inst: Institution processes payment and communicates with other institution Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: REQUIRES_ACTION Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: PROCESSING Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: SUCCEEDED Belvo-->>App: WEBHOOK STATUS_UPDATE (CHARGES)
Status: SUCCEEDED Belvo-->>App: WEBHOOK OBJECT_CREATED (TRANSACTIONS) App->>Belvo: GET /transactions/{transaction.id}/ Belvo-->>App: 200 + Transaction Details ``` ## Crear una Payment Intent La Payment Intent contiene toda la información necesaria para registrar y procesar el pago en la Red de Open Finance. 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 Payment Intent, necesitarás realizar una solicitud POST Create a Payment Intent con el siguiente payload: Con un cliente previamente creado ```json Con cliente previamente creado { "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": true, "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" } ``` Con un nuevo cliente ```json Con nuevo cliente { "amount": "1234.12", "description": "B23A-Shoe-Brown-Sneaker", "statement_description": "Super Shoe Store - Brown Sneakers", "allowed_payment_method_types": ["open_finance"], "confirm": true, "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": { "identifier": "10187609363", "name": "Caetano Veloso", "email": "caetano.veloso@musicabrazil.br", "phone": "+5511987654321", "address": "Rua de Caetano Veloso 432, 70200 Brasilia" }, } ``` | Parámetro | Requerido | Descripción | | --- | --- | --- | | `amount` | true | El monto del pago como una cadena de texto. | | `description` | true | 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 cliente (altamente recomendado). **Nota**: Si no utilizas el parámetro `statement_description`, el valor de `description` se usará como la descripción del estado de cuenta. | | `allowed_payment_method_types` | true | 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"]`. | | `external_id` | opcional (pero recomendado) | Un identificador único adicional (UUID) para el recurso para propósitos internos. Esto puede ser útil para rastrear el recurso en tu sistema y para propósitos de depuración. | | `confirm` | true | Indica que el pago está listo para ser procesado. | | `payment_method_details.open_finance` | true | 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. `payer_institution`: El `id` de la institución desde donde se realiza el pago. `callback_url`: La URL a la que tu usuario debe ser redirigido después de aprobar el pago en su institución bancaria. `cpf`: (Solo cuando el cliente es un negocio) El CPF del usuario que está realizando el pago. | | `customer` | true | El `id` del cliente previamente creado que realizará el pago. Opcionalmente, también puedes crear el cliente al mismo tiempo (ver el ejemplo de código). | Una vez que crees exitosamente una Payment Intent, 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 será redirigido de vuelta a la `callback_url` que proporcionaste en la solicitud de Payment Intent. Validez y sensibilidad de la URL de redirección La `redirect_url` de la Payment Intent es **válida por hasta 5 minutos**. Además, debido a las medidas de seguridad implementadas por las instituciones bancarias, la URL de redirección es altamente sensible y puede invalidarse en los siguientes escenarios: - Si se carga dentro de un **WebView** - Si se carga dentro de un **iframe** - Si ocurre una **búsqueda DNS** antes de que el usuario sea redirigido Para evitar fallos en el pago, asegúrate de que la URL de redirección se abra directamente en el navegador predeterminado del usuario inmediatamente después de recibirla. No precargues, caches o resuelvas la URL antes de la redirección real. ## 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: | Evento | Recurso | Descripción | | --- | --- | --- | | `STATUS_UPDATE` | Payment Intents | Los eventos `STATUS_UPDATE` para Payment Intents indican la etapa del proceso de pago Pix a través de 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 a través de 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: ```json 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 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: ```json 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.