Settlements

Settlements represent the payouts to your bank account. Each settlement aggregates the transactions processed within a clearing period and results in a single transfer to your configured IBAN. Use the Settlements API to retrieve settlement details, view linked payments, and reconcile payouts with your accounting system.

Settlements are only available in live mode. Test tokens will receive a 404 response. This is because test payments are never actually settled.

The Settlements API uses org-scoped authentication. Your bearer token grants access to all settlements across all acceptors within your organization, since settlements are aggregated at the organization level.

Discover the Settlements resource using Postman:

TapTree Postman Collection

Endpoints

Retrieve a settlement

GET/v1/settlements/:code

Fetch details of a specific settlement using its settlement code or ID.

List all settlements

GET/v1/settlements

Retrieve a paginated list of all settlements.

List settlement records

GET/v1/settlements/:code/records

Retrieve a paginated list of records (payments, refunds, chargebacks) linked to a settlement.

The settlement model

The settlement model contains all the details related to a payout to your bank account, including the amount, clearing account information, and clearing breakdowns by payment method. Individual records (payments, refunds, chargebacks, and other transaction types) are accessible via the links.records sub-resource.

Core attributes

Name
id
Type
string
Description
Unique identifier for the settlement, prefixed with stl_.
Name
object
Type
string
Description
The object type. Always settlement.
Name
org_id
Type
string
Description
Unique identifier for the organization this settlement belongs to.
Name
code
Type
string
Description
The settlement reference code. This matches the reference on your bank statement for easy reconciliation. Use this code to look up a specific settlement via the API.
Name
description
Type
string
Description
A human-readable description of the settlement, generated by TapTree from the number of clearings, the total amount, and the settlement date (e.g. Settlement of 3 clearings totalling EUR 1836.00 on 2026-02-28, or Settlement of 1 clearing totalling EUR 51.00 on 2024-12-19 when only one clearing is grouped). Currency in the description is uppercased for readability; the machine-readable amount.currency field remains lowercase ISO-4217.
Name
settlement_date
Type
date
Description
The date the settlement was paid out, in YYYY-MM-DD format.
Name
confirmation_date
Type
date
Description
The date the settlement was confirmed, in YYYY-MM-DD format.
Name
status
Type
string
Description
Status of the settlement.
Possible values: pending processing settled failed
Name
amount
Type
object
Description
The total settlement amount paid out to your bank account.
Name
clearing_account
Type
object
Description
The bank account the settlement was paid out to.
Name
clearings
Type
array
Description
List of clearing groups within this settlement. Each clearing contains clearing lines that break down the settlement by payment method.
Name
created_at
Type
datetime
Description
Timestamp of when the settlement was first synced, in ISO 8601 format.
Name
updated_at
Type
datetime
Description
Timestamp of when this settlement object was last updated.
Name
links
Type
object
Description
Links related to the settlement object.

Response object

{
 "object": "settlement",
 "id": "stl_7UhSN1zuXS",
 "org_id": "org_5A8hsNqGGyW",
 "code": "DZAU-L3U",
 "description": "Settlement of 1 clearing totalling EUR 1836.00 on 2026-02-28",
 "settlement_date": "2026-02-28",
 "confirmation_date": "2026-03-01",
 "status": "settled",
 "amount": {
   "value": "1836.00",
   "currency": "eur"
 },
 "clearing_account": {
   "method": "iban",
   "iban": "DE89370400440532013000",
   "bic": "COBADEFFXXX",
   "owner": "TapTree GmbH"
 },
 "clearings": [
   {
     "created_at": "2026-03-01T04:15:00.000000+00:00",
     "clearing_lines": [
       {
         "clearing_date": "2026-02-27",
         "value_date": "2026-02-27",
         "settlement_date": "2026-02-28",
         "state": "settled",
         "payment_method": "ideal",
         "direction": "credit",
         "collecting": true,
         "amount": {
           "value": "1836.00",
           "currency": "eur"
         },
         "transaction_count": 42,
         "unique_payers": 38
       }
     ]
   }
 ],
 "created_at": "2026-03-01T04:15:00.000000+00:00",
 "updated_at": "2026-03-03T04:00:00.000000+00:00",
 "links": {
   "api": {
     "href": "https://api.taptree.org/v1/settlements/DZAU-L3U",
     "type": "application/json"
   },
   "records": {
     "href": "https://api.taptree.org/v1/settlements/DZAU-L3U/records",
     "type": "application/json"
   }
 }
}

GET/v1/settlements/:code

Retrieve a Settlement

