Settlement

Query merchant settlement records on demand in JSON format, replacing the need to wait for a daily CSV file delivery.

Keep in mind!

This endpoint requires your Private Key (private-merchant-id) for authentication. Never expose it in client-side code.

Query Modes

The same POST /merchant-settlement/v1/settlement endpoint supports two modes:

By Date Range

Send startDate and endDate to retrieve a paginated list of settlement records for a specific period. Default: page 1, limit 100.

By Ticket Number

Send a ticketNumber to retrieve the settlement record for a specific transaction. Returns a single record. Requires the switch query parameter.

By date range

By ticket number

{
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "page": 1,
  "limit": 50
}

Field	Required	Default	Description
`startDate`	✅	—	Start of the period. Format: `YYYY-MM-DD`
`endDate`	✅	—	End of the period. Format: `YYYY-MM-DD`
`page`	❌	`1`	Page number to retrieve
`limit`	❌	`100`	Max records per page

{
  "data": [ { ...settlement record... } ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 101335,
    "totalPages": 2027
  }
}

When querying by ticketNumber, data always contains exactly one record.

Transaction

Amounts & Fees

Card

Field	Description
`ticket_number`	Kushki ticket number for this transaction
`sale_ticket_number`	Original sale ticket. Populated for voids and refunds; empty for sales
`transaction_type`	`SALE`, `VOID`, `REFUND`, `PREAUTHORIZATION`, `CAPTURE`
`transaction_status`	`APPROVED`, `DECLINED`, `VOIDED`, `REFUNDED`
`payment_method`	Payment method used (e.g., `CARD`)
`created`	Transaction creation date (`YYYY-MM-DD`)
`payment_date`	Date the settlement was paid to the merchant (`YYYY-MM-DD`)
`credential_alias`	Alias of the credential used
`recap`	Reconciliation code
`buy_order`	Merchant-provided order reference
`document_number`	Customer document number, if applicable
`processor_type`	Processing model (e.g., `AGGREGATOR_FORMAL`, `ACQUIRER`)
`observation`	Additional note, if any

HTTP	Code	Message	Cause
`400`	`K001`	El cuerpo de la petición es inválido	Malformed or missing required fields
`401`	`K004`	Id de comercio no válido	Invalid or missing `private-merchant-id`
`404`	`K037`	Registro de liquidación no encontrado	No settlement record found for the given `ticketNumber`
`500`	`K002`	Ha ocurrido un error inesperado	Unexpected server-side error

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Query Settlement

Retrieves settlement records by date range or by ticket number. Requires Private Merchant ID.

Got a suggestion on this documentation? Contact us.