Transactions | SumUp Developer

Transactions represent completed or attempted payment operations processed for a merchant account. A transaction contains the core payment result, such as the amount, currency, payment method, creation time, and current high-level status.

In addition to the main payment outcome, a transaction can contain related events that describe what happened after the original payment attempt. These events provide visibility into the financial lifecycle of the transaction, for example:

PAYOUT: the payment being prepared for payout or included in a payout to the merchant
REFUND: money returned to the payer
CHARGE_BACK: money reversed after the original payment
PAYOUT_DEDUCTION: an amount deducted from a payout to cover a refund or chargeback

From an integrator’s perspective, transactions are the authoritative record of payment outcomes. Use this tag to:

list transactions for reporting, reconciliation, and customer support workflows
retrieve a single transaction when you need the latest payment details
inspect simple_status for the current merchant-facing outcome of the payment
inspect events or transaction_events when you need refund, payout, or chargeback history

Typical workflow:

create and process payments through the Checkouts endpoints
use the Transactions endpoints to read the resulting payment records
use the returned statuses and events to update your own order, accounting, or support systems

Endpoints

Transactions

Retrieve a transaction

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

Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and one of following parameters is required:

id
transaction_code
foreign_transaction_id
client_transaction_id

Requires one of scopes:transactions.historytransactions.read

Path Parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MH4H92C7"

Query Parameters

idstring
Retrieves the transaction resource with the specified transaction ID (the id parameter in the transaction resource).

Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
transaction_codestring
Retrieves the transaction resource with the specified transaction code.

Example: "TEENSK4W2K"
foreign_transaction_idstring
External transaction identifier supplied by the client.

Example: "J13253253x1"
client_transaction_idstring
Client-supplied identifier of the transaction.

Example: "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2"

Response

Returns the requested transaction resource.

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
Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.

Example: 10.1
currencyCurrency
Options: BRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO 4217 currency code of the amount.

Example: "EUR"
timestampstringformat: date-time
The timestamp of when the transaction was created.

Example: "2020-02-29T10:56:56.876Z"
statusTransaction Status
Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
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_typePayment Type
Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
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_countintegerminimum: 1
Number of installments for a deferred payment.

Example: 1
merchant_codestring
Unique code of the registered merchant to whom the payment is made.

Example: "MH4H92C7"
vat_amountnumber
VAT included in the total transaction amount, in major units of the transaction's currency.

Example: 6
tip_amountnumber
Tip included in the total transaction amount, in major units of the transaction's currency.

Example: 3
entry_modeEntry Mode
Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
How the payment details were captured, for example CHIP or CONTACTLESS for card-present payments and CUSTOMER_ENTRY for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as APPLE_PAY or BLIK.

Example: "CUSTOMER_ENTRY"
auth_codestring
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

Example: "053201"
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_PAYMENTTRUE_INSTALLMENTACCELERATED_INSTALLMENT
Payout plan of the registered user at the time when the transaction was made.

Example: "SINGLE_PAYMENT"
foreign_transaction_idstring
External transaction identifier supplied by the client.

Example: "J13253253x1"
client_transaction_idstring
Client-supplied identifier of the transaction.

Example: "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2"
usernamestringformat: email
Email address of the registered user (merchant) to whom the payment is made.

Example: "merchant@example.com"
fee_amountnumber
Total SumUp transaction fee in major units of the transaction's currency.

Example: 8
latLatitudeminimum: -90, maximum: 90
Latitude value from the coordinates of the payment location (as received from the payment terminal reader).

Example: 52.520008
lonLongitudeminimum: -180, maximum: 180
Longitude value from the coordinates of the payment location (as received from the payment terminal reader).

Example: 13.404954
horizontal_accuracyHorizontal Accuracy
Indication of the precision of the geographical position received from the payment terminal.

Example: 5
merchant_idinteger
Internal SumUp identifier of the merchant.

Example: 136902
device_infoDevice
Details of the device used to create the transaction.
Show attributes
Close
Device
- namestring
  Device name.
  
  Example: "m0xx"
- system_namestring
  Device OS.
  
  Example: "Android"
