Webhook de Notificaciones – Borderless API

Recibe notificaciones de eventos en Prometeo

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:

  1. Exponer un endpoint HTTPS en tus servidores.
  2. Compartir con nosotros la URL de tu endpoint para que podamos configurarlo.
  3. 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:

  1. Verificar elverify_token incluido en la notificación.
  2. 🗃️ Guardar el contenido en tu base de datos para trazabilidad.
  3. 🔁 Responder con un código HTTP 2XX (idealmente 200) para evitar reintentos.
  4. 🧠 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": {}
  }
]
}
CampoDescripcion
verify_tokenToken de verificación enviado por Prometeo
eventsLista de eventos generados
events.event_typeEl tipo de evento
events.event_idID único del evento (usado para evitar duplicados)
events.timestampTimestamp de creación del evento
events.payloadObjeto 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
  }
}