Payouts | SumUp Developer

The Payouts model will allow you to track funds you’ve received from SumUp.

You can receive a detailed payouts list with information like dates, fees, references and statuses, using the List payouts endpoint.

Endpoints

List payouts
GET/v1.0/merchants/{merchant_code}/payouts

The Financial Payouts object

Ordered list of payout and payout-deduction records.

[]FinancialPayout

Show attributes

idintegerrequired
Unique identifier of the payout-related record.

Example: 123456789
typestringrequired
Options: PAYOUTCHARGE_BACK_DEDUCTIONREFUND_DEDUCTIONDD_RETURN_DEDUCTIONBALANCE_DEDUCTION
High-level payout record category.

Example: "PAYOUT"
amountnumberrequired
Amount of the payout or deduction in major units.

Example: 132.45
datestringrequiredformat: date
Payout date associated with the record, in YYYY-MM-DD format.

Example: "2024-02-29"
currencystringrequired
Three-letter ISO 4217 currency code of the payout.

Example: "EUR"
feenumberrequired
Fee amount associated with the payout record, in major units.

Example: 3.12
statusstringrequired
Options: SUCCESSFULFAILED
Merchant-facing outcome of the payout record.

Example: "SUCCESSFUL"
referencestringrequired
Processor or payout reference associated with the record.

Example: "payout-2024-02-29"
transaction_codestringrequired
Transaction code of the original sale associated with the payout or deduction.

Example: "TEENSK4W2K"

1
[
2
  {
3
    "id": 123456789,
4
    "type": "PAYOUT",
5
    "amount": 132.45,
6
    "date": "2024-02-29",
7
    "currency": "EUR",
8
    "fee": 3.12,
9
    "status": "SUCCESSFUL",
10
    "reference": "payout-2024-02-29",
11
    "transaction_code": "TEENSK4W2K"
12
  }
13
]

Payouts

List payouts

GET/v1.0/merchants/{merchant_code}/payouts

Lists payout and payout-deduction records for the specified merchant account within the requested date range.

The response can include:

regular payouts (type = PAYOUT)
deduction records for refunds, chargebacks, direct debit returns, or balance adjustments

Results are sorted by payout date in the requested order.

Requires one of scopes:user.profileuser.profile_readonlypayouts.read

Path Parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MH4H92C7"

Query Parameters

start_datestringrequiredformat: date
Start date of the payout period filter, inclusive, in ISO8601 date format (YYYY-MM-DD).

Example: "2024-02-01"
end_datestringrequiredformat: date
End date of the payout period filter, inclusive, in ISO8601 date format (YYYY-MM-DD). Must be greater than or equal to start_date.

Example: "2024-02-29"
formatstringdefault: json
Options: jsoncsv
Response format for the payout list.

Example: "json"
limitintegerminimum: 1, maximum: 9999
Maximum number of payout records to return.

Example: 10
orderstringdefault: asc
Options: ascdesc
Sort direction for the returned payouts.

Example: "desc"

Response

Returns the list of payout and deduction records for the requested period. See FinancialPayouts object.

[]FinancialPayout

Show attributes

idintegerrequired
Unique identifier of the payout-related record.

Example: 123456789
typestringrequired
Options: PAYOUTCHARGE_BACK_DEDUCTIONREFUND_DEDUCTIONDD_RETURN_DEDUCTIONBALANCE_DEDUCTION
High-level payout record category.

Example: "PAYOUT"
amountnumberrequired
Amount of the payout or deduction in major units.

Example: 132.45
datestringrequiredformat: date
Payout date associated with the record, in YYYY-MM-DD format.

Example: "2024-02-29"
currencystringrequired
Three-letter ISO 4217 currency code of the payout.

Example: "EUR"
feenumberrequired
Fee amount associated with the payout record, in major units.

Example: 3.12
statusstringrequired
Options: SUCCESSFULFAILED
Merchant-facing outcome of the payout record.

Example: "SUCCESSFUL"
referencestringrequired
Processor or payout reference associated with the record.