- modelstring
  Device model.
  
  Example: "GT-I9300"
- system_versionstring
  Device OS version.
  
  Example: "4.3"
- uuidstring
  Device UUID.
  
  Example: "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
simple_payment_typestring
Options: CASHCC_SIGNATUREELVELV_WITHOUT_SIGNATURECC_CUSTOMER_ENTEREDMANUAL_ENTRYEMVRECURRINGBALANCEMOTOBOLETOAPMBITCOINCARD
Simple name of the payment type.

Example: "CARD"
verification_methodstring
Options: nonesignatureoffline PINonline PINoffline PIN + signaturena
Verification method used for the transaction.

Example: "none"
cardCard Response
Details of the payment card.
Show attributes
Close
Card Response
- last_4_digitsstringmin length: 4, max length: 4, Read only
  Last 4 digits of the payment card number.
  
  Example: "3456"
- typeCard Type
  Options: ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN
  Issuing card network of the payment card used for the transaction.
  
  Example: "VISA"
- payment_account_referencestring
  Payment Account Reference (PAR) defined by EMVCo. It links a card's primary account number (PAN) with its affiliated payment tokens, allowing transactions made with the physical card and tokenized versions of that card, such as digital wallets, to be correlated when PAR is available.
  
  This reference cannot be used to initiate a payment and is separate from the saved payment instrument token used to process checkouts. Returned only when available for the card; integrations must handle its absence.
  
  Example: "5665ABCDEFGHIJKLMNOPQRSTUVWXY"
elv_accountELV Card Account
Details of the ELV card account associated with the transaction.
Show attributes
Close
ELV Card Account
- sort_codestring
  ELV card sort code.
  
  Example: "87096214"
- last_4_digitsstring
  ELV card account number last 4 digits.
  
  Example: "5674"
- sequence_nointeger
  ELV card sequence number.
  
  Example: 1
- ibanstring
  ELV IBAN.
  
  Example: "DE60870962140012345674"
local_timestringformat: date-time
Local timestamp of when the transaction was created.

Example: "2020-02-29T11:56:56+01:00"
payout_datestringformat: date
The date of the payout.

Example: "2019-08-28"
payout_typestring
Options: BANK_ACCOUNTPREPAID_CARD
Payout type for the transaction.

Example: "BANK_ACCOUNT"
process_asstring
Options: CREDITDEBIT
Whether the transaction was processed as credit or debit.

Example: "CREDIT"
products[]Product
List of products from the merchant's catalogue for which the transaction serves as a payment.
Show attributes
Close
Product
- namestring
  Product name.
  
  Example: "Purchase reader for merchant with code ME3FCAVF"
- price_labelstring
  Human-readable label for the product price.
  
  Example: "EUR 100.00"
- pricenumber
  Product price.
  
  Example: 100
- vat_ratenumber
  VAT rate as a decimal fraction, for example 0.19 for 19%.
  
  Example: 0.19
- single_vat_amountnumber
  VAT amount for a single product.
  
  Example: 19
- price_with_vatnumber
  Product price including VAT.
  
  Example: 119
- vat_amountnumber
  Total VAT amount for the product quantity.
  
  Example: 19
- quantityinteger
  Product quantity.
  
  Example: 1
- total_pricenumber
  Total price calculated as the product price multiplied by the quantity.
  
  Example: 100
- total_with_vatnumber
  Total product price including VAT.
  
  Example: 119
vat_rates[]object
List of VAT rates applicable to the transaction.
Show attributes
Close
Attributes
- ratenumber
  VAT rate.
  
  Example: 0.045
- netnumber
  NET amount of products having this VAT rate applied.
  
  Example: 1.36
- vatnumber
  VAT amount of this rate applied.
  
  Example: 0.06
- grossnumber
  Gross amount of products having this VAT rate applied.
  
  Example: 1.42
transaction_events[]TransactionEvent
Detailed list of events related to the transaction.
Show attributes
Close
Transaction Event
- idTransaction Event ID
  Numeric identifier of a transaction event. Use it as tx_event_id when requesting receipt details for a specific event. This is separate from the transaction ID and the transaction history pagination references.
  
  Example: 9567461191