Fetch details of a specific settlement using its settlement code or ID. The settlement code is the reference that appears on your bank statement, making it easy to look up the details of any payout. You can also use the settlement's stl_ prefixed ID. The response includes full settlement details and clearing breakdowns. To access individual records linked to this settlement, use the GET /v1/settlements/:code/records endpoint.

Required parameters

Name
code
Type
string
Description
The settlement identifier. Accepts either the settlement reference code from your bank statement (e.g. DZAU-L3U) or the settlement ID (e.g. stl_7UhSN1zuXS).

Request

GET

/v1/settlements/DZAU-L3U

curl https://api.taptree.org/v1/settlements/DZAU-L3U \
  -H "Authorization: Bearer {token}"

Example response

{
  "object": "settlement",
  "id": "stl_7UhSN1zuXS",
  "org_id": "org_5A8hsNqGGyW",
  "code": "DZAU-L3U",
  "description": "Settlement of 1 clearing totalling EUR 1836.00 on 2026-02-28",
  "settlement_date": "2026-02-28",
  "confirmation_date": "2026-03-01",
  "status": "settled",
  "amount": {
    "value": "1836.00",
    "currency": "eur"
  },
  "clearing_account": {
    "method": "iban",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "owner": "TapTree GmbH"
  },
  "clearings": [
    {
      "created_at": "2026-03-01T04:15:00.000000+00:00",
      "clearing_lines": [
        {
          "clearing_date": "2026-02-27",
          "value_date": "2026-02-27",
          "settlement_date": "2026-02-28",
          "state": "settled",
          "payment_method": "card",
          "brand": "visa",
          "card_type": "credit",
          "funding_type": "consumer",
          "region": "intra_eea",
          "channel": "ecommerce",
          "direction": "credit",
          "collecting": true,
          "amount": {
            "value": "1836.00",
            "currency": "eur"
          },
          "transaction_count": 42,
          "unique_payers": 38
        }
      ]
    }
  ],
  "created_at": "2026-03-01T04:15:00.000000+00:00",
  "updated_at": "2026-03-03T04:00:00.000000+00:00",
  "links": {
    "api": {
      "href": "https://api.taptree.org/v1/settlements/DZAU-L3U",
      "type": "application/json"
    },
    "records": {
      "href": "https://api.taptree.org/v1/settlements/DZAU-L3U/records",
      "type": "application/json"
    }
  }
}

GET/v1/settlements

List all settlements

Retrieve a paginated list of all settlements for your organization. Settlements are ordered by creation date, newest first. Use limit, starting_after, and ending_before parameters for pagination.

Optional query parameters

Name
limit
Type
integer
|
Optional
optional
|
Default
default=10
Description
Specify the maximum number of settlements to return in one response, up to 100.
Name
starting_after
Type
string
|
Optional
optional
Description
A settlement code or id for cursor-based pagination. Returns settlements listed after the specified settlement. Accepts either the settlement code (e.g. DZAU-L3U) or the settlement ID (e.g. stl_7UhSN1zuXS).
Example: If the last settlement in your response has code DZAU-L3U, use starting_after=DZAU-L3U to fetch the next page.
Name
ending_before
Type
string
|
Optional
optional
Description
A settlement code or id for cursor-based pagination. Returns settlements listed before the specified settlement. Accepts either the settlement code or the settlement ID.
To view settlements preceding DZAU-L3U, include ending_before=DZAU-L3U in your request.

Request

GET

/v1/settlements

curl -G https://api.taptree.org/v1/settlements \
  -H "Authorization: Bearer {token}" \
  -d limit=20

Example response

{
  "has_more": true,
  "data": [
    {
      "object": "settlement",
      "id": "stl_7UhSN1zuXS",
      "org_id": "org_5A8hsNqGGyW",
      "code": "DZAU-L3U",
      "description": "Settlement of 1 clearing totalling EUR 1836.00 on 2026-02-28",
      "settlement_date": "2026-02-28",
      "confirmation_date": "2026-03-01",
      "status": "settled",
      "amount": {
        "value": "1836.00",
        "currency": "eur"
      },
      "clearing_account": {
        "method": "iban",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "owner": "TapTree GmbH"
      },
      "created_at": "2026-03-01T04:15:00.000000+00:00",
      "updated_at": "2026-03-03T04:00:00.000000+00:00",
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/settlements/DZAU-L3U",
          "type": "application/json"
        },
        "records": {
          "href": "https://api.taptree.org/v1/settlements/DZAU-L3U/records",
          "type": "application/json"
        }
      }
    }
  ]
}

