Resolve Bre-B Key

Overview

This endpoint allows you to retrieve details of a specific Bre-B Key within the Passport API using the base information of the Key: key type and key value.

This will be best used when the Customer is making a one time, or irregular, Payment to the Key owner, such as at a Point of Sale (PoS) point in a restaurant, or online purchase. The Recipient is not needed to be stored so fewer API calls are needed to complete a Payment.

Endpoint Details

Definition	Description
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/resolve-key
Method	POST
Headers	Authorization
Authentication	Access Token (Bearer Token)

Request Body

Parameter	Type	Constraints	Required	Description
customer_id	UUID		Mandatory	The unique id of the Customer making the erquest
key	Object		Mandatory	An object that stores the Key information.
key_type	ENUM	`PHONE`, `EMAIL`, `ID`, `ALPHA`, `BCODE`	Optional	The type of Bre-B Key that is to be resolved. Required to be one of: Type of key. Accepted values: `ID` : Document Number. `PHONE`: Mobile Phone Number. `EMAIL`: Email. `ALPHA`: Alphanumeric Number. `BCODE`: Commercial Entity Number.
key_value	String	Various	Mandatory	The Bre-B Key that is to be resolved.

Example Request

curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.com/v1/resolve-key' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --data '{ "customer_id": "5991657f-fcd2-4699-af98-7d980e24b245", "key": { "key_type": "PHONE", //optional "key_value": "3123185778" } }'

Response Body

HTTP Status Code: 200 OK
The response contains the Bre-B Key metadata.

Example of Response

{ "id": "a41edccc-3bb0-41ce-ade0-9e8fe36783f5", "owner": { "identification_type": "NIT", "identification_number": "403364725", "first_name": "", "second_name": "", "first_last_name": "", "type": "BUSINESS", "business_name": "Merchant IRPFQ", "second_last_name": "" }, "key": { "key_type": "PHONE", "key_value": "3123185778" }, "customer_id": "5991657f-fcd2-4699-af98-7d980e24b245", "resolved_at": "2025-10-31T12:44:20.779Z", "participant": { "name": "", "identification_number": "837283743" }, "account": { "account_number": "88815573857", "account_type": "ORDINARY" }, "expires_at": "2025-10-31T13:14:20.779Z", "receptor_node": "VIS" }

The response confirms the translation of the Bre-B Key to the financial information that needs to be presented to the Customer, as well as to ensure a potential Payment is routed accordingly.

Important

Make sure to re-use the resolution_id when you are re-trying a payment. This is crucial as we guarantee that only one payment will be created with the same resolution_id. In other words, it acts as an idempotency key, ensuring that duplicate payments are not processed.

Common Errors and Handling

HTTP Status Code	Meaning	Description
400 Bad Request	Invalid Request	The recipient ID is missing or incorrectly formatted.
401 Unauthorized	Expired Token	The access token is invalid or has expired.
403 Forbidden	Access Denied	The request is not authorized to retrieve this recipient.
404 Not Found	Recipient Not Found	No recipient was found with the given ID.
500 Internal Server Error	Server Error	An unexpected error occurred while retrieving the recipient.

Best Practices

Use the retrieved recipient details for initiating Bre-B payments - use the id from the above response to pass as the resolution_id within the Payment body.

Last updated on