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

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

Response

HTTP Status Code: 200 OK.

Example of Response

JSON
    
 
{
    "pagination_info": {...},
    "payments": [...]
}
Copy

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