The Query Transactions endpoint lets you retrieve a paginated list of transactions processed on your POS terminals. Apply filters to narrow results by date range, BIN, card digits, or transaction reference.Returns a maximum of 10,000 transactions per query.
How it works#
POST /pos-analytics/v1/transactions/search — send pagination parameters and an optional filters object.{
"page": 1,
"size": 10,
"filters": {
"start_date": 1712286000000,
"end_date": 1712322035152,
"transaction_type": "charge"
}
}
Request fields#
| Field | Required | Description |
|---|
page | Yes | Page number. Starts at 1. |
size | Yes | Records per page. Maximum 500. |
filters | No | Optional filter object — see below. |
filters#
| Field | Type | Description |
|---|
start_date | integer | Start of the search window (Unix timestamp in ms). |
end_date | integer | End of the search window (Unix timestamp in ms). |
bin | string | First 6–8 digits of the card. |
last_four_digits | string | Last 4 digits of the card. |
client_transaction_id | string | Merchant-generated UUID for the transaction. |
transaction_reference | string | Kushki transaction reference. |
transaction_type | string | Type of transaction (e.g., "charge", "preAuth", "refund"). |
Response#
Returns an items array with one object per transaction.{
"items": [
{
"ticket_number": "111727462978861299",
"transaction_reference": "62c64ab2-1b09-48bd-ab98-4fa9b1893250",
"client_transaction_id": "61659d20-311c-4363-991d-7cdd73d36062",
"transaction_status": "APPROVED",
"transaction_type": "charge",
"payment_brand": "VISA",
"bin_card": "403338",
"last_four_digits": "6782",
"masked_credit_card": "403338XXXXXX6782",
"approved_transaction_amount": 231,
"amount": {
"currency": "PEN",
"subtotal_iva": 0,
"subtotal_iva0": 231,
"iva": 0,
"tip": 0
},
"approval_code": "123456",
"created": 1727462978861,
"country": "Peru",
"merchant_id": "20000000107334554000",
"merchant_name": "Mi Comercio Perú"
}
]
}
Response item fields#
Transaction identification| Field | Description |
|---|
ticket_number | Unique ticket number assigned by Kushki. |
transaction_id | Internal transaction identifier. |
transaction_reference | Merchant-facing transaction reference. |
client_transaction_id | UUID provided by the merchant at transaction time. |
approval_code | Issuer authorization code. |
| Field | Description |
|---|
transaction_status | APPROVED, DECLINED, VOIDED, or REFUNDED. |
transaction_type | Type of the transaction. |
payment_method | Payment method (e.g., "card"). |
payment_brand | Card network (e.g., "VISA", "MASTERCARD"). |
created | Transaction creation timestamp (Unix ms). |
country | Country where the transaction was processed. |
mcc | Merchant category code. |
| Field | Description |
|---|
bin_card | First 6–8 digits of the card. |
last_four_digits | Last 4 digits of the card. |
masked_credit_card | Masked card number. |
card_country | ISO country code of the card-issuing country. |
foreign_card | true if the card was issued outside Peru. |
issuing_bank | Name of the card-issuing bank. |
acquirer_bank | Acquiring bank name. |
| Field | Description |
|---|
request_amount | Amount originally requested. |
approved_transaction_amount | Amount actually approved. |
amount | Full amount breakdown object (currency, subtotals, IVA, tip). |
| Field | Description |
|---|
merchant_id | Merchant identifier. |
merchant_name | Merchant display name. |
metadata | Additional metadata attached to the transaction. |
Authentication#
Using the API#
https://api.kushkipagos.com/
Available Endpoints#
Query Transactions
Paginate through POS terminal transactions with optional filters by date, BIN, card digits, or transaction reference.
Got a suggestion on this documentation? Contact us.
