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:

Log in to the Passport Dashboard.
Navigate to Platform > Webhooks.
Select Create Webhook +.
Configure the Webhook.
Click Save.

Configuring Multiple Webhooks

The platform supports various webhook configurations, allowing you to set up one or more webhooks to receive different events at distinct endpoints. This flexibility enables you to tailor your event handling based on your specific needs.

Information

Please note that subscribing to the same event across multiple endpoints is not permitted.

If you have a webhook configured, simply select New Webhook + and proceed to configure your new callback URL along with the required information presented in the section: Webhook Setup in the Dashboard above.

Webhook Configuration: Parameter Details

Field	Description
Callback URL	HTTPS address where Passport will send notifications. Must be publicly accessible.
Secret Token	Key used to calculate/verify the HMAC-SHA256 signature. Keep it secure!
Delivery Mode	Retry mechanism to use (“Once” or “Retry”).
Webhook Enabled	YES/NO selector to enable or disable notifications.
Events	Type of Events: Confirmed, Inbound, Settled, Rejected.

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": { "error_code": "B101", "error_description": "Payment rejected by the MOL with code B101" }, "created_at": "2026-01-27T18:49:32.044301Z", "payment_id": "16b74a91-7290-4769-8906-6467416af1a4", "updated_at": "2026-01-27T18:49:36.513146Z", "Event": "payment.outbound.rejected" } ]

Example of Events

Payment Received

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

Important

This is not the final state of the payment. It is advisable to wait for one of the following final states: SETTLED or REJECTED.

[ { "type": "BREB", "amount": { "value": "1.00", "currency": "COP" }, "sender": { "owner": { "name": "Merchant I9TOS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "name": "BANCO COOPERATIVO COOPCENTRAL", "identification_number": "890203088" } }, "status": "PROCESSING", "receiver": { "key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "name": "BANCO COOPERATIVO COOPCENTRAL", "identification_number": "890203088" } }, "account_id": "1b095dbd-7d4b-46d5-8807-1d636482e48a", "created_at": "2026-03-10T17:44:52.111820Z", "payment_id": "9ff381d9-8b8e-4d20-b2e2-e1d0dd22d3d2", "updated_at": "2026-03-10T17:44:52.111820Z", "destination_key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "qr_code_reference": "LLAVE", "end_to_end_identification": "20260310890203088VIS449878448104403", "Event": "payment.inbound.received" } ]

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.

[ { "sender": { "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "identification_number": "890203088" } }, "receiver": { "key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "identification_number": "890203088" } }, "created_at": "2026-03-10T17:44:48.522249Z", "payment_id": "836b4ad0-2e9e-4ac7-a9ce-c6a6571397c2", "updated_at": "2026-03-10T17:44:54.577324Z", "destination_key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "end_to_end_identification": "20260310890203088VIS449878448104403", "Event": "payment.outbound.confirmed" }, { "type": "BREB", "amount": { "value": "1.00", "currency": "COP" }, "sender": { "owner": { "name": "Merchant I9TOS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "name": "BANCO COOPERATIVO COOPCENTRAL", "identification_number": "890203088" } }, "status": "CONFIRMED", "receiver": { "key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "name": "BANCO COOPERATIVO COOPCENTRAL", "identification_number": "890203088" } }, "account_id": "1b095dbd-7d4b-46d5-8807-1d636482e48a", "created_at": "2026-03-10T17:44:52.111820Z", "payment_id": "9ff381d9-8b8e-4d20-b2e2-e1d0dd22d3d2", "updated_at": "2026-03-10T17:44:54.577324Z", "destination_key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "qr_code_reference": "LLAVE", "end_to_end_identification": "20260310890203088VIS449878448104403", "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.

[ { "sender": { "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "identification_number": "890203088" } }, "receiver": { "key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "identification_number": "890203088" } }, "created_at": "2026-03-10T17:44:48.522249Z", "payment_id": "836b4ad0-2e9e-4ac7-a9ce-c6a6571397c2", "settled_at": "2026-03-10T17:44:55.288802Z", "updated_at": "2026-03-10T17:44:55.288802Z", "destination_key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "end_to_end_identification": "20260310890203088VIS449878448104403", "Event": "payment.outbound.settled" }, { "type": "BREB", "amount": { "value": "1.00", "currency": "COP" }, "sender": { "owner": { "name": "Merchant I9TOS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "name": "BANCO COOPERATIVO COOPCENTRAL", "identification_number": "890203088" } }, "status": "SETTLED", "receiver": { "key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "owner": { "name": "Merchant I9TOS", "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "name": "BANCO COOPERATIVO COOPCENTRAL", "identification_number": "890203088" } }, "account_id": "1b095dbd-7d4b-46d5-8807-1d636482e48a", "created_at": "2026-03-10T17:44:52.111820Z", "payment_id": "9ff381d9-8b8e-4d20-b2e2-e1d0dd22d3d2", "settled_at": "2026-03-10T17:44:55.288802Z", "updated_at": "2026-03-10T17:44:55.288802Z", "destination_key": { "key_type": "ALPHA", "key_value": "@AH6EZ0YPCHNXYM0M2QS9" }, "qr_code_reference": "LLAVE", "end_to_end_identification": "20260310890203088VIS449878448104403", "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:

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.

Last updated on