Skip to content
/
Payout details

Settlements API (1.0.0-rc2)

The Settlements API helps you with the reconciliation of payments, made by Ksutom to your bank account. Every payment has a unique payment_reference that can be found in the settlement reports and on your bank statement.

Read more on Settlement reports.

Download OpenAPI description
settlements.json
settlements.yaml
Languages
Servers
https://api.kustom.co/settlements/v1

Payout summary

Request

Returns a summary of payouts for each currency code in a date range.

Query
start_datestring(date-time)required

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z.

end_datestring(date-time)required

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full datetime like 2020-01-23T23:59:59Z.

currency_codestring

An optional currency code to filter the result for different currencies. If not provided the result returned in the response might include multiple results grouped by the currency. The currency should be provided by an ISO 4217 Currency Code like USD, EUR, AUD or GBP.

curl -i -X GET \
  'https://api.kustom.co/settlements/v1/payouts/summary?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&currency_code=string'

Responses

Payout summaries

Bodyapplication/jsonArray [
summary_total_fee_correction_amountinteger(int64)required

The total amount of fee correction, in minor units

Example: 550
summary_payout_date_startstring(date-time)required

ISO 8601 formatted date-time string

Example: "2016-12-14T07:52:26Z"
summary_total_release_amountinteger(int64)required

The total amount of money released from holdback, in minor units

Example: 550
summary_settlement_currencystringrequired

ISO 4217 Currency Code. Like USD, EUR, AUD or GBP.

Example: "USD"
summary_payout_date_endstring(date-time)required

ISO 8601 formatted date-time string

Example: "2016-12-14T07:52:26Z"
summary_total_tax_amountinteger(int64)required

The total amount of tax, in minor units

Example: 550
summary_total_settlement_amountinteger(int64)required

The total amount of the settlement in question, in minor units

Example: 550
summary_total_holdback_amountinteger(int64)required

The total amount of money withheld, in minor units

Example: 550
summary_total_reversal_amountinteger(int64)required

The total amount of reversals, in minor units

Example: 550
summary_total_return_amountinteger(int64)required

The total amount of returns, in minor units

Example: 550
summary_total_fee_amountinteger(int64)required

The total amount of fees, in minor units

Example: 500
summary_total_commission_amountinteger(int64)required

The total amount of commissions, in minor units

Example: 550
summary_total_sale_amountinteger(int64)required

The total amount of sales, in minor units

Example: 500
summary_total_repay_amountinteger(int64)required

The total amount of money that has been repaid by the merchant from the debt, in minor units

Example: 550
]
Response
application/json
[
  {
    "summary_total_fee_correction_amount": 550,
    "summary_payout_date_start": "2016-12-14T07:52:26Z",
    "summary_total_release_amount": 550,
    "summary_settlement_currency": "USD",
    "summary_payout_date_end": "2016-12-14T07:52:26Z",
    "summary_total_tax_amount": 550,
    "summary_total_settlement_amount": 550,
    "summary_total_holdback_amount": 550,
    "summary_total_reversal_amount": 550,
    "summary_total_return_amount": 550,
    "summary_total_fee_amount": 500,
    "summary_total_commission_amount": 550,
    "summary_total_sale_amount": 500,
    "summary_total_repay_amount": 550
  }
]

Payout details

Request

Returns a specific payout based on a given payment reference.

Path
payment_referencestringrequired

The reference id of the payout. Normally this reference can be found on your payment slip statement of your bank.

curl -i -X GET \
  'https://api.kustom.co/settlements/v1/payouts/{payment_reference}'

Responses

A payout

Bodyapplication/json
totalsobject(Totals)required
payment_referencestringrequired

The reference id of the payout

Example: "XISA93DJ"
payout_datestring(date-time)required

ISO 8601 formatted date-time string

Example: "2016-12-14T07:52:26Z"
currency_codestringrequired

ISO 4217 Currency Code. Like USD, EUR, AUD or GBP.

Example: "USD"
currency_code_of_registration_countrystring

ISO 4217 Currency Code of the country you are registered in.

Example: "EUR"
merchant_settlement_typestringrequired

Whether the amounts are net or gross

Enum"GROSS""NET""GROSS_FEE"
Example: "NET"
merchant_idstringrequired

The merchant id

transactionsstring

Link to the transactions that are part of this payout

