List transactions

GET/v2.1/merchants/{merchant_code}/transactions/history

Lists transaction history for the merchant, with optional filters for payment type, status, and date range. The response contains the current page in items and pagination query strings in links.

To request another page, use the query string from the relevant link's href with this history endpoint. Use changes_since when retrieving transactions modified since a previous synchronization, including transactions created earlier whose status has changed.

OAuth scopes: Requires one of: transactions.history, transactions.read.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes transactions.historytransactions.read

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MH4H92C7"

Query parameters

transaction_codestring
Retrieves the transaction resource with the specified transaction code.

Example: "TEENSK4W2K"
orderstring
Options:"ascending""descending"
default: "ascending"
Sort direction for the transaction history. Use ascending or descending; the default is ascending.
limitinteger
Maximum number of transactions per page. Must be a positive integer. Defaults to 10 when omitted; a page can contain fewer results.

Example: 10
users[]array<string>
Filters transactions by user email. For multiple values, repeat the query parameter, for example users[]=first@example.com&users[]=second@example.com.

Example: ["merchant@example.com"]
statuses[]array<string>
Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example statuses[]=SUCCESSFUL&statuses[]=REFUNDED.

Example: ["SUCCESSFUL","REFUNDED"]
payment_types[]array<string>
Filters the returned results by the specified list of payment types used for the transactions.

Example: ["ECOM","POS"]
entry_modes[]array<string>
Filters the returned results by the specified list of entry modes.

Example: ["CUSTOMER_ENTRY","CHIP"]
types[]array<string>
Filters the returned results by the specified list of transaction types.

Example: ["PAYMENT","REFUND"]
changes_sincestring
format: date-time
Filters the results by the latest modification time of resources and returns only transactions that are modified at or after the specified timestamp (in ISO8601 format).

Example: "2019-08-28T09:00:00Z"
newest_timestring
format: date-time
Filters the results by the creation time of resources and returns only transactions that are created before the specified timestamp (in ISO8601 format).

Example: "2019-08-29T09:00:00Z"
newest_refstring
Pagination reference that returns results before the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over newest_time when both are provided.

Example: "090df9bf-93b7-40f1-8181-fbdb236568a1"
oldest_timestring
format: date-time
Filters the results by the creation time of resources and returns only transactions that are created at or after the specified timestamp (in ISO8601 format).

Example: "2019-08-28T09:00:00Z"
oldest_refstring
Pagination reference that returns results after the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over oldest_time when both are provided.

Example: "090df9bf-93b7-40f1-8181-fbdb236568a1"

Responses

200application/json

Returns a page of transaction history items.

itemsarray<unknown>
Transactions in the current result page.

Example: [{"transaction_code":"TEENSK4W2K","amount":10.1,"currency":"EUR","timestamp":"2020-02-29T10:56:56.876Z","status":"SUCCESSFUL","payment_type":"ECOM","installments_count":1,"merchant_code":"MH4H92C7","transaction_id":"410fc44a-5956-44e1-b5cc-19c6f8d727a4","user":"merchant@example.com","type":"PAYMENT","payout_date":"2019-08-28","payout_type":"BANK_ACCOUNT","refunded_amount":0}]
Show 20 properties
- idstring
  Unique identifier of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  SumUp transaction code, for example TEENSK4W2K. Use it to look up the transaction with the transaction_code query parameter. This is separate from the transaction's id and the card issuer's auth_code.
  
  Example: "TEENSK4W2K"
- amountnumber
  format: float
  Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.
  
  Example: 10.1
- currencystring
  Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
  Three-letter ISO 4217 currency code of the amount.
  
  Example: "EUR"
- timestampstring
  format: date-time
  The timestamp of when the transaction was created.
  
  Example: "2020-02-29T10:56:56.876Z"
