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.

The Financial Payouts object

Ordered list of payout and payout-deduction records.

[]FinancialPayout

Show attributes

id integer required

Unique identifier of the payout-related record.

Example: 123456789
type string required

Options: PAYOUTCHARGE_BACK_DEDUCTIONREFUND_DEDUCTIONDD_RETURN_DEDUCTIONBALANCE_DEDUCTION

High-level payout record category.

Example: "PAYOUT"
amount number required

Amount of the payout or deduction in major units.

Example: 132.45
date string required format: date

Payout date associated with the record, in YYYY-MM-DD format.

Example: "2024-02-29"
currency string required

Three-letter ISO 4217 currency code of the payout.

Example: "EUR"
fee number required

Fee amount associated with the payout record, in major units.

Example: 3.12
status string required

Options: SUCCESSFULFAILED

Merchant-facing outcome of the payout record.

Example: "SUCCESSFUL"
reference string required

Processor or payout reference associated with the record.

Example: "payout-2024-02-29"
transaction_code string required

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.

Required scopes: user.profileuser.profile_readonly

Path Parameters

merchant_code string required

Merchant code of the account whose payouts should be listed.

Example: "MH4H92C7"

Query Parameters

start_date string required format: date

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

Example: "2024-02-01"
end_date string required format: 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"
format string default: json

Options: jsoncsv

Response format for the payout list.

Example: "json"
limit integer minimum: 1, maximum: 9999

Maximum number of payout records to return.

Example: 10
order string default: 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

id integer required

Unique identifier of the payout-related record.

Example: 123456789
type string required

Options: PAYOUTCHARGE_BACK_DEDUCTIONREFUND_DEDUCTIONDD_RETURN_DEDUCTIONBALANCE_DEDUCTION

High-level payout record category.

Example: "PAYOUT"
amount number required

Amount of the payout or deduction in major units.

Example: 132.45
date string required format: date

Payout date associated with the record, in YYYY-MM-DD format.

Example: "2024-02-29"
currency string required

Three-letter ISO 4217 currency code of the payout.

Example: "EUR"
fee number required

Fee amount associated with the payout record, in major units.

Example: 3.12
status string required

Options: SUCCESSFULFAILED

Merchant-facing outcome of the payout record.

Example: "SUCCESSFUL"
reference string required

Processor or payout reference associated with the record.

Example: "payout-2024-02-29"
transaction_code string required

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 SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Payouts.ListAsync(
6
    "MH4H92C7",
7
    "2024-02-01",
8
    "2024-02-29"
9
);

1
import com.sumup.sdk.SumUpClient;
2

3
SumUpClient client = SumUpClient.builder().build();
4

5
var result = client.payouts().listPayoutsV1(
6
  "MH4H92C7",
7
  java.time.LocalDate.parse("2024-02-01"),
8
  java.time.LocalDate.parse("2024-02-29")
9
);

1
from sumup import Sumup
2

3
client = Sumup()
4

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

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

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

1
client := sumup.NewClient()
2

3
result, err := client.Payouts.List(context.Background(), "MH4H92C7", "2024-02-01", "2024-02-29")

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

message string

Short description of the error.

Example: "Resource not found"
error_code string

Platform code for the error.

Example: "NOT_FOUND"
param string

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.

Content-Type: application/json

The request is not authorized.

type string required format: uri

A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
title string

A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
status integer

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detail string

A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instance string format: uri

A URI reference that identifies the specific occurrence of the problem.

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
}