Direct API (Pix Programado y Recurrente)

Con la Iniciación de Pagos de Finanzas Abiertas (OFPI) de Belvo, puedes recolectar pagos programados 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 programados o recurrentes
• los estados de pago y notificaciones
• cómo cancelar pagos programados o recurrentes

Descripción general del flujo de datos

Como puedes ver en el diagrama a continuación, el flujo de datos para crear un pago programado o recurrente involucra:

1. Crear una intención de pago (que contiene la información requerida para que el pago sea procesado en la Red de Finanzas Abiertas).
2. Escuchar las notificaciones relacionadas con el pago programado.
3. El día del pago programado, escuchar el OBJECT_CREATED webhook del recurso de transacciones.
4. Obtener los detalles de la transacción cuando el pago se complete.

Para más detalles sobre las notificaciones que puedes recibir, así como el ciclo de vida de un pago programado o recurrente, consulta la sección de Estados de pago y notificaciones de esta guía.

Crear una Payment Intent programada

La Payment Intent 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 Payment Intent Programada o Recurrente, necesitarás hacer una solicitud POST Crear una Payment Intent 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",
      "schedule": {} // ver las secciones dedicadas a continuación
    }
  },
  "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6"
}

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

Single

Un single pago programado te permite configurar una transacción única para una fecha futura específica. Esto es ideal para pagos únicos donde necesitas asegurarte de que la transacción ocurra en un día particular. Para crear un pago programado único, agrega la siguiente información a tu solicitud de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pago de zapatos - Single",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "single": {
          "date": "2024-08-01"
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Diario

Los pagos programados diarios permiten transacciones recurrentes todos los días a partir de una fecha especificada. Esto es perfecto para pagos frecuentes y regulares, como suscripciones diarias o servicios repetitivos. Para crear un pago programado diario, agrega la siguiente información a tu solicitud de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pago de zapatos - Diario",
  "statement_descrption": "Super Shoe Store - Zapatillas Marrones",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "daily": {
          "start_date": "2025-04-09",
          "occurrences": 2
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Semanal

Los pagos programados semanalmente te permiten configurar transacciones recurrentes en un día específico de cada semana. Esto es útil para servicios semanales u obligaciones recurrentes que ocurren el mismo día de la semana. Para crear un pago programado semanal, agrega la siguiente información a tu solicitud de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pago de zapatos - Semanal",
  "statement_descrption": "Super Shoe Store - Zapatillas Marrones",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "weekly": {
          "start_date": "2025-04-09",
          "day_of_week": "MONDAY",
          "occurrences": 2
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Mensual

Los pagos programados mensuales están diseñados para transacciones que se repiten el mismo día de cada mes. Esta configuración es ideal para facturas mensuales, suscripciones o cualquier pago mensual regular. Para crear un pago programado mensual, agrega la siguiente información a tu solicitud de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pago de zapatos - Mensual",
  "statement_descrption": "Super Shoe Store - Zapatillas Marrones",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "monthly": {
          "start_date": "2025-04-26",
          "day_of_month": 26,
          "occurrences": 12
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Custom

Los pagos programados Custom ofrecen flexibilidad al permitirte especificar un array de fechas para transacciones recurrentes. Esta opción es perfecta para horarios irregulares o planes de pago personalizados que no se ajustan a patrones de recurrencia estándar. Para crear un pago programado personalizado, agrega la siguiente información a tu solicitud de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Custom Schedule",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "custom": {
          "dates": ["2024-06-27", "2024-07-27", "2024-08-26", "2024-09-25", "2024-10-25"]
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Payment Intents, Charges, and Transactions

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

Por ejemplo, si creas un pago recurrente que ocurrirá dos veces, el charges array en el Payment Intent incluirá dos Charges. Y una vez que el primer Charge se procesa, Belvo genera una Transaction asociada.

Estados de Pago y Notificaciones

Una vez que programes un pago, recibirás actualizaciones de webhook para el Payment Intent, Charges y Transactions asociados. A continuación, puedes ver un ejemplo de un pago programado recurrente y los estados asociados por los que pasará cada 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 programado dado fue liquidado.

Una vez que se hayan completado todos los Charges programados (incluidos aquellos que fallen), el estado del Payment Intent se establecerá en SCHEDULE_FINISHED.

Para ver si un Payment Intent tiene algún Charge fallido, puedes usar el método List all Charges, filtrando por el id del Payment Intent:

curl --request GET \
--url 'https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/' \
--header 'accept: application/json' \
---u [Secret Key ID]:[Secret Key PASSWORD]

Cancelar un pago

Cancelar un cargo específico

Para cancelar un cargo programado específico, solo necesitas realizar una llamada a la API POST Cancelar un Cargo programado:

curl 
--request POST \
--header 'accept: application/json' \
-u [Secret Key ID]:[Secret Key PASSWORD] \
--url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/ \

Cancelar una Payment Intent completa

Para cancelar una Payment Intent (y todos los Cargos programados asociados), solo necesitas hacer una llamada a la API POST Cancel a Payment Intent:

curl 
--request POST \
--header 'accept: application/json' \
-u [Secret Key ID]:[Secret Key PASSWORD] \
--url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/cancel/ \

Después de realizar tu solicitud de cancelación, Belvo responderá con un 204 - No Content, y te notificará mediante un webhook que el estado de la Payment Intent ha cambiado a CANCELED.