- event_typeTransaction Event Type
  Options: PAYOUTCHARGE_BACKREFUNDPAYOUT_DEDUCTION
  Financial event associated with a transaction.
  
  PAYOUT: Funds from the transaction being prepared for or included in a merchant payout. Check the event status to determine whether they have been paid out.
  
  REFUND: Money returned to the payer.
  
  CHARGE_BACK: A reversal of the payment following a chargeback.
  
  PAYOUT_DEDUCTION: An amount deducted from a merchant payout, for example to cover a refund or chargeback.
  
  Example: "REFUND"
- statusTransaction Event Status
  Options: FAILEDPAID_OUTPENDINGRECONCILEDREFUNDEDSCHEDULEDSUCCESSFUL
  Status of the transaction event.
  
  Not every value is used for every event type.
  
  PENDING: The event has been created but is not final yet. Used for events that are still being processed and whose final outcome is not known yet.
  
  SCHEDULED: The event is planned for a future payout cycle but has not been executed yet. This applies to payout events before money is actually sent out.
  
  RECONCILED: The underlying payment has been matched with settlement data and is ready to continue through payout processing, but the funds have not been paid out yet. This applies to payout events.
  
  PAID_OUT: The payout event has been completed and the funds were included in a merchant payout.
  
  REFUNDED: A refund event has been accepted and recorded in the refund flow. This is the status returned for refund events once the transaction amount is being or has been returned to the payer.
  
  SUCCESSFUL: The event completed successfully. Use this as the generic terminal success status for event types that do not expose a more specific business outcome such as PAID_OUT or REFUNDED.
  
  FAILED: The event could not be completed. Typical examples are a payout that could not be executed or an event that was rejected during processing.
  
  Example: "SUCCESSFUL"
- amountnumber
  Amount of the event in major units of the associated transaction's currency.
  
  Example: 58.8
- due_datestringformat: date
  Date when the transaction event is due to occur.
  
  Example: "2020-05-25"
- datestringformat: date
  Date when the transaction event occurred.
  
  Example: "2020-05-25"
- installment_numberinteger
  Consecutive number of the installment that is paid. Applicable only to payout events, i.e. event_type = PAYOUT.
  
  Example: 1
- timestampstringformat: date-time
  Date and time of the transaction event.
  
  Example: "2020-05-25T10:49:42.784Z"
simple_statusstring
Options: SUCCESSFULPAID_OUTCANCEL_FAILEDCANCELLEDCHARGEBACKFAILEDREFUND_FAILEDREFUNDEDNON_COLLECTIONPENDING
High-level status of the transaction from the merchant's perspective.
- PENDING: The payment has been initiated and is still being processed. A final outcome is not available yet.
- SUCCESSFUL: The payment was completed successfully.
- PAID_OUT: The payment was completed successfully and the funds have already been included in a payout to the merchant.
- FAILED: The payment did not complete successfully.
- CANCELLED: The payment was cancelled or reversed and is no longer payable or payable to the merchant.
- CANCEL_FAILED: An attempt to cancel or reverse the payment was not completed successfully.
- REFUNDED: The payment was refunded in full or in part.
- REFUND_FAILED: An attempt to refund the payment was not completed successfully.
- CHARGEBACK: The payment was subject to a chargeback.
- NON_COLLECTION: The amount could not be collected from the merchant after a chargeback or related adjustment.
Example: "SUCCESSFUL"
links[]Link
List of hyperlinks for accessing related resources.
Show attributes
Close
Link
- relstring
  Relation of the linked resource to the current resource.
  
  Example: "refund"
- hrefstringformat: uri
  URL for accessing the related resource.
  
  Example: "https://api.sumup.com/v1.0/merchants/MH4H92C7/payments/4ffb8dfc-7f2b-413d-a497-2ad00766585e/refunds"
- typestring
  Media type of the linked resource.
  
  Example: "application/json"
- min_amountnumber
  Minimum amount allowed for a refund, in major units.
  
  Example: 0.01
- max_amountnumber
  Maximum amount allowed for a refund, in major units.
  
  Example: 10.1