Example: "https://{settlements_api}/transactions?payment_reference=XISA93DJ"
Response
application/json
{
  "totals": {
    "commission_amount": 550,
    "repay_amount": 550,
    "sale_amount": 500,
    "holdback_amount": 550,
    "tax_amount": 550,
    "settlement_amount": 550,
    "fee_correction_amount": 550,
    "reversal_amount": 550,
    "release_amount": 550,
    "return_amount": 550,
    "fee_amount": 500,
    "charge_amount": 500,
    "credit_amount": 500,
    "fee_refund_amount": 500,
    "tax_refund_amount": 500,
    "deposit_amount": 500,
    "opening_debt_balance_amount": 500,
    "closing_debt_balance_amount": 500
  },
  "payment_reference": "XISA93DJ",
  "payout_date": "2016-12-14T07:52:26Z",
  "currency_code": "USD",
  "currency_code_of_registration_country": "EUR",
  "merchant_settlement_type": "NET",
  "merchant_id": "string",
  "transactions": "https://{settlements_api}/transactions?payment_reference=XISA93DJ"
}

List all payouts

Request

Returns a collection of payouts.

Query
start_datestring(date-time)

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z.

end_datestring(date-time)

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full date time like 2020-01-23T23:59:59Z.

currency_codestring

An optional currency code to filter the result for different currencies. If not provided the result returned in the response might include multiple results grouped by the currency. The currency should be provided by an ISO 4217 Currency Code like USD, EUR, AUD or GBP.

sizeinteger(int64)<= 500

How many elements to include in the result. If no value for size is provided, a default of 20 will be used. A maximum of 500 can be set

Default 20
offsetinteger(int64)

The current offset. Describes "where" in a collection the current starts.

Default 0
curl -i -X GET \
  'https://api.kustom.co/settlements/v1/payouts?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&currency_code=string&size=20&offset=0'

Responses

A collection of payouts

Bodyapplication/json
payoutsArray of objects(Payout)required
paginationobject(Pagination)required
Response
application/json
{
  "payouts": [
    { … }
  ],
  "pagination": {
    "count": 10,
    "total": 42,
    "next": "http://example.com/collection?offset=21&size=10",
    "prev": "http://example.com/collection?offset=0&size=10",
    "offset": 10
  }
}

Get a payouts summary (CSV)

Request

More information about this CSV format is available at: https://docs.klarna.com/settlement-reports

Query
payment_referencestringrequired

The reference id of the payout

curl -i -X GET \
  'https://api.kustom.co/settlements/v1/reports/payout-with-transactions?payment_reference=string'

Responses

A payout

Get a payouts summary (PDF)

Request

A single settlement summed up in pdf format

Query
payment_referencestringrequired

The reference id of the payout

curl -i -X GET \
  'https://api.kustom.co/settlements/v1/reports/payout?payment_reference=string'

Responses

A payout

List transactions in a payout

Request

Returns a collection of transactions.

Query
payment_referencestring

The reference id of the payout

order_idstring

The Kustom assigned order id reference

sizeinteger(int64)<= 500

How many elements to include in the result. If no value for size is provided, a default of 20 will be used. A maximum of 500 can be set.

Default 20
offsetinteger(int64)

The current offset. Describes "where" in a collection the current starts.

Default 0
curl -i -X GET \
  'https://api.kustom.co/settlements/v1/transactions?payment_reference=string&order_id=string&size=20&offset=0'

Responses

A collection of payouts

Bodyapplication/json
transactionsArray of objects(Transaction)required
paginationobject(Pagination)required
Response
application/json
{
  "transactions": [
    { … }
  ],
  "pagination": {
    "count": 10,
    "total": 42,
    "next": "http://example.com/collection?offset=21&size=10",
    "prev": "http://example.com/collection?offset=0&size=10",
    "offset": 10
  }
}

Get a payouts summary with transactions (CSV)

Request

More information about this CSV format is available at: https://docs.klarna.com/settlement-reports

Query
start_datestring(date-time)required

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z.

end_datestring(date-time)required

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full date time like 2020-01-23T23:59:59Z.

curl -i -X GET \
  'https://api.kustom.co/settlements/v1/reports/payouts-summary-with-transactions?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z'

Responses

A summary of payouts

Get a payouts summary with transactions (PDF)

Request

Returns a summary for all payouts between the given dates

Query
start_datestring(date-time)required

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z.

end_datestring(date-time)required

ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full date time like 2020-01-23T23:59:59Z.

curl -i -X GET \
  'https://api.kustom.co/settlements/v1/reports/payouts-summary?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z'

Responses

A summary of payouts