Webhook de Notificaciones – Borderless API

Usá nuestro webhook de notificaciones para recibir actualizaciones en tiempo real sobre el estado de los pagos realizados mediante la API de Borderless .

🚀 ¿Cómo habilitar las notificaciones?

Para comenzar a recibir notificaciones de cambios de estado en tus transacciones, seguí estos pasos:

Exponer un endpoint HTTPS en tus servidores.
Compartir con nosotros la URL de tu endpoint para que podamos configurarlo.
Procesar las notificaciones recibidas con tu lógica de negocio.

📥 Requisitos del endpoint

Las notificaciones se envían como solicitudes HTTP POST al endpoint que nos indiques. Asegurate de cumplir con los siguientes requisitos:

El endpoint debe estar disponible mediante HTTPS.
Debe responder con un código HTTP 200 para confirmar la recepción.
Es posible que necesites configurar tu firewall o WAF para aceptar solicitudes desde nuestras IPs: 107.23.220.24, 23.22.34.57 y 3.83.0.169

🚧
Reintento de notificaciones
Si respondes con un codigo fuera del rango 2XX o demoras mas de 5 segundos en responder, volveremos a intentar luego de un tiempo. Deberas encargarte de deduplicar eventos usando el identificador del mismo.

⚙️ Configuración del webhook

Una vez que hayas expuesto tu endpoint, compartinos la URL y nosotros nos encargaremos de configurarlo.

Te enviaremos un verify_token que deberás usar para validar la autenticidad de cada notificación recibida.

📌 Procesamiento de notificaciones

Cuando recibas una notificación, seguí estos pasos:

✅ Verificar elverify_token incluido en la notificación.
🗃️ Guardar el contenido en tu base de datos para trazabilidad.
🔁 Responder con un código HTTP 2XX (idealmente 200) para evitar reintentos.
🧠 Aplicar la lógica de negocio necesaria según el tipo de evento.

🧾 Estructura del mensaje

Cada webhook se envía como una solicitud HTTP POST con el siguiente cuerpo JSON:

{
"verify_token": "TOKEN_GENERADO",
"events": [
  {
    "event_type": "payin.settled",
    "event_id": "UUID-EVENTO",
    "timestamp": "2025-07-29T14:44:43.786177",
    "payload": {}
  }
]
}

Campo	Descripcion
`verify_token`	Token de verificación enviado por Prometeo
`events`	Lista de eventos generados
`events.event_type`	El tipo de evento
`events.event_id`	ID único del evento (usado para evitar duplicados)
`events.timestamp`	Timestamp de creación del evento
`events.payload`	Objeto con los datos específicos del evento

📘 Tipos de Eventos

✅ `payin.settled`

Indica que el pago fue recibido correctamente.

{
  "event_type": "payin.settled",
  "event_id": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-07-29T14:44:43.786177",
  "payload": {
    "amount": 1500,
    "concept": "SHELDON-RENT-JULY",
    "currency": "MXN",
    "intent_id": "a9f8e7d6-5432-1abc-9def-0987654321ff",
    "transaction_id": "b0a9c8d7-6789-4567-8901-fedcba123456",
    "external_id": "EXT-BBT-001",
    "reference": "TX-SHEL-20250729",
    "origin": {
      "name": "Leonard Hofstadter",
      "tax_id": "LEOH010203XYZ",
      "tax_id_type": "rfc",
      "withdrawal_account": {
        "account_number": "700000000000000010",
        "bank": {
          "code": "700",
          "name": "MockBank Origin",
          "country": "MX"
        }
      }
    },
    "destination": {
      "account": "646000000000000042",
      "owner_name": "Sheldon Cooper",
      "tax_id": "SHEC990101AAA",
      "tax_id_type": "rfc",
      "bank": {
        "code": "646",
        "bicfi": "MOCKBIC2",
        "name": "MockBank Destination",
        "country": "MX"
      }
    },
    "voucher_data": {
      "key_tracing": "BBT987654321",
      "url": "https://mockbank.com/vouchers/BBT987654321"
    }
  }
}

❌ `payin.rejected`

Indica que el pago fue rechazado (por ejemplo, por un error en el monto).

{
  "event_type": "payin.rejected",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "timestamp": "2025-07-29T14:23:40.676857",
  "payload": {
    "amount": 50,
    "concept": "PENNY-COFFEE-REF202507",
    "currency": "MXN",
    "intent_id": "f9e8d7c6-b5a4-3210-9876-abcdefabcdef",
    "transaction_id": "abc12345-def6-7890-1234-fedcba987654",
    "external_id": "EXT-BBT-002",
    "reference": null,
    "error": {
      "code": "MX99",
      "message": "Amount does not match with intent data"
    },
    "origin": {
      "name": "Penny Teller",
      "tax_id": "PENT010203XYZ",
      "tax_id_type": "rfc",
      "withdrawal_account": {
        "account_number": "700000000000000011",
        "bank": {
          "code": "700",
          "name": "MockBank Origin",
          "country": "MX"
        }
      }
    },
    "destination": {
      "account": "646000000000000043",
      "owner_name": "Rajesh Koothrappali",
      "tax_id": "RAJK990101AAA",
      "tax_id_type": "rfc",
      "bank": {
        "code": "646",
        "bicfi": "MOCKBIC3",
        "name": "MockBank Destination",
        "country": "MX"
      }
    },
    "voucher_data": null
  }
}

🚀 ¿Cómo habilitar las notificaciones?

📥 Requisitos del endpoint

Reintento de notificaciones

⚙️ Configuración del webhook

📌 Procesamiento de notificaciones

🧾 Estructura del mensaje

📘 Tipos de Eventos

✅ payin.settled

❌ payin.rejected

✅ `payin.settled`

❌ `payin.rejected`