Get settlement

Settlements API v2
GEThttps://api.mollie.com/v2/settlements/*id*
Authentication:Organization access tokensApp access tokens

Successful payments, together with refunds, captures and chargebacks are collected into settlements, which are then paid out according to your organization’s payout schedule. By retrieving a single settlement, you can check which payments were paid out with it, when the settlement took place, and what invoices were created to invoice the costs in the settlement.

Beside payments, settlements can be composed of other entities such as refunds, chargebacks or captures.

Parameters

Replace id in the endpoint URL by the settlement’s ID, for example stl_jDk30akdN or by the settlement’s bank reference, for example 1234567.1804.03.

Response

200 application/hal+json

resourcestring
Indicates the response contains a settlement object. Will always contain settlement for this endpoint.
idstring
The settlement’s unique identifier, for example stl_jDk30akdN.
referencestring
The settlement’s bank reference, as found in your Mollie account and on your bank statement.
createdAtstring
The date on which the settlement was created, in ISO 8601 format.
settledAtstring
The date on which the settlement was settled, in ISO 8601 format. When requesting the open settlement or next settlement the return value is null.
statusstring

The status of the settlement.

Possible values:

  • open The settlement has not been closed yet.
  • pending The settlement has been closed and is being processed.
  • paidout The settlement has been paid out.
  • failed The settlement could not be paid out.
amountamount object

The total amount paid out with this settlement.

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the exact amount of the settlement in the given currency.
periodsobject

This object is a collection of Period objects, which describe the settlement by month in full detail.

Please note the periods are sorted by date. For example, the field may contain an object called 2018, which contains a Period object called 03. The Period object fields are listed below.

Show child parameters

revenuearray

An array of revenue objects containing the total revenue for each payment method during this period. Each object has the following fields.

Show child parameters

descriptionstring
A description of the revenue subtotal.
methodstring
The payment method ID, if applicable.
countinteger
The number of payments received for this payment method.
amountNetamount object

The net total of received funds for this payment method (excludes VAT).

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the net amount in the given currency.
amountVatamount object

The VAT amount applicable to the revenue.

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the VAT amount in the given currency.
amountGrossamount object

The gross total of received funds for this payment method (includes VAT).

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the gross amount in the given currency.
costsarray

An array of Cost objects, describing the fees withheld for each payment method during this period. Each object has the following fields.

Show child parameters

descriptionstring
A description of the subtotal.
methodstring
The payment method ID, if applicable.
countinteger
The number of times costs were made for this payment method.
rateobject

The service rates, further divided into fixed and percentage costs.

Show child parameters

fixedamount object

An amount object describing the fixed costs.

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the fixed amount in the given currency.
variablestring
A string describing the variable costs as a percentage.
amountNetamount object

The net total costs for this payment method (excludes VAT).

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the net amount in the given currency.
amountVatamount object

The VAT amount applicable to the costs.

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the VAT amount in the given currency.
amountGrossamount object

The gross total costs for this payment method (includes VAT).

Show child parameters

currencystring
The ISO 4217 currency code.
valuestring
A string containing the gross amount in the given currency.
invoiceIdstring

The ID of the invoice that was created to invoice specifically the costs in this month/period.

If an individual month/period has not been invoiced yet, then this field will not be present until that invoice is created.

invoiceIdstring

The ID of the invoice on which this settlement is invoiced, if it has been invoiced.

Warning

This field has been deprecated in favor of the invoiceId field inside each monthly period in the periods object.

This was done because settlements nowadays have each monthly period invoiced separately, in which case this ID will reference only the oldest invoice. This can result in incorrect bookkeeping.

For this reason the field should no longer be used. Use the aforementioned invoiceId field of the individual monthly period objects instead.

_linksobject

An object with several URL objects relevant to the settlement. Every URL object will contain an href and a type field.

Show child parameters

selfURL object
The API resource URL of the settlement itself.
paymentsURL object
The API resource URL of the payments that are included in this settlement.
refundsURL object
The API resource URL of the refunds that are included in this settlement.
chargebacksURL object
The API resource URL of the chargebacks that are included in this settlement.
capturesURL object
The API resource URL of the captures that are included in this settlement.
invoiceURL object
The API resource URL of the invoice that contains this settlement.
documentationURL object
The URL to the settlement retrieval endpoint documentation.

Example

