Saltar al contenido
Última actualización

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 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"
}
Parámetro RequeridoDescripció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, el valor de description se usará como la descripción del estado de cuenta.
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"].
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.
confirmsiIndica 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_financesiEn 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.
customersiEl 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.

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": { 
        "identifier": "23******00", 
        "name": "João da Silva"
      }
    }
  }
}
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:

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.

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/", 
      "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:

EventoRecursoDescripción
STATUS_UPDATEPayment IntentsLos 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_UPDATEChargesLos 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.
Página anterior
Página siguiente
Copyright © 2020-2025 Belvo. All rights reserved