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

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

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"

Responses

200application/json

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
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
merchant_codestring
Unique code of the registered merchant to whom the payment is made.

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

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

Example: 3
entry_modestring
Options:"BOLETO""SOFORT""IDEAL""BANCONTACT""EPS""MYBANK""SATISPAY""BLIK""P24""GIROPAY""PIX""QR_CODE_PIX""APPLE_PAY""GOOGLE_PAY""PAYPAL""TWINT""NONE""CHIP""MANUAL_ENTRY""CUSTOMER_ENTRY""MAGSTRIPE_FALLBACK""MAGSTRIPE""DIRECT_DEBIT""CONTACTLESS""MOTO""CONTACTLESS_MAGSTRIPE""N/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_PAYMENT""TRUE_INSTALLMENT""ACCELERATED_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"
usernamestring
format: email
Email address of the registered user (merchant) to whom the payment is made.

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

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

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

Example: 13.404954
horizontal_accuracynumber
format: float
Indication of the precision of the geographical position received from the payment terminal.

Example: 5
merchant_idinteger
format: int64
Internal SumUp identifier of the merchant.

Example: 136902
device_infoobject
Details of the device used to create the transaction.
Show 5 properties
- 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:"CASH""CC_SIGNATURE""ELV""ELV_WITHOUT_SIGNATURE""CC_CUSTOMER_ENTERED""MANUAL_ENTRY""EMV""RECURRING""BALANCE""MOTO""BOLETO""APM""BITCOIN""CARD"
Simple name of the payment type.

Example: "CARD"
verification_methodstring
Options:"none""signature""offline PIN""online PIN""offline PIN + signature""na"
Verification method used for the transaction.

Example: "none"
cardobject
Details of the payment card.
Show 3 properties
- last_4_digitsstring
  minLength: 4maxLength: 4
  Last 4 digits of the payment card number.
  
  Example: "3456"
- 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"
- 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_accountobject
Details of the ELV card account associated with the transaction.
Show 4 properties
- 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_timestring
format: date-time
Local timestamp of when the transaction was created.

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

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

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

Example: "CREDIT"
productsarray<object>
List of products from the merchant's catalogue for which the transaction serves as a payment.
Show 10 properties
- 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
  format: decimal
  Product price.
  
  Example: 100
- vat_ratenumber
  format: decimal
  VAT rate as a decimal fraction, for example 0.19 for 19%.
  
  Example: 0.19
- single_vat_amountnumber
  format: decimal
  VAT amount for a single product.
  
  Example: 19
- price_with_vatnumber
  format: decimal
  Product price including VAT.
  
  Example: 119
- vat_amountnumber
  format: decimal
  Total VAT amount for the product quantity.
  
  Example: 19
- quantityinteger
  Product quantity.
  
  Example: 1
- total_pricenumber
  format: decimal
  Total price calculated as the product price multiplied by the quantity.
  
  Example: 100
- total_with_vatnumber
  format: decimal
  Total product price including VAT.
  
  Example: 119
vat_ratesarray<object>
List of VAT rates applicable to the transaction.
Show 4 properties
- ratenumber
  format: decimal
  VAT rate.
  
  Example: 0.045
- netnumber
  format: decimal
  NET amount of products having this VAT rate applied.
  
  Example: 1.36
- vatnumber
  format: decimal
  VAT amount of this rate applied.
  
  Example: 0.06
- grossnumber
  format: decimal
  Gross amount of products having this VAT rate applied.
  
  Example: 1.42
transaction_eventsarray<object>
Detailed list of events related to the transaction.
Show 8 properties
- idinteger
  format: int64
  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_typestring
  Options:"PAYOUT""CHARGE_BACK""REFUND""PAYOUT_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"
- statusstring
  Options:"FAILED""PAID_OUT""PENDING""RECONCILED""REFUNDED""SCHEDULED""SUCCESSFUL"
  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
  format: decimal
  Amount of the event in major units of the associated transaction's currency.
  
  Example: 58.8