events[]Event
Compact list of events related to the transaction.
Show attributes
Close
Event
- idTransaction Event ID
  Numeric identifier of a transaction event. Use it as tx_event_id when requesting receipt details for a specific event. This is separate from the transaction ID and the transaction history pagination references.
  
  Example: 9567461191
- transaction_idTransaction ID
  Unique identifier of the transaction.
  
  Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
- typeTransaction Event Type
  Options: PAYOUTCHARGE_BACKREFUNDPAYOUT_DEDUCTION
  Financial event associated with a transaction.
  
  PAYOUT: Funds from the transaction being prepared for or included in a merchant payout. Check the event status to determine whether they have been paid out.
  
  REFUND: Money returned to the payer.
  
  CHARGE_BACK: A reversal of the payment following a chargeback.
  
  PAYOUT_DEDUCTION: An amount deducted from a merchant payout, for example to cover a refund or chargeback.
  
  Example: "REFUND"
- statusTransaction Event Status
  Options: FAILEDPAID_OUTPENDINGRECONCILEDREFUNDEDSCHEDULEDSUCCESSFUL
  Status of the transaction event.
  
  Not every value is used for every event type.
  
  PENDING: The event has been created but is not final yet. Used for events that are still being processed and whose final outcome is not known yet.
  
  SCHEDULED: The event is planned for a future payout cycle but has not been executed yet. This applies to payout events before money is actually sent out.
  
  RECONCILED: The underlying payment has been matched with settlement data and is ready to continue through payout processing, but the funds have not been paid out yet. This applies to payout events.
  
  PAID_OUT: The payout event has been completed and the funds were included in a merchant payout.
  
  REFUNDED: A refund event has been accepted and recorded in the refund flow. This is the status returned for refund events once the transaction amount is being or has been returned to the payer.
  
  SUCCESSFUL: The event completed successfully. Use this as the generic terminal success status for event types that do not expose a more specific business outcome such as PAID_OUT or REFUNDED.
  
  FAILED: The event could not be completed. Typical examples are a payout that could not be executed or an event that was rejected during processing.
  
  Example: "SUCCESSFUL"
- amountnumber
  Amount associated with the transaction event, in major units.
  
  Example: 10.1
- timestampstringformat: date-time
  The timestamp of when the transaction event occurred.
  
  Example: "2020-05-25T10:49:42.784Z"
- fee_amountnumber
  Fee associated with the transaction event, in major units.
  
  Example: 0.25
- installment_numberinteger
  Consecutive number of the installment associated with the event.
  
  Example: 1
- deducted_amountnumber
  Amount deducted from the merchant for the event, in major units.
  
  Example: 10.1
- deducted_fee_amountnumber
  Fee deducted from the merchant for the event, in major units.
  
  Example: 0.25
locationobject
Details of the payment location as received from the payment terminal.
Show attributes
Close
Attributes
- latLatitudeminimum: -90, maximum: 90
  Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
  
  Example: 52.520008
- lonLongitudeminimum: -180, maximum: 180
  Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
  
  Example: 13.404954
- horizontal_accuracyHorizontal Accuracy
  Indication of the precision of the geographical position received from the payment terminal.
  
  Example: 5
tax_enabledboolean
Indicates whether tax deduction is enabled for the transaction.

Example: true

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

1
sumup transactions get "410fc44a-5956-44e1-b5cc-19c6f8d727a4" \
2
  --merchant-code "MH4H92C7"

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

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

6
  const result = await client.transactions.get(
7
    "MH4H92C7",
8
    {
9
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
10
    }
11
  );
12
  console.log(result);
13
}
14

15
main().catch(console.error);

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

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Transactions.GetAsync(
12
            "your-merchant-code",
13
            new TransactionsGetOptions
14
            {
15
                Id = "example-id",
16
                TransactionCode = "example",
17
                ForeignTransactionId = "example-id",
18
                ClientTransactionId = "example-id",
19
            });
20

21
        Console.WriteLine(response.StatusCode);
22
    }
23
}

1
import com.sumup.sdk.SumUpClient;
2

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

