# Guía de Direct API (Beneficiario de Clave Pix)

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 Payment Intent 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. Solicitar a tu usuario que confirme los detalles del Pix.
3. Confirmar la Payment Intent para iniciar el pago.
4. Redirigir al Pagador a su institución bancaria para aprobar el pago.
5. Escuchar los webhooks `SUCCEEDED` de los recursos Payment Intents y Charges.


## 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. Al usar Claves Pix como beneficiario, necesitarás realizar dos llamadas a la API para completar el proceso de pago: primero, crear la Payment Intent y luego confirmarla.

Para crear una Payment Intent, necesitarás hacer una solicitud POST Crear una 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": false,
  "payment_method_details": {
    "open_finance": {
      "pix_key": "chosen-pix-key",
      "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": false,
  "payment_method_details": {
    "open_finance": {
      "pix_key": "chosen-pix-key",
      "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` | 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`, el valor de `description` se usará como la descripción del estado de cuenta. |
| `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"]`. |
| `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. |
| `confirm` | si | Indica que el pago está listo para ser procesado. Para la creación inicial de la Payment Intent, esto debe establecerse en `false`. Confirmarás el pago en un paso separado. |
| `payment_method_details.open_finance` | si | En el objeto `open_finance`, debes proporcionar los siguientes detalles sobre el pago:- `pix_key`: La Clave Pix asociada con la cuenta bancaria que recibirá los fondos del pago. Esto puede ser un CPF, CNPJ, correo electrónico, número de teléfono (incluyendo el código de país "+55123124234234"), o una clave aleatoria.
- `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` | si | 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). |


En la respuesta de la Payment Intent, recibirás los siguientes campos destacados. Necesitas mostrarlos en tu aplicación al usuario para que puedan confirmar que esta es la información de pago correcta. Después de que confirmen los detalles, necesitarás confirmar la Payment Intent en el siguiente paso.


```json Respuesta Inicial de Payment Intent
{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "customer": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09",
  "updated_at": "2022-02-09T08:45:50.406032Z",
  "status": "REQUIRES_PAYMENT_METHOD",
  "amount": "1234.12",
  "currency": "BRL",
  "description": "Training shoes",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "selected_payment_method_type": "open_finance",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "pix_key": "53497b80-81a2-4ea8-9296-83a909c05bdf",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "payment_method_information": {
    "open_finance": {
      "pix_key_details": { // [!code highlight]
        "identifier": "23******00", // [!code highlight]
        "name": "João da Silva" // [!code highlight]
      }
    }
  }
}
```

Enmascaramiento de Clave Pix
En el caso de que la Clave Pix proporcionada sea un CPF, dirección de correo electrónico o número de teléfono, el valor en `payment_method_details.open_finance.pix_key` será enmascarado. Si es un CNPJ o una Clave Pix aleatoria UUID, el valor no será enmascarado.

## Confirmar la Payment Intent

Para confirmar la Payment Intent, necesitarás hacer una solicitud POST Completar una Payment Intent con el siguiente payload:


```json Confirmar Payment Intent
{
  "confirm": true
}
```

Una vez que hayas completado 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 es redirigido de vuelta a la `callback_url` que proporcionaste en la solicitud de Payment Intent.


```json Respuesta de Payment Intent Confirmada
{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "customer": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09",
  "updated_at": "2022-02-09T08:45:50.406032Z",
  "status": "REQUIRES_ACTION",
  "amount": "1234.12",
  "currency": "BRL",
  "description": "Training shoes",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "selected_payment_method_type": "open_finance",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "pix_key": "53497b80-81a2-4ea8-9296-83a909c05bdf",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "payment_method_information": {
    "open_finance": {
      "provider_request_id": "978c0c97ea847e78e8849634473c1f1",
      "redirect_url": "https://wakandanational.com/", // [!code highlight]
      "end_to_end_id": "F203262942022211117487a213b1d140",
      "settlement_date": "2024-10-22",
      "pix_key_details": {
        "identifier": "23******00",
        "name": "João da Silva"
      }
    }
  }
}
```

## Estados de pago y notificaciones

Para cada Payment Intent confirmado, Belvo genera un objeto **Charge** dentro del cuerpo de respuesta del Payment Intent.

Recibirás notificaciones de webhook tanto para el Payment Intent como para el Charge asociado a medida que el pago pasa por diferentes estados.

A continuación, puedes ver un ejemplo de un pago 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 los eventos de webhook `SUCCEEDED` de Payment Intent y Charge, 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 de 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 de Pix via 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 de Pix via 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. |