Webhooks

Overview

This section centralizes everything you need to configure and test the complete Webhook flow within Passport’s Payments-as-a-Service (PaaS) platform. From creating the subscription to end-to-end (E2E) validation of outgoing and incoming payments.

Webhook Setup in the Dashboard

Before receiving notifications, you must register your Webhook in the Passport Dashboard. Below are the details of each field on the “Create Webhook” screen.

The Fintech administrator must:

1. Log in to the Passport Dashboard.
2. Navigate to Platform > Webhooks.
3. Select Create Webhook +.
4. Configure the Webhook.
5. Click Save.

Create Webhook

__

__

Webhook Configuration

Webhook Configuration: Parameter Details

Webhook Retry Behavior

When the Delivery Mode is set to Retry, after a webhook delivery failure, the platform will attempt to resend up to 12 times.

The retry schedule follows exponential backoff:

• 1_2*0 = 1s for the first retry
• 1_2*1 = 2s for the second
• 1_2*2 = 4s for the third
• 1_2*3 = 8s for the fourth

Event Selection

Under the Events section, choose the Payments category and select one or more (the event name in the notification is in parentheses).

We recommend enabling all events to properly handle both inbound and outbound payment scenarios.

• Inbound (payment.inbound.received)

  • The payment was successfully sent to you in the Bre-B network. This means that a payment is being received by you or the customer you manage.

• Confirmed (payment.inbound.confirmed or payment.outbound.confirmed)

  • The inbound or outbound payment was confirmed by the Originating or Receiving Bank.

• Settled (payment.inbound.settled or payment.outbound.settled)

  • The payment was completed at the originating or receiving bank.

• Rejected (payment.inbound.rejected or payment.outbound.rejected)

  • The payment was rejected. Check the response body for more details.

Inbound Event Flow

For inbound transactions (towards your account or your customers), the simple event flow is:

payment.inbound.received > payment.inbound.Confirmed > payment.inbound.settled

Outbound Event Flow

For outbound transactions (from your account or your customers), the main events are:

payment.outbound.confirmed > payment.outbound.settled

Payment Rejection

In the event that the validations MOL result in the status of a payment being classified as Rejected, this can occur at any stage of the payment process. The webhook will provide both the Status Code and a detailed Description of the error that was detected.

• payment.inbound.rejected
• payment.outbound.rejected

"error" : {

  "code": "B101",

  "description": "Account not found",

}

Example of Events

Payment Received

The event payment.inbound.settled happens when a transaction is successfully submitted to your account or your customer's account. This can happen through a Key-to-Key transaction or a QR code. The same applies to payment.outbound.settled, which means that your transaction was settled at the receiving bank.

{

  "payment_id": "7f2be799-9bad-4e87-8fd1-204b67c8e3c1",

  "reference": "20250919890505363VIS110763168961353",

  "account_id": "f49ba409-8f89-4d9a-9687-c5e7e5bb3ba6",

  "customer_id": "56334512-ead6-4b33-90fa-6b7c69052f4e",

  "amount": {

    "value": "100000.00",

    "currency": "COP"

  },

  "created_at": "2025-09-19 16:18:38.860160+00:00",

  "updated_at": "2025-09-19 16:18:39.821841+00:00",

  "status": "SETTLED",

  "Event": "payment.inbound.rexeived"

}

Payment Confirmed

The payment.inbound.confirmed event signifies the confirmation received from the Participant (the receptor bank) regarding the transaction. This confirmation only occurs if certain conditions are met, such as the validity of the key and its association with an existing account at the receptor bank (and more). Following the inbound event, the payment.inbound.confirmed event indicates a successful transaction. However, if any issues arise at the Node, MOL, or Bank level, the subsequent event will be payment.inbound.rejected.

If the direction is outbound, the event will show as payment.outbound.confirmed or payment.outbound.rejected if there is an inconsistency.

{

  "payment_id": "7f2be799-9bad-4e87-8fd1-204b67c8e3c1",

  "reference": "20250919890505363VIS110763168961353",

  "account_id": "f49ba409-8f89-4d9a-9687-c5e7e5bb3ba6",

  "customer_id": "56334512-ead6-4b33-90fa-6b7c69052f4e",

  "amount": {

    "value": "100000.00",

    "currency": "COP"

  },

  "created_at": "2025-09-19 16:18:38.860160+00:00",

  "updated_at": "2025-09-19 16:18:40.460027+00:00",

  "status": "CONFIRMED",

  "Event": "payment.inbound.confirmed"

Payment Settled

One of the most significant events in the payment flow, payment.inbound.settled or payment.outbound.settled his marks the successful transfer of funds from or to your customer's bank account. In other words, this indicates that the customer has completed the payment for the service or product, and the funds are now available in account. Conversely, outbound payments refer to the process where funds are transferred from an account to the designated destination account.

{

  "payment_id": "7f2be799-9bad-4e87-8fd1-204b67c8e3c1",

  "reference": "Dispersion a merchant PEPITO",

  "account_id": "f49ba409-8f89-4d9a-9687-c5e7e5bb3ba6",

  "customer_id": "56334512-ead6-4b33-90fa-6b7c69052f4e",

  "amount": {

    "value": "100000.00",

    "currency": "COP"

  },

  "created_at": "2025-09-22 15:14:38.790966+00:00",

  "updated_at": "2025-09-22 15:15:21.388715+00:00",

  "status": "SETTLED",

  "breb_recipient_id": "0f7d4398-5fbd-4889-93ed-37e4ee20534d",

  "Event": "payment.inbound.settled"

}

Payment Rejected

In the event of any issues encountered by any actor in the payment flow, a rejection status will be returned. This indicates that the movement of funds will not take place within the network or between accounts. Please note that this status is final. Consequently, the payment should be thoroughly reviewed to identify any error status codes. The relevant webhooks will display the specific error in the appropriate field:

"error" : {

  "code": "B101",

  "description": "Account not found",

}

The direction of the payment (inbound or outbound) will be indicated in events as follows:

• payment.inbound.rejected for rejected inbound payments.
• payment.outbound.rejected for rejected outbound payments.