- statusstring
  Options:"SUCCESSFUL""CANCELLED""FAILED""PENDING""REFUNDED"
  Current status of the transaction.
  
  PENDING: The transaction has been created but its final outcome is not known yet.
  
  SUCCESSFUL: The transaction completed successfully.
  
  CANCELLED: The transaction was cancelled or otherwise reversed before completion.
  
  FAILED: The transaction attempt did not complete successfully.
  
  REFUNDED: The transaction was refunded in full or in part.
  
  Example: "SUCCESSFUL"
- payment_typestring
  Options:"CASH""POS""ECOM""RECURRING""BITCOIN""BALANCE""MOTO""BOLETO""DIRECT_DEBIT""APM""UNKNOWN"
  Payment category recorded on a transaction, for example POS for a point-of-sale card payment, ECOM for an online card payment, or RECURRING for a recurring card payment. These reporting values are separate from the lowercase payment_type values used to process checkouts.
  
  Example: "ECOM"
- installments_countinteger
  minimum: 1
  Number of installments for a deferred payment.
  
  Example: 1
- product_summarystring
  Short description of the payment. The value is taken from the description property of the related checkout resource.
  
  Example: "Purchase"
- payouts_totalinteger
  Total number of payouts to the registered user specified in the user property.
  
  Example: 1
- payouts_receivedinteger
  Number of payouts that are made to the registered user specified in the user property.
  
  Example: 1
- payout_planstring
  Options:"SINGLE_PAYMENT""TRUE_INSTALLMENT""ACCELERATED_INSTALLMENT"
  Payout plan of the registered user at the time when the transaction was made.
  
  Example: "SINGLE_PAYMENT"
- transaction_idstring
  Unique identifier of the transaction.
  
  Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
- client_transaction_idstring
  Client-supplied identifier of the transaction.
  
  Example: "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2"
- userstring
  format: email
  Email address of the registered user (merchant) to whom the payment is made.
  
  Example: "merchant@example.com"
- typestring
  Options:"PAYMENT""REFUND""CHARGE_BACK"
  Type of the transaction for the registered user specified in the user property.
  
  Example: "PAYMENT"
- card_typestring
  Options:"ALELO""AMEX""BANCOMAT""CONECS""CUP""DINERS""DISCOVER""EFTPOS""ELO""ELV""GIROCARD""HIPERCARD""INTERAC""JCB""MAESTRO""MASTERCARD""PLUXEE""SUMUP""SWILE""TICKET""VISA""VISA_ELECTRON""VISA_VPAY""VPAY""VR""UNKNOWN"
  Issuing card network of the payment card used for the transaction.
  
  Example: "VISA"
- payout_datestring
  format: date
  Payout date (if paid out at once).
  
  Example: "2019-08-28"
- payout_typestring
  Options:"BANK_ACCOUNT""PREPAID_CARD"
  Payout type.
  
  Example: "BANK_ACCOUNT"
- refunded_amountnumber
  format: decimal
  Total amount refunded for this transaction, in major units of the transaction's currency.
  
  Example: 0
linksarray<object>
Pagination links for navigating the transaction history.

Example: []
Show 2 properties
- relstringrequired
  Pagination relation indicating which page the link retrieves, for example next.
  
  Example: "next"