7
    var result = client.transactions().get(
8
            "MH4H92C7"
9
        );
10
    System.out.println(result);
11
  }
12
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.transactions.get(
7
    "MH4H92C7",
8
    id="410fc44a-5956-44e1-b5cc-19c6f8d727a4",
9
    transaction_code="TEENSK4W2K",
10
    foreign_transaction_id="J13253253x1",
11
    client_transaction_id="urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
12
)
13
print(result)

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

3
$result = $sumup->transactions->get('MH4H92C7');

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Transactions.Get(context.TODO(), "MH4H92C7", sumup.TransactionsGetParams{
13
    ID:                   new("410fc44a-5956-44e1-b5cc-19c6f8d727a4"),
14
    TransactionCode:      new("TEENSK4W2K"),
15
    ForeignTransactionID: new("J13253253x1"),
16
    ClientTransactionID:  new("urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2"),
17
  })
18
  if err != nil {
19
    panic(err.Error())
20
  }
21

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

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let response = client
7
        .transactions()
8
        .get("MERCHANT_CODE", Default::default())
9
        .await
10
        .expect("get request failed");
11
    println!("{response:#?}");
12
}

1
{
2
  "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
3
  "transaction_code": "TEENSK4W2K",
4
  "amount": 10.1,
5
  "currency": "EUR",
6
  "timestamp": "2020-02-29T10:56:56.876Z",
7
  "status": "SUCCESSFUL",
8
  "payment_type": "ECOM",
9
  "installments_count": 1,
10
  "merchant_code": "MH4H92C7",
11
  "vat_amount": 6,
12
  "tip_amount": 3,
13
  "entry_mode": "CUSTOMER_ENTRY",
14
  "auth_code": "053201"
15
}

Error 401
Error 404

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"

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

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

Example: "NOT_FOUND"

Error 401
Error 404

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

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

Transactions

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.

Requires one of scopes:transactions.historytransactions.read

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"
orderstringdefault: ascending
Options: ascendingdescending
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[][]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[][]string
Options: SUCCESSFULCANCELLEDFAILEDREFUNDEDCHARGE_BACK
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[][]PaymentType
Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
Filters the returned results by the specified list of payment types used for the transactions.

Example: ["ECOM","POS"]
entry_modes[][]EntryMode
Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
Filters the returned results by the specified list of entry modes.

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

Example: ["PAYMENT","REFUND"]
changes_sincestringformat: 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_timestringformat: 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_timestringformat: 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"

Response

Returns a page of transaction history items.

items[]TransactionHistory
Transactions in the current result page.
Show attributes
Close
Transaction History
- 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
  Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.
  
  Example: 10.1
- currencyCurrency
  Options: BRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO 4217 currency code of the amount.
  
  Example: "EUR"
- timestampstringformat: date-time
  The timestamp of when the transaction was created.
  
  Example: "2020-02-29T10:56:56.876Z"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  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_countintegerminimum: 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_PAYMENTTRUE_INSTALLMENTACCELERATED_INSTALLMENT
  Payout plan of the registered user at the time when the transaction was made.
  
  Example: "SINGLE_PAYMENT"
- transaction_idTransaction ID
  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"
- userstringformat: email
  Email address of the registered user (merchant) to whom the payment is made.
  
  Example: "merchant@example.com"
- typestring
  Options: PAYMENTREFUNDCHARGE_BACK
  Type of the transaction for the registered user specified in the user property.
  
  Example: "PAYMENT"
- card_typeCard Type
  Options: ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN
  Issuing card network of the payment card used for the transaction.
  
  Example: "VISA"
- payout_datestringformat: date
  Payout date (if paid out at once).
  
  Example: "2019-08-28"
- payout_typestring
  Options: BANK_ACCOUNTPREPAID_CARD
  Payout type.
  
  Example: "BANK_ACCOUNT"
- refunded_amountnumber
  Total amount refunded for this transaction, in major units of the transaction's currency.
  
  0
links[]TransactionsHistoryLink
Pagination links for navigating the transaction history.
Show attributes
Close
Transactions History Link
- 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"

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