GET/v1/settlements/:code/records

List settlement records

Retrieve a paginated list of individual records linked to a specific settlement. Records include payments, refunds, chargebacks, reversals, and other transaction types processed within the settlement period. Use this endpoint to reconcile which transactions are included in a payout.

Every record has an object field indicating its type and a direction field ("debit" or "credit"). Matched records — "payment", "refund", "chargeback" — include their full TapTree object with id, status, and links. Other record types only include basic transaction details (amount, payment method, date). Your integration should handle all object types gracefully.

Record types

The following object types may appear in the data array:

Object	Description
`payment`	A completed sale, linked to a TapTree payment.
`refund`	A reimbursement of an earlier sale, linked to a TapTree refund.
`chargeback`	A forced reimbursement initiated by the cardholder's bank, linked to a TapTree chargeback.
`chargeback_reversal`	Reversal of a chargeback (the bank reversed its decision in your favor).
`rollback`	A sale reversed by the payment method.

Use the optional type query parameter to filter by object type (e.g. ?type=payment, ?type=refund, ?type=chargeback, ?type=chargeback_reversal, ?type=rollback).

Required parameters

Name
code
Type
string
Description
The settlement identifier. Accepts either the settlement reference code (e.g. DZAU-L3U) or the settlement ID (e.g. stl_7UhSN1zuXS).

Optional query parameters

Name
type
Type
string
|
Optional
optional
Description
Filter records by object type. See the record types table above for all possible values. Omit to return all types.
Name
limit
Type
integer
|
Optional
optional
|
Default
default=10
Description
Maximum number of records to return, up to 100.
Name
starting_after
Type
string
|
Optional
optional
Description
A record or payment id for cursor-based pagination.
Name
ending_before
Type
string
|
Optional
optional
Description
A record or payment id for cursor-based pagination.

Request

GET

/v1/settlements/DZAU-L3U/records

curl -G https://api.taptree.org/v1/settlements/DZAU-L3U/records \
  -H "Authorization: Bearer {token}" \
  -d limit=25

Example response

{
  "has_more": true,
  "data": [
    {
      "object": "payment",
      "id": "pay_AzoSgo2h7mB",
      "direction": "debit",
      "org_id": "org_5A8hsNqGGyW",
      "acceptor_id": "acceptor_Aa54Z3THuFj",
      "status": "paid",
      "created_at": "2026-02-27T14:25:00.000000+00:00",
      "paid_at": "2026-02-27T14:30:00.000000+00:00",
      "description": "Order #1234",
      "payment_method": "ideal",
      "amount": {
        "value": "25.50",
        "currency": "eur"
      },
      "metadata": {
        "order_id": "1234"
      },
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/payments/pay_AzoSgo2h7mB",
          "type": "application/json"
        }
      }
    },
    {
      "object": "refund",
      "id": "rf_4KpQ7rW2xYn",
      "direction": "credit",
      "payment_id": "pay_AzoSgo2h7mB",
      "status": "refunded",
      "amount": {
        "value": "15.00",
        "currency": "eur"
      },
      "created_at": "2026-02-27T16:45:00.000000+00:00",
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/refunds/rf_4KpQ7rW2xYn",
          "type": "application/json"
        },
        "payment": {
          "href": "https://api.taptree.org/v1/payments/pay_AzoSgo2h7mB",
          "type": "application/json"
        }
      }
    },
    {
      "object": "chargeback",
      "id": "cb_8ZkT3mN9pRw",
      "direction": "credit",
      "payment_id": "pay_BcxR4tH6jKm",
      "status": "open",
      "reason": {
        "code": "10.1",
        "description": "EMV Liability Shift Counterfeit Fraud"
      },
      "amount": {
        "value": "25.50",
        "currency": "eur"
      },
      "deadline_at": "2026-03-15T23:59:59.000000+00:00",
      "created_at": "2026-03-01T10:30:00.000000+00:00",
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/chargebacks/cb_8ZkT3mN9pRw",
          "type": "application/json"
        },
        "payment": {
          "href": "https://api.taptree.org/v1/payments/pay_BcxR4tH6jKm",
          "type": "application/json"
        }
      }
    },
    {
      "object": "chargeback_reversal",
      "direction": "debit",
      "chargeback_id": "cb_8ZkT3mN9pRw",
      "payment_id": "pay_BcxR4tH6jKm",
      "amount": {
        "value": "25.50",
        "currency": "eur"
      },
      "payment_method": "visa",
      "transaction_date": "2026-03-10T11:00:00.000000+00:00"
    }
  ]
}