# 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 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 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: 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": 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" } ``` 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": 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": { "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 cliente (altamente recomendado). **Nota**: Si no utilizas el parámetro `statement_description`, se usará el valor de `description` 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. | | `payment_method_details.open_finance` | si | 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. `schedule`: Ver las secciones dedicadas a continuación para obtener detalles sobre cada programación que puedes solicitar. `cpf`: (Solo cuando el cliente es una empresa) 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). | 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: ```json Single Scheduled Payment { "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 } ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `date` | La fecha en la que debe ocurrir el pago, en formato `YYYY-MM-DD`. La fecha debe ser al menos 1 día en el futuro y no más de 720 días en el futuro. | `2024-08-01` | ### 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: ```json Pago Recurrente Diario { "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 } ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `start_date` | La fecha en que deben comenzar los pagos recurrentes, en formato `YYYY-MM-DD`. | `2024-08-01` | | `occurrences` | El número de veces que este pago recurrente debe repetirse. El valor mínimo es `2` y el valor máximo es `60`. | `52` | ### 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: ```json Pago Recurrente Semanal { "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 } ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `start_date` | La fecha en que los pagos recurrentes deben comenzar, en formato `YYYY-MM-DD`. Actualmente, esta fecha debe ser la misma que el primer `day_of_week` que proporciones. | `2024-08-01` | | `day_of_week` | El día de la semana en que este pago debe liquidarse. Puede ser uno de los siguientes: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, o `SUNDAY`. | `MONDAY` | | `occurrences` | El número de veces que este pago recurrente debe repetirse. El valor mínimo es `2` y el valor máximo es `60`. | `52` | ### 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: ```json Pago Recurrente Mensual { "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 } ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `start_date` | La fecha en que deben comenzar los pagos recurrentes, en formato `YYYY-MM-DD`. Actualmente, esta fecha debe ser la misma que el primer `day_of_month` que proporciones. | `2024-08-01` | | `day_of_month` | El día del mes (entre `1` y `31`) en que debe realizarse el pago. **Nota**: Si eliges un día que no aparece en todos los meses (por ejemplo, `31`), entonces en los meses en que esta fecha no ocurra, el pago se realizará al día siguiente. Por ejemplo, como junio solo tiene 30 días, el pago se procesará el 1 de julio (y luego nuevamente el 31 de julio). Para evitar cobrar a tus usuarios dos veces en el mismo mes, te sugerimos elegir un día hasta el 28. | `26` | | `occurrences` | El número de veces que este pago recurrente debe repetirse. El valor mínimo es `2` y el valor máximo es `24`. | `12` | ### 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: ```json Custom Recurring Payment { "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 } ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `dates` | El array de fechas en las que deben ocurrir los pagos recurrentes, en formato `YYYY-MM-DD`. El número mínimo de fechas es `2` y el número máximo de fechas es `60`. Las fechas deben ser al menos 1 día en el futuro y no más de 720 días en el futuro. | `["2024-06-27", "2024-07-27"]` | | `description` | Una descripción del pago recurrente personalizado que se mostrará a tu usuario cuando sean redirigidos a su banco para dar su consentimiento y aceptar el pago. **Nota**: Recomendamos encarecidamente que este mensaje esté en portugués brasileño y que explique claramente el propósito y la naturaleza recurrente del pago. | `Os pagamentos ocorrerão a cada três dias até a data final (09.07.2024)` | ## 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 la Payment Intent, Charges y Transactions asociadas. 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 todos los Charges programados se hayan completado (incluyendo aquellos que fallen), el estado de la Payment Intent se establecerá en `SCHEDULE_FINISHED`. Para ver si una Payment Intent tiene algún Charge fallido, puedes usar el método List all Charges, filtrando por el `id` de la Payment Intent: ```curl curl --request GET \ --url 'https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/' \ --header 'accept: application/json' \ ---u SECRET_ID:SECRET_PASSWORD ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `payment_intent_id` | El `payment-intent.id` para el que deseas obtener los Charges. | `65492eeb-344c-49fe-8dab-11da1be67d7a` | ## 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 Cancelar Cargo Singular curl --request POST \ --header 'accept: application/json' \ -u SECRET_ID:SECRET_PASSWORD \ --url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/ \ ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `payment_intent_id` | El `payment-intent.id` programado al que pertenece el cargo. | `65492eeb-344c-49fe-8dab-11da1be67d7a` | | `charge_id` | El `charge.id` programado que deseas cancelar. | `414c6387-2d46-45cc-84a8-e1d175aebe53` | Lo más tarde que puedes cancelar un Cargo programado es hasta las 23:59:00 (GMT-3) del día anterior a la fecha de pago programada. Si no cumples con el tiempo límite, recibirás un error de API de Belvo y el pago se procesará. ### 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 Cancelar Payment Intent Completa curl --request POST \ --header 'accept: application/json' \ -u SECRET_ID:SECRET_PASSWORD \ --url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/cancel/ \ ``` | Campo | Descripción | Ejemplo | | --- | --- | --- | | `id` | El `payment-intent.id` que deseas cancelar. | `65492eeb-344c-49fe-8dab-11da1be67d7a` | 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`. Lo más tarde que puedes cancelar una Payment Intent programada es hasta las 23:59:00 (GMT-3) del día anterior a la fecha de pago programada. Si no cumples con el tiempo límite, recibirás un error de API de Belvo y el pago se procesará.