cURLPHPPythonRubyNode.js
1
2
3
4
5
6
7
curl -X GET https://api.mollie.com/v2/settlements/stl_jDk30akdN \
   -H "Authorization: Bearer access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ"

# or, by bank reference

curl -X GET https://api.mollie.com/v2/settlements/1234567.1804.03 \
   -H "Authorization: Bearer access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ"

1
2
3
4
5
6
7
8
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setAccessToken("access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ");
$settlement = $mollie->settlements->get("stl_jDk30akdN");

// or, by bank reference

$settlement = $mollie->settlements->get("1234567.1804.03");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from mollie.api.client import Client

mollie_client = Client()
mollie_client.set_access_token('access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ')

settlement = mollie_client.settlements.get('stl_jDk30akdN')

# or, by bank reference

settlement = mollie_client.settlements.get('1234567.1804.03')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
require 'mollie-api-ruby'

Mollie::Client.configure do |config|
  config.api_key = 'access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ'
end

settlement = Mollie::Settlement.get('stl_jDk30akdN')

# or, by bank reference

settlement = Mollie::Settlement.get('1234567.1804.03')

1
2
3
4
We don't have a Node.js code example for this API call yet.

If you have some time to spare, feel free to open a pull request at:
https://github.com/mollie/api-documentation

Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "resource": "settlement",
    "id": "stl_jDk30akdN",
    "reference": "1234567.1804.03",
    "createdAt": "2018-04-06T06:00:01.0Z",
    "settledAt": "2018-04-06T09:41:44.0Z",
    "status": "paidout",
    "amount": {
        "value": "39.75",
        "currency": "EUR"
    },
    "periods": {
        "2018": {
            "04": {
                "revenue": [
                    {
                        "description": "iDEAL",
                        "method": "ideal",
                        "count": 6,
                        "amountNet": {
                            "value": "86.1000",
                            "currency": "EUR"
                        },
                        "amountVat": null,
                        "amountGross": {
                            "value": "86.1000",
                            "currency": "EUR"
                        }
                    },
                    {
                        "description": "Refunds iDEAL",
                        "method": "refund",
                        "count": 2,
                        "amountNet": {
                            "value": "-43.2000",
                            "currency": "EUR"
                        },
                        "amountVat": null,
                        "amountGross": {
                            "value": "43.2000",
                            "currency": "EUR"
                        }
                    }
                ],
                "costs": [
                    {
                        "description": "iDEAL",
                        "method": "ideal",
                        "count": 6,
                        "rate": {
                            "fixed": {
                                "value": "0.3500",
                                "currency": "EUR"
                            },
                            "percentage": null
                        },
                        "amountNet": {
                            "value": "2.1000",
                            "currency": "EUR"
                        },
                        "amountVat": {
                            "value": "0.4410",
                            "currency": "EUR"
                        },
                        "amountGross": {
                            "value": "2.5410",
                            "currency": "EUR"
                        }
                    },
                    {
                        "description": "Refunds iDEAL",
                        "method": "refund",
                        "count": 2,
                        "rate": {
                            "fixed": {
                                "value": "0.2500",
                                "currency": "EUR"
                            },
                            "percentage": null
                        },
                        "amountNet": {
                            "value": "0.5000",
                            "currency": "EUR"
                        },
                        "amountVat": {
                            "value": "0.1050",
                            "currency": "EUR"
                        },
                        "amountGross": {
                            "value": "0.6050",
                            "currency": "EUR"
                        }
                    }
                ],
                "invoiceId": "inv_FrvewDA3Pr"
            }
        }
    },
    "invoiceId": "inv_FrvewDA3Pr",
    "_links": {
        "self": {
            "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN",
            "type": "application/hal+json"
        },
        "invoice": {
             "href": "https://api.mollie.com/v2/invoices/inv_FrvewDA3Pr",
             "type": "application/hal+json"
        },
        "payments": {
            "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/payments",
            "type": "application/hal+json"
        },
        "refunds": {
            "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/refunds",
            "type": "application/hal+json"
        },
        "chargebacks": {
            "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/chargebacks",
            "type": "application/hal+json"
        },
        "captures": {
            "href": "https://api.mollie.com/v2/settlements/stl_jDk30akdN/captures",
            "type": "application/hal+json"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/settlements-api/get-settlement",
            "type": "text/html"
        }
    }
}