1
sumup transactions list \
2
  --merchant-code "MH4H92C7"

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

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

6
  const result = await client.transactions.list(
7
    "MH4H92C7",
8
    {
9
      "transaction_code": "TEENSK4W2K"
10
    }
11
  );
12
  console.log(result);
13
}
14

15
main().catch(console.error);

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

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Transactions.ListAsync(
12
            "your-merchant-code",
13
            new TransactionsListOptions
14
            {
15
                TransactionCode = "example",
16
                Order = "example",
17
                Limit = 10,
18
                Users = Array.Empty<string>(),
19
                Statuses = Array.Empty<string>(),
20
                PaymentTypes = Array.Empty<PaymentType>(),
21
                EntryModes = Array.Empty<EntryMode>(),
22
                Types = Array.Empty<string>(),
23
                ChangesSince = DateTimeOffset.Parse("2025-01-01T12:00:00Z"),
24
                NewestTime = DateTimeOffset.Parse("2025-01-01T12:00:00Z"),
25
                NewestRef = "example",
26
                OldestTime = DateTimeOffset.Parse("2025-01-01T12:00:00Z"),
27
                OldestRef = "example",
28
            });
29

30
        Console.WriteLine(response.StatusCode);
31
    }
32
}

1
import com.sumup.sdk.SumUpClient;
2

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

7
    var result = client.transactions().list(
8
            "MH4H92C7"
9
        );
10
    System.out.println(result);
11
  }
12
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.transactions.list(
7
    "MH4H92C7",
8
    transaction_code="TEENSK4W2K",
9
    order="ascending",
10
    limit=10,
11
    users=[
12
        "merchant@example.com",
13
    ],
14
    statuses=[
15
        "SUCCESSFUL",
16
        "REFUNDED",
17
    ],
18
    payment_types=[
19
        "ECOM",
20
        "POS",
21
    ],
22
    entry_modes=[
23
        "CUSTOMER_ENTRY",
24
        "CHIP",
25
    ],
26
    types=[
27
        "PAYMENT",
28
        "REFUND",
29
    ],
30
    changes_since="2019-08-28T09:00:00Z",
31
    newest_time="2019-08-29T09:00:00Z",
32
    newest_ref="090df9bf-93b7-40f1-8181-fbdb236568a1",
33
    oldest_time="2019-08-28T09:00:00Z",
34
    oldest_ref="090df9bf-93b7-40f1-8181-fbdb236568a1",
35
)
36
print(result)

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

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

1
package main
2

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

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

11
func main() {
12
  client := sumup.NewClient()
13
  result, err := client.Transactions.List(context.TODO(), "MH4H92C7", sumup.TransactionsListParams{
14
    TransactionCode: new("TEENSK4W2K"),
15
    Order:           new(sumup.TransactionsListOrder("ascending")),
16
    Limit:           new(10),
17
    Users:           []string{"merchant@example.com"},
18
    Statuses:        []sumup.TransactionsListStatusesItem{"SUCCESSFUL", "REFUNDED"},
19
    PaymentTypes:    []sumup.PaymentType{"ECOM", "POS"},
20
    EntryModes:      []sumup.EntryMode{"CUSTOMER_ENTRY", "CHIP"},
21
    Types:           []sumup.TransactionsListTypesItem{"PAYMENT", "REFUND"},
22
    ChangesSince:    new(time.Date(2019, time.August, 28, 9, 0, 0, 0, time.UTC)),
23
    NewestTime:      new(time.Date(2019, time.August, 29, 9, 0, 0, 0, time.UTC)),
24
    NewestRef:       new("090df9bf-93b7-40f1-8181-fbdb236568a1"),
25
    OldestTime:      new(time.Date(2019, time.August, 28, 9, 0, 0, 0, time.UTC)),
26
    OldestRef:       new("090df9bf-93b7-40f1-8181-fbdb236568a1"),
27
  })
28
  if err != nil {
29
    panic(err.Error())
30
  }
31

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

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let response = client
7
        .transactions()
8
        .list("MERCHANT_CODE", Default::default())
9
        .await
10
        .expect("list request failed");
11
    println!("{response:#?}");
12
}