Example: "payout-2024-02-29"
transaction_codestringrequired
Transaction code of the original sale associated with the payout or deduction.

Example: "TEENSK4W2K"

1
curl https://api.sumup.com/v1.0/merchants/{merchant_code}/payouts \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.payouts.list("MH4H92C7", "2024-02-01", "2024-02-29");

1
using System;
2
using System.Collections.Generic;
3
using System.Text.Json;
4
using System.Threading.Tasks;
5
using SumUp;
6

7
public static class Program
8
{
9
    public static async Task Main()
10
    {
11
        using var client = new SumUpClient();
12
        var response = await client.Payouts.ListAsync(
13
            "your-merchant-code",
14
            new PayoutsListOptions
15
            {
16
                StartDate = DateOnly.Parse("2025-01-01"),
17
                EndDate = DateOnly.Parse("2025-01-01"),
18
                Format = "example",
19
                Limit = 10,
20
                Order = "example",
21
            });
22

23
        Console.WriteLine(response.StatusCode);
24
    }
25
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class ListPayoutsV1Sample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    var result = client.payouts().list(
8
            "MH4H92C7",
9
            java.time.LocalDate.parse("2024-02-29"),
10
            java.time.LocalDate.parse("2024-02-01")
11
        );
12
    System.out.println(result);
13
  }
14
}

1
import os
2

3
import sumup
4

5

6
def main() -> None:
7
    client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
8

9
    result = client.payouts.list(
10
        "MH4H92C7",
11
        start_date="2024-02-01",
12
        end_date="2024-02-29",
13
        format="json",
14
        limit=10,
15
        order="desc",
16
    )
17
    print(result)
18

19

20
if __name__ == "__main__":
21
    main()

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->payouts->list('MH4H92C7', '2024-02-01', '2024-02-29');

1
package main
2

3
import (
4
  "context"
5
  "log"
6
  "time"
7

8
  "github.com/sumup/sumup-go"
9
  "github.com/sumup/sumup-go/datetime"
10
)
11

12
func main() {
13
  ctx := context.Background()
14
  client := sumup.NewClient()
15

16
  result, err := client.Payouts.List(ctx, "MH4H92C7", sumup.PayoutsListParams{
17
    StartDate: datetime.NewDate(2024, time.February, 1),
18
    EndDate:   datetime.NewDate(2024, time.February, 29),
19
    Format:    ptr(sumup.PayoutsListFormat("json")),
20
    Limit:     ptr(10),
21
    Order:     ptr(sumup.PayoutsListOrder("desc")),
22
  })
23
  if err != nil {
24
    log.Fatal(err)
25
  }
26

27
  log.Printf("%+v", result)
28
}
29

30
func ptr[T any](value T) *T {
31
  return &value
32
}

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.payouts().list("MH4H92C7", sumup::ListPayoutsV1Params{
6
    start_date: Some("2024-02-01".to_string()),
7
    end_date: Some("2024-02-29".to_string()),
8
    format: Some("json".to_string()),
9
    limit: Some(10),
10
    order: Some("desc".to_string()),
11
}).await;

1
[
2
  {
3
    "amount": 132.45,
4
    "currency": "EUR",
5
    "date": "2024-02-29",
6
    "fee": 3.12,
7
    "id": 123456789,
8
    "reference": "payout-2024-02-29",
9
    "status": "SUCCESSFUL",
10
    "transaction_code": "TEENSK4W2K",
11
    "type": "PAYOUT"
12
  }
13
]

Error 400
Error 401

Content-Type: application/json

The request is invalid for the submitted query parameters.

[]ErrorExtended

Show attributes

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"
paramstring
Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, card.name refers to the name parameter embedded in the card object.

Example: "card.name"

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Error 400
Error 401

1
[
2
  {
3
    "error_code": "MISSING",
4
    "message": "Validation error: required",
5
    "param": "start_date"
6
  },
7
  {
8
    "error_code": "MISSING",
9
    "message": "Validation error: required",
10
    "param": "end_date"
11
  }
12
]

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}