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.

OAuth scopes: Requires one of: user.profile, user.profile_readonly, payouts.read.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes user.profileuser.profile_readonlypayouts.read

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MH4H92C7"

Query parameters

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

Example: "2024-02-01"
end_datestringrequired
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"
formatstring
Options:"json""csv"
default: "json"
Response format for the payout list.

Example: "json"
limitinteger
minimum: 1maximum: 9999
Maximum number of payout records to return.

Example: 10
orderstring
Options:"asc""desc"
default: "asc"
Sort direction for the returned payouts.

Example: "desc"

Responses

200application/json

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

idintegerrequired
format: int64
Unique identifier of the payout-related record.

Example: 123456789
typestringrequired
Options:"PAYOUT""CHARGE_BACK_DEDUCTION""REFUND_DEDUCTION""DD_RETURN_DEDUCTION""BALANCE_DEDUCTION"
High-level payout record category.

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

Example: 132.45
datestringrequired
format: 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
format: float
Fee amount associated with the payout record, in major units.

Example: 3.12
statusstringrequired
Options:"SUCCESSFUL""FAILED"
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"

text/plain

id,type,amount,date,currency,fee,status,reference,transaction_code
123456789,PAYOUT,132.45,2024-02-29,EUR,3.12,SUCCESSFUL,payout-2024-02-29,TEENSK4W2K

400application/json

The request is invalid for the submitted query parameters.

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"

401application/json

The request is not authorized.

typestringrequired
format: 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."
instancestring
format: 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"

GET

Code sample

curl --request GET \
  --url 'https://api.sumup.com/v1.0/merchants/MH4H92C7/payouts?start_date=2024-02-01&end_date=2024-02-29' \
  --header 'Authorization: Bearer <token>'

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.payouts.list(
    "MH4H92C7",
    {
      "start_date": "2024-02-01",
      "end_date": "2024-02-29"
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Payouts.ListAsync(
            "your-merchant-code",
            new PayoutsListOptions
            {
                StartDate = DateOnly.Parse("2025-01-01"),
                EndDate = DateOnly.Parse("2025-01-01"),
                Format = "example",
                Limit = 10,
                Order = "example",
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.payouts().list(
            "MH4H92C7",
            java.time.LocalDate.parse("2024-02-29"),
            java.time.LocalDate.parse("2024-02-01")
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.payouts.list(
    "MH4H92C7",
    start_date="2024-02-01",
    end_date="2024-02-29",
    format="json",
    limit=10,
    order="desc",
)
print(result)

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$queryParams = new \SumUp\Services\PayoutsListParams();
$queryParams->startDate = '2024-02-01';
$queryParams->endDate = '2024-02-29';
$queryParams->format = 'json';
$queryParams->limit = 10;
$queryParams->order = 'desc';

$result = $sumup->payouts()->list(
    'MH4H92C7',
    $queryParams,
);

var_dump($result);

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sumup/sumup-go"
	"github.com/sumup/sumup-go/datetime"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Payouts.List(context.TODO(), "MH4H92C7", sumup.PayoutsListParams{
		StartDate: datetime.NewDate(2024, time.February, 1),
		EndDate:   datetime.NewDate(2024, time.February, 29),
		Format:    new(sumup.PayoutsListFormat("json")),
		Limit:     new(10),
		Order:     new(sumup.PayoutsListOrder("desc")),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let response = client
        .payouts()
        .list(
            "MERCHANT_CODE",
            sumup::resources::payouts::ListParams::builder()
                .start_date("2024-01-01".parse().expect("valid date"))
                .end_date("2024-01-01".parse().expect("valid date"))
                .build(),
        )
        .await
        .expect("list request failed");
    println!("{response:#?}");
}

Response example

[
  {
    "amount": 132.45,
    "currency": "EUR",
    "date": "2024-02-29",
    "fee": 3.12,
    "id": 123456789,
    "reference": "payout-2024-02-29",
    "status": "SUCCESSFUL",
    "transaction_code": "TEENSK4W2K",
    "type": "PAYOUT"
  }
]

[
  {
    "error_code": "MISSING",
    "message": "Validation error: required",
    "param": "start_date"
  },
  {
    "error_code": "MISSING",
    "message": "Validation error: required",
    "param": "end_date"
  }
]

{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}