Initiate a Payment

Overview

This endpoint allows you to initiate a Bre-B payment within the Passport API. A successful request processes the payment and returns the transaction details, including status and recipient information.

Endpoint Details

Definition	Description
Endpoint	https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/payments/breb
Method	POST
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Request Body

Parameter	Type	Constraints	Required	Description
account_id	String		Yes	The unique identifier of the account from which the payment will be made.
breb_recipient_id	String		Yes	The unique identifier of the Bre-B recipient receiving the payment.
amount.value	String		Yes	The amount to be transferred.
amount.currency	String	ENUM: `COP`	Yes	The currency of the transaction.
reference	String	1-35	Optional	A description or reference for the payment.

For notation amount.value, it stats the object.field name.

Example Request

JSON
    
 
curl --location 'https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/breb/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "account_id": "9bb99e5e-5bd0-44c9-944a-d01c9d8ffe21", 
    "breb_recipient_id": "8e5dbe27-b17e-4366-a116-82f9c52bcdab",
    "amount": { 
        "value": "100000",
        "currency": "COP"
    },
    "reference": "Test payment"
}'
Copy

Response Body

HTTP Status Code: 200 OK.
Returns the newly created payment and its associated metadata.

Example of Response

JSON
    
 
{
    "breb_resolved_key": {
        "account_type": "LOW_VALUE",
        "account_number": "00880798997",
        "business_name": "DQDevelopEntity12HQ",
        "identification_number": "8905045638",
        "identification_type": "NIT"
    },
    "payment": {
        "status": "PENDING",
        "reference": "Test payment",
        "account_id": "9bb99e5e-5bd0-44c9-944a-d01c9d8ffe21",
        "breb_recipient_id": "8e5dbe27-b17e-4366-a116-82f9c52bcdab",
        "amount": {
            "currency": "COP",
            "value": "100000"
        },
        "id": "cdb5ae4b-fd6e-4244-9e16-a4e6262f0fe2"
    }
}
Copy

The payment status will first be PENDING. Once the payment is processed, it will change to SETTLED. You can use the Webhooks to check the payment statuses.

The response will include the key resolution within the breb_resolved_key object. The resolution is necessary in Bre-B to start a payment. It provides information about the key's owner and can be used to verify ownership of the key.

Common Errors and Handling

HTTP Status Code	Meaning	Description
400 Bad Request	Invalid Data	Required fields are missing or contain incorrect values.
401 Unauthorized	Expired Token	The access token is invalid or has expired.
403 Forbidden	Access Denied	The request is not authorized to create a payment.
500 Internal Server Error	Server Error	An unexpected error occurred while processing the payment.

Best Practices

Ensure the account_id and breb_recipient_idare correct before making the request.
Use the reference to facilitate the auditing of a payment.
Monitor the payment status (PENDING, SETTLED, etc.) to track progress.
Implement error handling to manage failed or delayed payments.

Last updated on