SETTLEMENT
Query Settlement
POST /merchant-settlement/v1/settlementMode 1 — Query by date range
startDate and endDate to retrieve all settlement records for the specified period. Results are paginated.| Field | Required | Description |
|---|---|---|
startDate | ✅ | Start of the settlement period, in YYYY-MM-DD format |
endDate | ✅ | End of the settlement period, in YYYY-MM-DD format |
page | Page number to retrieve. Default: 1 | |
limit | Records per page. Default: 100 |
{
"startDate": "2026-01-01",
"endDate": "2026-01-31",
"page": 1,
"limit": 50
}Mode 2 — Query by ticket number
ticketNumber to retrieve the settlement record for a specific transaction. Returns exactly one record in the data array. Also include the switch query parameter.| Field | Required | Description |
|---|---|---|
ticketNumber | ✅ | Ticket number returned by Kushki at charge or capture time |
| Parameter | Value | Description |
|---|---|---|
switch | ecommerce | Payment channel scope — use ecommerce for online transactions |
POST /merchant-settlement/v1/settlement?switch=ecommerce{
"ticketNumber": "821775714399469939"
}Response
data array of settlement records and a pagination object.pagination fields
| Field | Description |
|---|---|
page | Current page number |
limit | Max records per page |
total | Total records available for the queried period |
totalPages | Total pages based on the current limit |
Settlement record fields
| Field | Description |
|---|---|
ticket_number | Unique Kushki ticket number for this transaction |
sale_ticket_number | Ticket of the original sale. Populated for voids and refunds; empty for sales |
buy_order | Merchant-provided order reference |
recap | Reconciliation code for the transaction |
document_number | Document number associated with the transaction, if applicable |
approval_code | Authorization code returned by the issuer |
| Field | Description |
|---|---|
created | Date the transaction was created (YYYY-MM-DD) |
payment_date | Date the settlement payment was made to the merchant (YYYY-MM-DD) |
day / month | Day and month extracted from the transaction creation date |
transaction_type | SALE, VOID, REFUND, PREAUTHORIZATION, or CAPTURE |
transaction_status | APPROVED, DECLINED, VOIDED, or REFUNDED |
payment_method | Payment method used (e.g., CARD) |
number_of_months | Deferred months applied. "0" for non-deferred transactions |
metadata | Custom metadata attached at charge time, if any |
observation | Additional notes on the record, if any |
| Field | Description |
|---|---|
merchant_id | Unique identifier of your merchant account |
merchant_name | Display name of your merchant account |
credential_alias | Alias of the credential used for the transaction |
processor_type | Processing model (e.g., AGGREGATOR_FORMAL, ACQUIRER) |
country | Country where the transaction was processed |
currency_code | Always COP for Colombia |
| Field | Description |
|---|---|
bin_card | First 6 digits of the card (BIN) |
card_brand | Card network (e.g., VISA, MASTERCARD) |
card_type | CREDIT, DEBIT, or PREPAID |
foreign_card | "TRUE" if the card was issued outside Colombia |
issuing_bank | Name of the card-issuing bank |
| Field | Description |
|---|---|
cash_pin | Cash PIN for the transaction, if applicable |
payment_point | Cash payment point identifier, if applicable |
| Field | Description |
|---|---|
approved_transaction_amount | Total amount approved for the transaction |
subtotal_iva | Subtotal subject to VAT |
subtotal_iva0 | Subtotal not subject to VAT |
iva_value | VAT amount applied to the transaction |
ice_value | ICE tax amount (Impuesto a Consumos Especiales) |
| Field | Description |
|---|---|
variable_fee | Variable fee amount charged by Kushki |
variable_percentage | Variable fee rate applied, as a percentage |
static_amount | Fixed fee charged per transaction |
min_fee_amount | Minimum fee amount applied |
kushki_commission | Total Kushki commission (variable_fee + static_amount) |
iva_kushki_commission | VAT on the Kushki commission |
kushki_amount | Total retained by Kushki (kushki_commission + iva_kushki_commission) |
commission_msi | Commission for months-without-interest deferred payments |
iva_msi | VAT on the MSI commission |
fraud_retention | Amount retained for fraud prevention |
adjustment | Manual adjustment applied to the record |
wallet | Amount associated with wallet operations, if applicable |
fund_release | Amount released from a previously held fund |
pay_amount | Net amount paid to the merchant — approved_transaction_amount minus all fees and retentions |
Example Response
{
"data": [
{
"payment_date": "2026-03-10",
"created": "2026-03-08",
"country": "Colombia",
"currency_code": "COP",
"merchant_name": "Mi Comercio Colombia",
"transaction_status": "APPROVED",
"ticket_number": "821773035999295672",
"transaction_type": "SALE",
"payment_method": "CARD",
"card_brand": "VISA",
"card_type": "DEBIT",
"approval_code": "000314",
"approved_transaction_amount": "105000.00",
"subtotal_iva": "0.0",
"subtotal_iva0": "105000.00",
"iva_value": "0.0",
"variable_fee": "2993.85",
"variable_percentage": "2.85309",
"kushki_commission": "2993.85",
"iva_kushki_commission": "569.83",
"kushki_amount": "3563.68",
"fraud_retention": "0.00",
"adjustment": "0.00",
"pay_amount": "101436.32"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1245,
"totalPages": 25
}
}Authentication
⚠️ Keep this credential secure. Never expose your private-merchant-idin client-side or frontend code.
Using the API
🟢 Production
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Available Endpoints
Got a suggestion on this documentation? Contact us.
Modified at 2026-07-11 00:04:34