1
{
2
  "items": [
3
    {
4
      "transaction_code": "TEENSK4W2K",
5
      "amount": 10.1,
6
      "currency": "EUR",
7
      "timestamp": "2020-02-29T10:56:56.876Z",
8
      "status": "SUCCESSFUL",
9
      "payment_type": "ECOM",
10
      "installments_count": 1,
11
      "merchant_code": "MH4H92C7",
12
      "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
13
      "user": "merchant@example.com",
14
      "type": "PAYMENT",
15
      "payout_date": "2019-08-28",
16
      "payout_type": "BANK_ACCOUNT",
17
      "refunded_amount": 0
18
    }
19
  ],
20
  "links": []
21
}

Error 400
Error 401

Content-Type: application/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"

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
  "message": "Validation error",
3
  "error_code": "INVALID"
4
}

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

Transactions

Refund a transaction

POST/v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds

Refunds a transaction identified by its SumUp transaction ID. Omit the request body to request a full refund, or provide amount for a partial refund in the transaction’s currency.

Retrieve the transaction afterwards to inspect its refunded amount and refund events. The transaction must be eligible for a refund; see the error responses for invalid amounts, permissions, and processing failures.

Requires one of scopes:paymentsrefunds.write

Path Parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MH4H92C7"
transaction_idstringrequired
Unique identifier of the transaction.

Example: "4ffb8dfc-7f2b-413d-a497-2ad00766585e"

Body Parameters

amountnumber
Amount to refund in major units of the transaction's currency, for example 5 for EUR 5.00. It must be greater than zero and cannot exceed the amount eligible for a refund. Eligibility depends on the transaction and country/currency rules. If omitted, the system requests a full refund.

Example: 5

Response

The transaction was refunded in full or partially based on the request.

1
curl https://api.sumup.com/v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds \
2
 -X POST \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "amount": 5
6
  }'

1
sumup transactions refund "4ffb8dfc-7f2b-413d-a497-2ad00766585e" \
2
  --merchant-code "MH4H92C7" \
3
  --amount "5"

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

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

6
  const result = await client.transactions.refund(
7
    "MH4H92C7",
8
    "4ffb8dfc-7f2b-413d-a497-2ad00766585e",
9
    {
10
      "amount": 5
11
    }
12
  );
13
  console.log(result);
14
}
15

16
main().catch(console.error);

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

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Transactions.RefundAsync(
12
            "your-merchant-code",
13
            "example-id",
14
            new TransactionsRefundRequest
15
            {
16
                Amount = 5f,
17
            });
18

19
        Console.WriteLine(response.StatusCode);
20
    }
21
}

1
import com.sumup.sdk.SumUpClient;
2

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

7
    var result = client.transactions().refund(
8
            "MH4H92C7",
9
            "4ffb8dfc-7f2b-413d-a497-2ad00766585e",
10
            com.sumup.sdk.models.RefundTransactionRequest.builder()
11
                .amount(5.0f)
12
                .build()
13
        );
14
    System.out.println(result);
15
  }
16
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.transactions.refund(
7
    "MH4H92C7",
8
    "4ffb8dfc-7f2b-413d-a497-2ad00766585e",
9
    amount=5,
10
)
11
print(result)

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

3
$result = $sumup->transactions->refund('MH4H92C7', '4ffb8dfc-7f2b-413d-a497-2ad00766585e', [
4
  'amount' => 5,
5
]);

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Transactions.Refund(context.TODO(), "MH4H92C7", "4ffb8dfc-7f2b-413d-a497-2ad00766585e", sumup.TransactionsRefundParams{
13
    Amount: new(float32(5)),
14
  })
15
  if err != nil {
16
    panic(err.Error())
17
  }
18

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

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let body = sumup::resources::transactions::RefundRequest {
7
        amount: Some(5f32),
8
    };
9
    let response = client
10
        .transactions()
11
        .refund("MERCHANT_CODE", "TRANSACTION_ID", Some(body))
12
        .await
13
        .expect("refund request failed");
14
    println!("{response:#?}");
15
}

1
{}