- due_datestring
  format: date
  Date when the transaction event is due to occur.
  
  Example: "2020-05-25"
- datestring
  format: 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
- timestampstring
  format: date-time
  Date and time of the transaction event.
  
  Example: "2020-05-25T10:49:42.784Z"
simple_statusstring
Options:"SUCCESSFUL""PAID_OUT""CANCEL_FAILED""CANCELLED""CHARGEBACK""FAILED""REFUND_FAILED""REFUNDED""NON_COLLECTION""PENDING"
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"
linksarray<object>
List of hyperlinks for accessing related resources.
Show 5 properties
- relstring
  Relation of the linked resource to the current resource.
  
  Example: "refund"
- hrefstring
  format: 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
  format: float
  Minimum amount allowed for a refund, in major units.
  
  Example: 0.01
- max_amountnumber
  format: float
  Maximum amount allowed for a refund, in major units.
  
  Example: 10.1
eventsarray<object>
Compact list of events related to the transaction.
Show 10 properties
- idinteger
  format: int64
  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_idstring
  Unique identifier of the transaction.
  
  Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
- typestring
  Options:"PAYOUT""CHARGE_BACK""REFUND""PAYOUT_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"
- statusstring
  Options:"FAILED""PAID_OUT""PENDING""RECONCILED""REFUNDED""SCHEDULED""SUCCESSFUL"
  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
  format: float
  Amount associated with the transaction event, in major units.
  
  Example: 10.1
- timestampstring
  format: date-time
  The timestamp of when the transaction event occurred.
  
  Example: "2020-05-25T10:49:42.784Z"
- fee_amountnumber
  format: float
  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
  format: float
  Amount deducted from the merchant for the event, in major units.
  
  Example: 10.1
- deducted_fee_amountnumber
  format: float
  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 3 properties
- latnumber
  format: floatminimum: -90maximum: 90
  Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
  
  Example: 52.520008
- lonnumber
  format: floatminimum: -180maximum: 180
  Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
  
  Example: 13.404954
- horizontal_accuracynumber
  format: float
  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

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"

404application/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"

GET

Code sample

curl --request GET \
  --url https://api.sumup.com/v2.1/merchants/MH4H92C7/transactions \
  --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.get(
    "MH4H92C7",
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
    }
  );
  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.GetAsync(
            "your-merchant-code",
            new TransactionsGetOptions
            {
                Id = "example-id",
                TransactionCode = "example",
                ForeignTransactionId = "example-id",
                ClientTransactionId = "example-id",
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

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

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.transactions.get(
    "MH4H92C7",
    id="410fc44a-5956-44e1-b5cc-19c6f8d727a4",
    transaction_code="TEENSK4W2K",
    foreign_transaction_id="J13253253x1",
    client_transaction_id="urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
)
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\TransactionsGetParams();
$queryParams->id = '410fc44a-5956-44e1-b5cc-19c6f8d727a4';
$queryParams->transactionCode = 'TEENSK4W2K';
$queryParams->foreignTransactionId = 'J13253253x1';
$queryParams->clientTransactionId = 'urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2';

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

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Transactions.Get(context.TODO(), "MH4H92C7", sumup.TransactionsGetParams{
		ID:                   new("410fc44a-5956-44e1-b5cc-19c6f8d727a4"),
		TransactionCode:      new("TEENSK4W2K"),
		ForeignTransactionID: new("J13253253x1"),
		ClientTransactionID:  new("urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2"),
	})
	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()
        .get(
            "MERCHANT_CODE",
            sumup::resources::transactions::GetParams::builder().build(),
        )
        .await
        .expect("get request failed");
    println!("{response:#?}");
}

Response example

{
  "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "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",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": "CUSTOMER_ENTRY",
  "auth_code": "053201"
}

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

{
  "error_code": "NOT_FOUND",
  "message": "Resource not found"
}