Settlement

The Settlement endpoint gives you programmatic access to your settlement records. Use it to reconcile transactions, verify fee calculations, and build payout reports.

Two query modes are available in a single endpoint:

Date range — retrieve a paginated list of all settlement records within a time window.

Ticket number — retrieve the settlement record for a specific transaction.

Query by date range

Include startDate and endDate in the request body. Returns a paginated list.

{
  "startDate": "2026-04-01",
  "endDate": "2026-04-30",
  "page": 1,
  "limit": 100
}

Field	Required	Description
`startDate`	Yes	Start of the settlement period (`YYYY-MM-DD`).
`endDate`	Yes	End of the settlement period (`YYYY-MM-DD`).
`page`	No	Page number. Default: `1`.
`limit`	No	Records per page. Default: `100`.

Query by ticket number

Include a ticketNumber to retrieve the settlement record for a specific transaction. Also pass the switch query parameter to specify the payment channel.

{
  "ticketNumber": "821773035999295672"
}

Field	Required	Description
`ticketNumber`	Yes	Ticket number of the transaction to look up.

Response structure

Both modes return a data array of settlement records and a pagination object.

{
  "data": [
    {
      "payment_date": "2026-04-10",
      "country": "Peru",
      "currency_code": "PEN",
      "merchant_name": "Mi Comercio Perú",
      "transaction_status": "APPROVED",
      "transaction_type": "SALE",
      "approved_transaction_amount": "250.00",
      "kushki_commission": "7.13",
      "iva_kushki_commission": "1.14",
      "kushki_amount": "8.27",
      "pay_amount": "241.73"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 435,
    "totalPages": 5
  }
}

Settlement record fields

Transaction identification

Field	Description
`ticket_number`	Unique ticket number assigned by Kushki.
`sale_ticket_number`	Ticket of the original sale (for voids/refunds).
`approval_code`	Issuer authorization code.
`buy_order`	Merchant-provided order reference.
`recap`	Reconciliation code.

Transaction details

Field	Description
`payment_date`	Date the settlement was paid to the merchant (`YYYY-MM-DD`).
`created`	Transaction creation date (`YYYY-MM-DD`).
`transaction_status`	`APPROVED`, `DECLINED`, `VOIDED`, or `REFUNDED`.
`transaction_type`	`SALE`, `VOID`, `REFUND`, `PREAUTHORIZATION`, or `CAPTURE`.
`payment_method`	Payment method used (e.g., `CARD`, `CASH`, `TRANSFER`).
`currency_code`	Transaction currency (`PEN` or `USD`).
`country`	Country where the transaction was processed.

Card details

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 Peru.
`issuing_bank`	Name of the card-issuing bank.
`number_of_months`	Deferred months (`"0"` for non-deferred).

Amounts and fees

Field	Description
`approved_transaction_amount`	Total amount charged to the customer.
`subtotal_iva`	Subtotal subject to VAT.
`subtotal_iva0`	Subtotal not subject to VAT.
`iva_value`	VAT amount.
`ice_value`	ICE tax amount.
`variable_fee`	Variable fee amount charged by Kushki.
`variable_percentage`	Variable fee rate (%).
`static_amount`	Fixed fee per transaction.
`kushki_commission`	Total Kushki commission (fees).
`iva_kushki_commission`	VAT on the Kushki commission.
`kushki_amount`	Total retained by Kushki (commission + VAT).
`pay_amount`	Net amount paid to the merchant after all deductions.
`fraud_retention`	Amount retained for fraud prevention.
`adjustment`	Manual adjustment applied to the record.
`fund_release`	Amount released from a previously held fund.

Other

Field	Description
`processor_type`	Processing model (`AGGREGATOR_FORMAL`, etc.).
`credential_alias`	Alias of the credential used for the transaction.
`merchant_id`	Merchant identifier.
`merchant_name`	Merchant display name.
`document_number`	Document number associated with the transaction.
`cash_pin`	Cash PIN, if applicable.
`payment_point`	Payment point identifier for cash transactions.
`metadata`	Additional metadata attached to the transaction.
`observation`	Notes associated with the settlement record.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Query Settlement Records

Retrieve settlement records by date range or by a specific ticket number. Returns transaction amounts, fees, Kushki commissions, and the net pay amount.

Got a suggestion on this documentation? Contact us.

Query by date range#

Query by ticket number#

Response structure#

Settlement record fields#

Authentication#

Using the API#