- hrefstringrequired
  Query string to use with the transaction history endpoint when requesting the linked page. Preserve the returned pagination references and query parameters.
  
  Example: "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"

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"

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/v2.1/merchants/MH4H92C7/transactions/history \
  --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.transactions.list(
    "MH4H92C7",
    {
      "transaction_code": "TEENSK4W2K"
    }
  );
  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.Transactions.ListAsync(
            "your-merchant-code",
            new TransactionsListOptions
            {
                TransactionCode = "example",
                Order = "example",
                Limit = 10,
                Users = Array.Empty<string>(),
                Statuses = Array.Empty<string>(),
                PaymentTypes = Array.Empty<PaymentType>(),
                EntryModes = Array.Empty<EntryMode>(),
                Types = Array.Empty<string>(),
                ChangesSince = DateTimeOffset.Parse("2025-01-01T12:00:00Z"),
                NewestTime = DateTimeOffset.Parse("2025-01-01T12:00:00Z"),
                NewestRef = "example",
                OldestTime = DateTimeOffset.Parse("2025-01-01T12:00:00Z"),
                OldestRef = "example",
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.transactions().list(
            "MH4H92C7"
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.transactions.list(
    "MH4H92C7",
    transaction_code="TEENSK4W2K",
    order="ascending",
    limit=10,
    users=[
        "merchant@example.com",
    ],
    statuses=[
        "SUCCESSFUL",
        "REFUNDED",
    ],
    payment_types=[
        "ECOM",
        "POS",
    ],
    entry_modes=[
        "CUSTOMER_ENTRY",
        "CHIP",
    ],
    types=[
        "PAYMENT",
        "REFUND",
    ],
    changes_since="2019-08-28T09:00:00Z",
    newest_time="2019-08-29T09:00:00Z",
    newest_ref="090df9bf-93b7-40f1-8181-fbdb236568a1",
    oldest_time="2019-08-28T09:00:00Z",
    oldest_ref="090df9bf-93b7-40f1-8181-fbdb236568a1",
)
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\TransactionsListParams();
$queryParams->transactionCode = 'TEENSK4W2K';
$queryParams->order = 'ascending';
$queryParams->limit = 10;
$queryParams->usersList = [
    'merchant@example.com',
];
$queryParams->statusesList = [
    'SUCCESSFUL',
    'REFUNDED',
];
$queryParams->paymentTypesList = [
    'ECOM',
    'POS',
];
$queryParams->entryModesList = [
    'CUSTOMER_ENTRY',
    'CHIP',
];
$queryParams->typesList = [
    'PAYMENT',
    'REFUND',
];
$queryParams->changesSince = '2019-08-28T09:00:00Z';
$queryParams->newestTime = '2019-08-29T09:00:00Z';
$queryParams->newestRef = '090df9bf-93b7-40f1-8181-fbdb236568a1';
$queryParams->oldestTime = '2019-08-28T09:00:00Z';
$queryParams->oldestRef = '090df9bf-93b7-40f1-8181-fbdb236568a1';

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

var_dump($result);

package main

import (
	"context"
	"fmt"
	"time"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Transactions.List(context.TODO(), "MH4H92C7", sumup.TransactionsListParams{
		TransactionCode: new("TEENSK4W2K"),
		Order:           new(sumup.TransactionsListOrder("ascending")),
		Limit:           new(10),
		Users:           []string{"merchant@example.com"},
		Statuses:        []sumup.TransactionsListStatusesItem{"SUCCESSFUL", "REFUNDED"},
		PaymentTypes:    []sumup.PaymentType{"ECOM", "POS"},
		EntryModes:      []sumup.EntryMode{"CUSTOMER_ENTRY", "CHIP"},
		Types:           []sumup.TransactionsListTypesItem{"PAYMENT", "REFUND"},
		ChangesSince:    new(time.Date(2019, time.August, 28, 9, 0, 0, 0, time.UTC)),
		NewestTime:      new(time.Date(2019, time.August, 29, 9, 0, 0, 0, time.UTC)),
		NewestRef:       new("090df9bf-93b7-40f1-8181-fbdb236568a1"),
		OldestTime:      new(time.Date(2019, time.August, 28, 9, 0, 0, 0, time.UTC)),
		OldestRef:       new("090df9bf-93b7-40f1-8181-fbdb236568a1"),
	})
	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
        .transactions()
        .list(
            "MERCHANT_CODE",
            sumup::resources::transactions::ListParams::builder().build(),
        )
        .await
        .expect("list request failed");
    println!("{response:#?}");
}

Response example

{
  "items": [
    {
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "user": "merchant@example.com",
      "type": "PAYMENT",
      "payout_date": "2019-08-28",
      "payout_type": "BANK_ACCOUNT",
      "refunded_amount": 0
    }
  ],
  "links": []
}

{
  "message": "Validation error",
  "error_code": "INVALID"
}

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