List Payments

Overview

This endpoint retrieves a paginated list of Payments associated with an entity’s Customer. It provides details such as status, direction, recipient, amount, and references for reconciliation and monitoring.

Endpoint Details

Definition	Description
Endpoint	https://api.paas-sandbox.co.passportfintech.com/v1/payments
Method	GET
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Query Paramaters

Pagination Parameters

Parameter	Description
page_params.page_size	Number of records to return per page.
page_params.page_number	Page number to retrieve.
page_params.first_request_timestamp.seconds	UTC seconds since Unix epoch (`1970-01-01T00:00:00Z`).
page_params.first_request_timestamp.nanos	Nanosecond fraction (0 to 999,999,999).

Ordering Parameters

Parameter	Description
order_params.order_key	Field used to sort results (for example, `created_at` or `updated_at`, depending on supported values).
order_params.order_direction	Sort direction. Allowed values: `ORDER_DIRECTION_ENUM_UNSPECIFIED`, `ASC`, `DESC`.

Payment Filters

Parameter	Description
payment_id	Filter by payment ID.
customer_id	Filter by customer ID.
account_id	Filter by account ID.
direction	Filter by payment direction (for example, `INBOUND` / `OUTBOUND`).
key_value	Filter by Bre-B key value associated with the payment.
status	Filter by payment status.
qr_code_reference	Filter by QR code reference.
type	Filter by payment type.
end_to_end_identification	Filter by the unique identifier in the Bre-B ecosystem.

Sender Filters

Parameter	Description
sender_type	Filter by sender owner type (for example, `INDIVIDUAL`, `BUSINESS`).
sender_name	Filter by sender name.
sender_identification_type	Filter by sender identification type (for example, `CC`, `NIT`).
sender_identification_number	Filter by sender identification number.
sender_account_type	Filter by sender account type.
sender_account_number	Filter by sender account number.
sender_participant_name	Filter by sender participant name.
sender_participant_identification_number	Filter by sender participant identification number.

Receiver Filters

Parameter	Description
receiver_type	Filter by receiver owner type (for example, `INDIVIDUAL`, `BUSINESS`).
receiver_name	Filter by receiver name.
receiver_identification_type	Filter by receiver identification type (for example, `CC`, `NIT`).
receiver_identification_number	Filter by receiver identification number.
receiver_account_type	Filter by receiver account type.
receiver_account_number	Filter by receiver account number.
receiver_participant_name	Filter by receiver participant name.
receiver_participant_identification_number	Filter by receiver participant identification number.

Creation Time Filters

Parameter	Description
created_at_after.seconds	Lower bound (inclusive) for payment creation time, in UTC seconds since Unix epoch.
created_at_after.nanos	Nanosecond fraction for `created_at_after` (0 to 999,999,999).
created_at_before.seconds	Upper bound (inclusive/exclusive depending on implementation) for payment creation time, in UTC seconds since Unix epoch.
created_at_before.nanos	Nanosecond fraction for `created_at_before` (0 to 999,999,999).

Update Time Filters

Parameter	Description
updated_at_after.seconds	Lower bound for payment update time, in UTC seconds since Unix epoch.
updated_at_after.nanos	Nanosecond fraction for `updated_at_after` (0 to 999,999,999).
updated_at_before.seconds	Upper bound for payment update time, in UTC seconds since Unix epoch.
updated_at_before.nanos	Nanosecond fraction for `updated_at_before` (0 to 999,999,999).

Request Body

This endpoint does not require a request body.

Example Request

curl --location 'https://api.paas.sandbox.co.passportfintech.com/v1/payments' \ --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \

Response

HTTP Status Code: 200 OK.

Example of Response

{ "pagination_info": { "total_pages": 1, "total_elements": 2, "first_request_timestamp": "2025-10-10T11:37:22.204Z", "current_page": 1 }, "payments": [ { "qr_code_reference": "", "receiver": { "account": { "account_number": "88509775041", "account_type": "ORDINARY" }, "owner": { "identification_type": "NIT", "identification_number": "862886878", "type": "BUSINESS", "name": "Merchant CWSPZ" }, "key": { "key_type": "PHONE", "key_value": "3975999158" }, "participant": { "identification_number": "123456789" } }, "direction": "OUTBOUND", "amount": { "value": "100000", "currency": "COP" }, "error": { "error_description": "B002", "error_code": "B002" }, "sender": { "participant": { "identification_number": "123456789" }, "account": { "account_number": "88509775041", "account_type": "ORDINARY" }, "owner": { "identification_type": "NIT", "identification_number": "862886878", "type": "BUSINESS", "name": "Merchant CWSPZ" } }, "account_id": "a9a0e0f7-0263-44ee-911e-d66910f9f5c7", "resolution_id": "86a3bd39-906d-4a3a-b66e-4964629e7885", "created_at": "2025-10-10T08:44:07.642Z", "updated_at": "2025-10-10T08:44:17.165Z", "status": "REJECTED", "id": "ad8bac4b-3047-472a-ab59-9483d40109b8" }, { "qr_code_reference": "", "receiver": { "account": { "account_number": "88509775041", "account_type": "ORDINARY" }, "owner": { "identification_type": "NIT", "identification_number": "862886878", "type": "BUSINESS", "name": "Merchant CWSPZ" }, "key": { "key_type": "PHONE", "key_value": "3975999158" }, "participant": { "identification_number": "123456789" } }, "direction": "OUTBOUND", "amount": { "value": "100000", "currency": "COP" }, "error": { "error_description": "B002", "error_code": "B002" }, "sender": { "participant": { "identification_number": "123456789" }, "account": { "account_number": "88509775041", "account_type": "ORDINARY" }, "owner": { "identification_type": "NIT", "identification_number": "862886878", "type": "BUSINESS", "name": "Merchant CWSPZ" } }, "account_id": "a9a0e0f7-0263-44ee-911e-d66910f9f5c7", "resolution_id": "9e5cd615-d2da-43eb-866e-c0026b177c01", "created_at": "2025-10-10T08:52:05.171Z", "updated_at": "2025-10-10T08:52:13.570Z", "status": "REJECTED", "id": "0d9f17a1-af37-4e4d-831d-3520b5797aa1" } ] }

Common Errors and Handling

HTTP Status Code	Meaning	Description
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing/expired bearer token, or token lacks `paas.core.breb_payments.list.get` scope
403	Forbidden	Caller does not have permission to list payments
404	Not Found	No payments exist for the entity
500	Server Error	Unexpected error; retry or contact support

Best Practices

Use the pagination_info object to iterate through large payment histories.
Filter by status to track operational flows.
Leverage direction (OUTBOUND, INBOUND) for settlement and reconciliation.
Store and log id, reference, and updated_at for auditing purposes.
Combine with Retrieve Payment (GET /payments/{id}) to get detailed transaction information when needed.

Last updated on