Skip to content
SumUp Developer

Transactions

SumUp API reference and code samples.

Retrieve details for a specific transaction by it’s id or any other required query parameter, or list all transactions related to the merchant account.

Transactions

Refund a transaction

POST /v0.1/me/refund/{txn_id}

Refunds an identified transaction either in full or partially.

Required scopes: payments

Path Parameters

  • txn_id string required

    Unique ID of the transaction.

Body Parameters

  • amount number

    Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.

Response

Returns empty response.

POST /v0.1/me/refund/{txn_id} 
curl https://api.sumup.com/v0.1/me/refund/{txn_id} \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.refund("txn_id", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.RefundAsync(
    "txn_id",
    new RefundTransactionBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


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


var result = client.transactions().refundTransaction(
  "txn_id",
  RefundTransactionBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.transactions.refund("txn_id", RefundTransactionBody(


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


$result = $sumup->transactions->refund('txn_id', [


]);
client := sumup.NewClient()


result, err := client.Transactions.Refund(context.Background(), "txn_id", sumup.TransactionsRefundParams{


})
use sumup::Client;


let client = Client::default();


let result = client.transactions().refund("txn_id", sumup::RefundTransactionBody{}).await;

Content-Type: application/json

The requested resource does not exist.

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.
Error 404
{
  "error_code": "NOT_FOUND",
  "message": "Resource not found"
}
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
  • internal_id
  • transaction_code
  • foreign_transaction_id
  • client_transaction_id
Required scopes: transactions.history

Path Parameters

  • merchant_code string required
    Example: "MH4H92C7"

Query Parameters

  • id string

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

  • internal_id string

    Retrieves the transaction resource with the specified internal transaction ID (the internal_id parameter in the transaction resource).

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

  • foreign_transaction_id string

    External/foreign transaction id (passed by clients).

  • client_transaction_id string

    Client transaction id.

Response

Returns the requested transaction resource.

  • id string

    Unique ID of the transaction.

    Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
  • transaction_code string

    Transaction code returned by the acquirer/processing entity after processing the transaction.

    Example: "TEENSK4W2K"
  • amount number

    Total amount of the transaction.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • timestamp string format: date-time

    Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56.876Z"
  • status string
    Options:  SUCCESSFULCANCELLEDFAILEDPENDING

    Current status of the transaction.

  • payment_type Payment Type
    Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

    Payment type used for the transaction.

  • installments_count integer minimum: 1

    Current number of the installment for deferred payments.

  • merchant_code string

    Unique code of the registered merchant to whom the payment is made.

    Example: "MH4H92C7"
  • vat_amount number

    Amount of the applicable VAT (out of the total transaction amount).

    Example: 6
  • tip_amount number

    Amount of the tip (out of the total transaction amount).

    Example: 3
  • entry_mode Entry Mode
    Options:  nonemagstripechipmanual entrycustomer entrymagstripe fallbackcontactlessmotocontactless magstripeboletodirect debitsofortidealbancontactepsmybanksatispayblikp24giropaypixqr code pixapple paygoogle paypaypalna

    Entry mode of the payment details.

  • auth_code string

    Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

    Example: "053201"
  • internal_id integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • product_summary string

    Short description of the payment. The value is taken from the description property of the related checkout resource.

  • payouts_total integer

    Total number of payouts to the registered user specified in the user property.

  • payouts_received integer

    Number of payouts that are made to the registered user specified in the user property.

  • payout_plan string
    Options:  SINGLE_PAYMENTTRUE_INSTALLMENTACCELERATED_INSTALLMENT

    Payout plan of the registered user at the time when the transaction was made.

  • foreign_transaction_id string

    External/foreign transaction id (passed by clients).

    Example: "J13253253x1"
  • client_transaction_id string

    Client transaction id.

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

    Email address of the registered user (merchant) to whom the payment is made.

  • fee_amount number

    Transaction SumUp total fee amount.

    Example: 8
  • lat Latitude minimum: 0, maximum: 90

    Latitude value from the coordinates of the payment location (as received from the payment terminal reader).

  • lon Longitude minimum: 0, maximum: 180

    Longitude value from the coordinates of the payment location (as received from the payment terminal reader).

  • horizontal_accuracy Horizontal Accuracy

    Indication of the precision of the geographical position received from the payment terminal.

  • merchant_id integer

    SumUp merchant internal Id.

    Example: 136902
  • device_info Device

    Details of the device used to create the transaction.

     Show attributes
     Close
    Device
    • name string

      Device name.

      Example: "m0xx"
    • system_name string

      Device OS.

      Example: "Android"
    • model string

      Device model.

      Example: "GT-I9300"
    • system_version string

      Device OS version.

      Example: "4.3"
    • uuid string

      Device UUID.

      Example: "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
  • simple_payment_type string
    Options:  CASHCC_SIGNATUREELVELV_WITHOUT_SIGNATURECC_CUSTOMER_ENTEREDMANUAL_ENTRYEMVRECURRINGBALANCEMOTOBOLETOAPMBITCOINCARD

    Simple name of the payment type.

  • verification_method string
    Options:  nonesignatureoffline PINonline PINoffline PIN + signaturena

    Verification method used for the transaction.

  • card Card Response

    Details of the payment card.

     Show attributes
     Close
    Card Response
    • last_4_digits string min length: 4, max length: 4, Read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type Card Type
      Options:  ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN

      Issuing card network of the payment card used for the transaction.

  • elv_account ELV Card Account

    Details of the ELV card account associated with the transaction.

     Show attributes
     Close
    ELV Card Account
    • sort_code string

      ELV card sort code.

      Example: "87096214"
    • last_4_digits string

      ELV card account number last 4 digits.

      Example: "5674"
    • sequence_no integer

      ELV card sequence number.

      Example: 1
    • iban string

      ELV IBAN.

      Example: "DE60870962140012345674"
  • local_time string format: date-time

    Local date and time of the creation of the transaction.

  • payout_date string format: date

    The date of the payout.

    Example: "2019-08-28"
  • payout_type string
    Options:  BANK_ACCOUNTPREPAID_CARD

    Payout type for the transaction.

  • process_as string
    Options:  CREDITDEBIT

    Debit/Credit.

    Example: "CREDIT"
  • products []Product

    List of products from the merchant's catalogue for which the transaction serves as a payment.

     Show attributes
     Close
    Product
    • name string

      Product name.

      Example: "Purchase reader for merchant with code ME3FCAVF"
    • price_label string

      Product description.

    • price number

      Product price.

      Example: 100
    • vat_rate number

      VAT percentage.

    • single_vat_amount number

      VAT amount for a single product.

    • price_with_vat number

      Product price incl. VAT.

    • vat_amount number

      VAT amount.

    • quantity integer

      Product quantity.

      Example: 1
    • total_price number

      Quantity x product price.

      Example: 100
    • total_with_vat number

      Total price incl. VAT.

  • vat_rates []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
    • rate number

      VAT rate.

      Example: 0.045
    • net number

      NET amount of products having this VAT rate applied.

      Example: 1.36
    • vat number

      VAT amount of this rate applied.

      Example: 0.06
    • gross number

      Gross amount of products having this VAT rate applied.

      Example: 1.42
  • transaction_events []TransactionEvent

    List of transaction events related to the transaction.

     Show attributes
     Close
    Transaction Event
    • id Event ID

      Unique ID of the transaction event.

    • event_type Event Type
      Options:  PAYOUTCHARGE_BACKREFUNDPAYOUT_DEDUCTION

      Type of the transaction event.

    • status Event Status
      Options:  PENDINGSCHEDULEDFAILEDREFUNDEDSUCCESSFULPAID_OUT

      Status of the transaction event.

    • amount number

      Amount of the event.

      Example: 58.8
    • due_date string format: date

      Date when the transaction event is due to occur.

      Example: "2020-05-25"
    • date string format: date

      Date when the transaction event occurred.

      Example: "2020-05-25"
    • installment_number integer

      Consecutive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.

      Example: 1
    • timestamp string format: date-time

      Date and time of the transaction event.

      Example: "2020-05-25T10:49:42.784Z"
  • simple_status string
    Options:  SUCCESSFULPAID_OUTCANCEL_FAILEDCANCELLEDCHARGEBACKFAILEDREFUND_FAILEDREFUNDEDNON_COLLECTIONPENDING

    Status generated from the processing status and the latest transaction state.

  • links []Link

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Link
    • rel string

      Specifies the relation to the current resource.

    • href string format: uri

      URL for accessing the related resource.

    • type string

      Specifies the media type of the related resource.

  • events []Event

    List of events related to the transaction.

     Show attributes
     Close
    Event
    • id Event ID

      Unique ID of the transaction event.

    • transaction_id Transaction ID

      Unique ID of the transaction.

    • type Event Type
      Options:  PAYOUTCHARGE_BACKREFUNDPAYOUT_DEDUCTION

      Type of the transaction event.

    • status Event Status
      Options:  PENDINGSCHEDULEDFAILEDREFUNDEDSUCCESSFULPAID_OUT

      Status of the transaction event.

    • amount number

      Amount of the event.

    • timestamp string format: date-time

      Date and time of the transaction event.

    • fee_amount number

      Amount of the fee related to the event.

    • installment_number integer

      Consecutive number of the installment.

    • deducted_amount number

      Amount deducted for the event.

    • deducted_fee_amount number

      Amount of the fee deducted for the event.

  • location object

    Details of the payment location as received from the payment terminal.

     Show attributes
     Close
    Attributes
    • lat Latitude minimum: 0, maximum: 90

      Latitude value from the coordinates of the payment location (as received from the payment terminal reader).

    • lon Longitude minimum: 0, maximum: 180

      Longitude value from the coordinates of the payment location (as received from the payment terminal reader).

    • horizontal_accuracy Horizontal Accuracy

      Indication of the precision of the geographical position received from the payment terminal.

  • tax_enabled boolean

    Indicates whether tax deduction is enabled for the transaction.

GET /v2.1/merchants/{merchant_code}/transactions 
curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.get("MH4H92C7");
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.GetAsync(
    "MH4H92C7"
);
import com.sumup.sdk.SumUpClient;


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


var result = client.transactions().getTransactionV2_1(
  "MH4H92C7"
);
from sumup import Sumup


client = Sumup()


result = client.transactions.get("MH4H92C7")
$sumup = new \SumUp\SumUp();


$result = $sumup->transactions->get('MH4H92C7');
client := sumup.NewClient()


result, err := client.Transactions.Get(context.Background(), "MH4H92C7")
use sumup::Client;


let client = Client::default();


let result = client.transactions().get("MH4H92C7", sumup::GetTransactionV2_1Params{
    id: Some("id".to_string()),
    internal_id: Some("internal_id".to_string()),
    transaction_code: Some("transaction_code".to_string()),
    foreign_transaction_id: Some("foreign_transaction_id".to_string()),
    client_transaction_id: Some("client_transaction_id".to_string()),
}).await;
Retrieve a transaction response
{
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": null,
  "payment_type": null,
  "installments_count": null,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": null,
  "auth_code": "053201",
  "internal_id": 1763892018,
  "product_summary": null,
  "payouts_total": null,
  "payouts_received": null,
  "payout_plan": null,
  "foreign_transaction_id": "J13253253x1",
  "client_transaction_id": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
  "username": null,
  "fee_amount": 8,
  "lat": null,
  "lon": null,
  "horizontal_accuracy": null,
  "merchant_id": 136902,
  "device_info": {
    "name": "m0xx",
    "system_name": "Android",
    "model": "GT-I9300",
    "system_version": "4.3",
    "uuid": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
  },
  "simple_payment_type": null,
  "verification_method": null,
  "card": {
    "last_4_digits": "3456",
    "type": null
  },
  "elv_account": {
    "sort_code": "87096214",
    "last_4_digits": "5674",
    "sequence_no": 1,
    "iban": "DE60870962140012345674"
  },
  "local_time": null,
  "payout_date": "2019-08-28",
  "payout_type": null,
  "process_as": "CREDIT",
  "products": [
    {
      "name": "Purchase reader for merchant with code ME3FCAVF",
      "price_label": null,
      "price": 100,
      "vat_rate": null,
      "single_vat_amount": null,
      "price_with_vat": null,
      "vat_amount": null,
      "quantity": 1,
      "total_price": 100,
      "total_with_vat": null
    }
  ],
  "vat_rates": [
    {
      "rate": 0.045,
      "net": 1.36,
      "vat": 0.06,
      "gross": 1.42
    }
  ],
  "transaction_events": [
    {
      "id": null,
      "event_type": null,
      "status": null,
      "amount": 58.8,
      "due_date": "2020-05-25",
      "date": "2020-05-25",
      "installment_number": 1,
      "timestamp": "2020-05-25T10:49:42.784Z"
    }
  ],
  "simple_status": null,
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ],
  "events": [
    {
      "id": null,
      "transaction_id": null,
      "type": null,
      "status": null,
      "amount": null,
      "timestamp": null,
      "fee_amount": null,
      "installment_number": null,
      "deducted_amount": null,
      "deducted_fee_amount": null
    }
  ],
  "location": {
    "lat": null,
    "lon": null,
    "horizontal_accuracy": null
  },
  "tax_enabled": null
}

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 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Transactions

List transactions

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

Lists detailed history of all transactions associated with the merchant profile.

Required scopes: transactions.history

Path Parameters

  • merchant_code string required
    Example: "MH4H92C7"

Query Parameters

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

  • order string default: ascending
    Options:  ascendingdescending

    Specifies the order in which the returned results are displayed.

  • limit integer

    Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.

  • users []string

    Filters the returned results by user email.

  • statuses[] []string
    Options:  SUCCESSFULCANCELLEDFAILEDREFUNDEDCHARGE_BACK

    Filters the returned results by the specified list of final statuses of the transactions.

  • payment_types []PaymentType
    Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

    Filters the returned results by the specified list of payment types used for the transactions.

  • entry_modes[] []EntryModeFilter
    Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

    Filters the returned results by the specified list of entry modes.

  • types []string
    Options:  PAYMENTREFUNDCHARGE_BACK

    Filters the returned results by the specified list of transaction types.

  • changes_since string 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).

  • newest_time string 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).

  • newest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are smaller than the specified value. This parameters supersedes the newest_time parameter (if both are provided in the request).

  • oldest_time string 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).

  • oldest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are greater than the specified value. This parameters supersedes the oldest_time parameter (if both are provided in the request).

Response

Returns a page of transaction history items.

  • items []TransactionHistory

    Transaction entry returned in history listing responses.

     Show attributes
     Close
    Transaction History
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • product_summary string

      Short description of the payment. The value is taken from the description property of the related checkout resource.

    • payouts_total integer

      Total number of payouts to the registered user specified in the user property.

    • payouts_received integer

      Number of payouts that are made to the registered user specified in the user property.

    • payout_plan string
      Options:  SINGLE_PAYMENTTRUE_INSTALLMENTACCELERATED_INSTALLMENT

      Payout plan of the registered user at the time when the transaction was made.

    • transaction_id Transaction ID

      Unique ID of the transaction.

    • client_transaction_id string

      Client-specific ID of the transaction.

    • user string format: email

      Email address of the registered user (merchant) to whom the payment is made.

    • type string
      Options:  PAYMENTREFUNDCHARGE_BACK

      Type of the transaction for the registered user specified in the user property.

    • card_type Card Type
      Options:  ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN

      Issuing card network of the payment card used for the transaction.

    • payout_date string format: date

      Payout date (if paid out at once).

      Example: "2019-08-28"
    • payout_type string
      Options:  BANK_ACCOUNTPREPAID_CARD

      Payout type.

      Example: "BANK_ACCOUNT"
    • refunded_amount number

      Total refunded amount.

      0
  • links []TransactionsHistoryLink

    Hypermedia link used for transaction history pagination.

     Show attributes
     Close
    Transactions History Link
    • rel string required

      Relation.

      Example: "next"
    • href string required

      Location.

      Example: "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"
GET /v2.1/merchants/{merchant_code}/transactions/history 
curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions/history \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.list("MH4H92C7");
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.ListAsync(
    "MH4H92C7"
);
import com.sumup.sdk.SumUpClient;


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


var result = client.transactions().listTransactionsV2_1(
  "MH4H92C7"
);
from sumup import Sumup


client = Sumup()


result = client.transactions.list("MH4H92C7")
$sumup = new \SumUp\SumUp();


$result = $sumup->transactions->list('MH4H92C7');
client := sumup.NewClient()


result, err := client.Transactions.List(context.Background(), "MH4H92C7")
use sumup::Client;


let client = Client::default();


let result = client.transactions().list("MH4H92C7", sumup::ListTransactionsV2_1Params{
    transaction_code: Some("transaction_code".to_string()),
    order: Some("order".to_string()),
    limit: Some("limit".to_string()),
    users: Some("users".to_string()),
    statuses: Some("statuses[]".to_string()),
    payment_types: Some("payment_types".to_string()),
    entry_modes: Some("entry_modes[]".to_string()),
    types: Some("types".to_string()),
    changes_since: Some("changes_since".to_string()),
    newest_time: Some("newest_time".to_string()),
    newest_ref: Some("newest_ref".to_string()),
    oldest_time: Some("oldest_time".to_string()),
    oldest_ref: Some("oldest_ref".to_string()),
}).await;
List transactions response
{
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null,
      "payout_date": "2019-08-28",
      "payout_type": "BANK_ACCOUNT",
      "refunded_amount": null
    }
  ],
  "links": [
    {
      "rel": "next",
      "href": "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"
    }
  ]
}

Content-Type: application/json

The request is invalid for the submitted query parameters.

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.
Error 400
{
  "message": "Validation error",
  "error_code": "INVALID"
}
Transactions

Retrieve a transactionDeprecated

GET /v0.1/me/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
  • internal_id
  • transaction_code
  • foreign_transaction_id
  • client_transaction_id
Required scopes: transactions.history

Query Parameters

  • id string

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

  • internal_id string

    Retrieves the transaction resource with the specified internal transaction ID (the internal_id parameter in the transaction resource).

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

Response

Returns the requested transaction resource.

  • id string

    Unique ID of the transaction.

    Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
  • transaction_code string

    Transaction code returned by the acquirer/processing entity after processing the transaction.

    Example: "TEENSK4W2K"
  • amount number

    Total amount of the transaction.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • timestamp string format: date-time

    Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56.876Z"
  • status string
    Options:  SUCCESSFULCANCELLEDFAILEDPENDING

    Current status of the transaction.

  • payment_type Payment Type
    Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

    Payment type used for the transaction.

  • installments_count integer minimum: 1

    Current number of the installment for deferred payments.

  • merchant_code string

    Unique code of the registered merchant to whom the payment is made.

    Example: "MH4H92C7"
  • vat_amount number

    Amount of the applicable VAT (out of the total transaction amount).

    Example: 6
  • tip_amount number

    Amount of the tip (out of the total transaction amount).

    Example: 3
  • entry_mode Entry Mode
    Options:  nonemagstripechipmanual entrycustomer entrymagstripe fallbackcontactlessmotocontactless magstripeboletodirect debitsofortidealbancontactepsmybanksatispayblikp24giropaypixqr code pixapple paygoogle paypaypalna

    Entry mode of the payment details.

  • auth_code string

    Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

    Example: "053201"
  • internal_id integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • product_summary string

    Short description of the payment. The value is taken from the description property of the related checkout resource.

  • payouts_total integer

    Total number of payouts to the registered user specified in the user property.

  • payouts_received integer

    Number of payouts that are made to the registered user specified in the user property.

  • payout_plan string
    Options:  SINGLE_PAYMENTTRUE_INSTALLMENTACCELERATED_INSTALLMENT

    Payout plan of the registered user at the time when the transaction was made.

  • foreign_transaction_id string

    External/foreign transaction id (passed by clients).

    Example: "J13253253x1"
  • client_transaction_id string

    Client transaction id.

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

    Email address of the registered user (merchant) to whom the payment is made.

  • fee_amount number

    Transaction SumUp total fee amount.

    Example: 8
  • lat Latitude minimum: 0, maximum: 90

    Latitude value from the coordinates of the payment location (as received from the payment terminal reader).

  • lon Longitude minimum: 0, maximum: 180

    Longitude value from the coordinates of the payment location (as received from the payment terminal reader).

  • horizontal_accuracy Horizontal Accuracy

    Indication of the precision of the geographical position received from the payment terminal.

  • merchant_id integer

    SumUp merchant internal Id.

    Example: 136902
  • device_info Device

    Details of the device used to create the transaction.

     Show attributes
     Close
    Device
    • name string

      Device name.

      Example: "m0xx"
    • system_name string

      Device OS.

      Example: "Android"
    • model string

      Device model.

      Example: "GT-I9300"
    • system_version string

      Device OS version.

      Example: "4.3"
    • uuid string

      Device UUID.

      Example: "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
  • simple_payment_type string
    Options:  CASHCC_SIGNATUREELVELV_WITHOUT_SIGNATURECC_CUSTOMER_ENTEREDMANUAL_ENTRYEMVRECURRINGBALANCEMOTOBOLETOAPMBITCOINCARD

    Simple name of the payment type.

  • verification_method string
    Options:  nonesignatureoffline PINonline PINoffline PIN + signaturena

    Verification method used for the transaction.

  • card Card Response

    Details of the payment card.

     Show attributes
     Close
    Card Response
    • last_4_digits string min length: 4, max length: 4, Read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type Card Type
      Options:  ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN

      Issuing card network of the payment card used for the transaction.

  • elv_account ELV Card Account

    Details of the ELV card account associated with the transaction.

     Show attributes
     Close
    ELV Card Account
    • sort_code string

      ELV card sort code.

      Example: "87096214"
    • last_4_digits string

      ELV card account number last 4 digits.

      Example: "5674"
    • sequence_no integer

      ELV card sequence number.

      Example: 1
    • iban string

      ELV IBAN.

      Example: "DE60870962140012345674"
  • local_time string format: date-time

    Local date and time of the creation of the transaction.

  • payout_date string format: date

    The date of the payout.

    Example: "2019-08-28"
  • payout_type string
    Options:  BANK_ACCOUNTPREPAID_CARD

    Payout type for the transaction.

  • process_as string
    Options:  CREDITDEBIT

    Debit/Credit.

    Example: "CREDIT"
  • products []Product

    List of products from the merchant's catalogue for which the transaction serves as a payment.

     Show attributes
     Close
    Product
    • name string

      Product name.

      Example: "Purchase reader for merchant with code ME3FCAVF"
    • price_label string

      Product description.

    • price number

      Product price.

      Example: 100
    • vat_rate number

      VAT percentage.

    • single_vat_amount number

      VAT amount for a single product.

    • price_with_vat number

      Product price incl. VAT.

    • vat_amount number

      VAT amount.

    • quantity integer

      Product quantity.

      Example: 1
    • total_price number

      Quantity x product price.

      Example: 100
    • total_with_vat number

      Total price incl. VAT.

  • vat_rates []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
    • rate number

      VAT rate.

      Example: 0.045
    • net number

      NET amount of products having this VAT rate applied.

      Example: 1.36
    • vat number

      VAT amount of this rate applied.

      Example: 0.06
    • gross number

      Gross amount of products having this VAT rate applied.

      Example: 1.42
  • transaction_events []TransactionEvent

    List of transaction events related to the transaction.

     Show attributes
     Close
    Transaction Event
    • id Event ID

      Unique ID of the transaction event.

    • event_type Event Type
      Options:  PAYOUTCHARGE_BACKREFUNDPAYOUT_DEDUCTION

      Type of the transaction event.

    • status Event Status
      Options:  PENDINGSCHEDULEDFAILEDREFUNDEDSUCCESSFULPAID_OUT

      Status of the transaction event.

    • amount number

      Amount of the event.

      Example: 58.8
    • due_date string format: date

      Date when the transaction event is due to occur.

      Example: "2020-05-25"
    • date string format: date

      Date when the transaction event occurred.

      Example: "2020-05-25"
    • installment_number integer

      Consecutive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.

      Example: 1
    • timestamp string format: date-time

      Date and time of the transaction event.

      Example: "2020-05-25T10:49:42.784Z"
  • simple_status string
    Options:  SUCCESSFULPAID_OUTCANCEL_FAILEDCANCELLEDCHARGEBACKFAILEDREFUND_FAILEDREFUNDEDNON_COLLECTIONPENDING

    Status generated from the processing status and the latest transaction state.

  • links []Link

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Link
    • rel string

      Specifies the relation to the current resource.

    • href string format: uri

      URL for accessing the related resource.

    • type string

      Specifies the media type of the related resource.

  • events []Event

    List of events related to the transaction.

     Show attributes
     Close
    Event
    • id Event ID

      Unique ID of the transaction event.

    • transaction_id Transaction ID

      Unique ID of the transaction.

    • type Event Type
      Options:  PAYOUTCHARGE_BACKREFUNDPAYOUT_DEDUCTION

      Type of the transaction event.

    • status Event Status
      Options:  PENDINGSCHEDULEDFAILEDREFUNDEDSUCCESSFULPAID_OUT

      Status of the transaction event.

    • amount number

      Amount of the event.

    • timestamp string format: date-time

      Date and time of the transaction event.

    • fee_amount number

      Amount of the fee related to the event.

    • installment_number integer

      Consecutive number of the installment.

    • deducted_amount number

      Amount deducted for the event.

    • deducted_fee_amount number

      Amount of the fee deducted for the event.

  • location object

    Details of the payment location as received from the payment terminal.

     Show attributes
     Close
    Attributes
    • lat Latitude minimum: 0, maximum: 90

      Latitude value from the coordinates of the payment location (as received from the payment terminal reader).

    • lon Longitude minimum: 0, maximum: 180

      Longitude value from the coordinates of the payment location (as received from the payment terminal reader).

    • horizontal_accuracy Horizontal Accuracy

      Indication of the precision of the geographical position received from the payment terminal.

  • tax_enabled boolean

    Indicates whether tax deduction is enabled for the transaction.

GET /v0.1/me/transactions 
curl https://api.sumup.com/v0.1/me/transactions \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.getDeprecated();
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.GetDeprecatedAsync();
import com.sumup.sdk.SumUpClient;


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


var result = client.transactions().getTransaction();
from sumup import Sumup


client = Sumup()


result = client.transactions.get_deprecated()
$sumup = new \SumUp\SumUp();


$result = $sumup->transactions->getDeprecated();
client := sumup.NewClient()


result, err := client.Transactions.GetDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.transactions().get_deprecated(sumup::GetTransactionParams{
    id: Some("id".to_string()),
    internal_id: Some("internal_id".to_string()),
    transaction_code: Some("transaction_code".to_string()),
}).await;
Retrieve a transaction response
{
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": null,
  "payment_type": null,
  "installments_count": null,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": null,
  "auth_code": "053201",
  "internal_id": 1763892018,
  "product_summary": null,
  "payouts_total": null,
  "payouts_received": null,
  "payout_plan": null,
  "foreign_transaction_id": "J13253253x1",
  "client_transaction_id": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
  "username": null,
  "fee_amount": 8,
  "lat": null,
  "lon": null,
  "horizontal_accuracy": null,
  "merchant_id": 136902,
  "device_info": {
    "name": "m0xx",
    "system_name": "Android",
    "model": "GT-I9300",
    "system_version": "4.3",
    "uuid": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
  },
  "simple_payment_type": null,
  "verification_method": null,
  "card": {
    "last_4_digits": "3456",
    "type": null
  },
  "elv_account": {
    "sort_code": "87096214",
    "last_4_digits": "5674",
    "sequence_no": 1,
    "iban": "DE60870962140012345674"
  },
  "local_time": null,
  "payout_date": "2019-08-28",
  "payout_type": null,
  "process_as": "CREDIT",
  "products": [
    {
      "name": "Purchase reader for merchant with code ME3FCAVF",
      "price_label": null,
      "price": 100,
      "vat_rate": null,
      "single_vat_amount": null,
      "price_with_vat": null,
      "vat_amount": null,
      "quantity": 1,
      "total_price": 100,
      "total_with_vat": null
    }
  ],
  "vat_rates": [
    {
      "rate": 0.045,
      "net": 1.36,
      "vat": 0.06,
      "gross": 1.42
    }
  ],
  "transaction_events": [
    {
      "id": null,
      "event_type": null,
      "status": null,
      "amount": 58.8,
      "due_date": "2020-05-25",
      "date": "2020-05-25",
      "installment_number": 1,
      "timestamp": "2020-05-25T10:49:42.784Z"
    }
  ],
  "simple_status": null,
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ],
  "events": [
    {
      "id": null,
      "transaction_id": null,
      "type": null,
      "status": null,
      "amount": null,
      "timestamp": null,
      "fee_amount": null,
      "installment_number": null,
      "deducted_amount": null,
      "deducted_fee_amount": null
    }
  ],
  "location": {
    "lat": null,
    "lon": null,
    "horizontal_accuracy": null
  },
  "tax_enabled": null
}

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 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Transactions

List transactionsDeprecated

GET /v0.1/me/transactions/history

Lists detailed history of all transactions associated with the merchant profile.

Required scopes: transactions.history

Query Parameters

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

  • order string default: ascending
    Options:  ascendingdescending

    Specifies the order in which the returned results are displayed.

  • limit integer

    Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.

  • users []string

    Filters the returned results by user email.

  • statuses[] []string
    Options:  SUCCESSFULCANCELLEDFAILEDREFUNDEDCHARGE_BACK

    Filters the returned results by the specified list of final statuses of the transactions.

  • payment_types []PaymentType
    Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

    Filters the returned results by the specified list of payment types used for the transactions.

  • types []string
    Options:  PAYMENTREFUNDCHARGE_BACK

    Filters the returned results by the specified list of transaction types.

  • changes_since string 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).

  • newest_time string 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).

  • newest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are smaller than the specified value. This parameters supersedes the newest_time parameter (if both are provided in the request).

  • oldest_time string 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).

  • oldest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are greater than the specified value. This parameters supersedes the oldest_time parameter (if both are provided in the request).

Response

Returns a page of transaction history items.

  • items []TransactionHistory

    Transaction entry returned in history listing responses.

     Show attributes
     Close
    Transaction History
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • product_summary string

      Short description of the payment. The value is taken from the description property of the related checkout resource.

    • payouts_total integer

      Total number of payouts to the registered user specified in the user property.

    • payouts_received integer

      Number of payouts that are made to the registered user specified in the user property.

    • payout_plan string
      Options:  SINGLE_PAYMENTTRUE_INSTALLMENTACCELERATED_INSTALLMENT

      Payout plan of the registered user at the time when the transaction was made.

    • transaction_id Transaction ID

      Unique ID of the transaction.

    • client_transaction_id string

      Client-specific ID of the transaction.

    • user string format: email

      Email address of the registered user (merchant) to whom the payment is made.

    • type string
      Options:  PAYMENTREFUNDCHARGE_BACK

      Type of the transaction for the registered user specified in the user property.

    • card_type Card Type
      Options:  ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN

      Issuing card network of the payment card used for the transaction.

    • payout_date string format: date

      Payout date (if paid out at once).

      Example: "2019-08-28"
    • payout_type string
      Options:  BANK_ACCOUNTPREPAID_CARD

      Payout type.

      Example: "BANK_ACCOUNT"
    • refunded_amount number

      Total refunded amount.

      0
  • links []TransactionsHistoryLink

    Hypermedia link used for transaction history pagination.

     Show attributes
     Close
    Transactions History Link
    • rel string required

      Relation.

      Example: "next"
    • href string required

      Location.

      Example: "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"
GET /v0.1/me/transactions/history 
curl https://api.sumup.com/v0.1/me/transactions/history \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.listDeprecated();
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.ListDeprecatedAsync();
import com.sumup.sdk.SumUpClient;


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


var result = client.transactions().listTransactions();
from sumup import Sumup


client = Sumup()


result = client.transactions.list_deprecated()
$sumup = new \SumUp\SumUp();


$result = $sumup->transactions->listDeprecated();
client := sumup.NewClient()


result, err := client.Transactions.ListDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.transactions().list_deprecated(sumup::ListTransactionsParams{
    transaction_code: Some("transaction_code".to_string()),
    order: Some("order".to_string()),
    limit: Some("limit".to_string()),
    users: Some("users".to_string()),
    statuses: Some("statuses[]".to_string()),
    payment_types: Some("payment_types".to_string()),
    types: Some("types".to_string()),
    changes_since: Some("changes_since".to_string()),
    newest_time: Some("newest_time".to_string()),
    newest_ref: Some("newest_ref".to_string()),
    oldest_time: Some("oldest_time".to_string()),
    oldest_ref: Some("oldest_ref".to_string()),
}).await;
List transactions response
{
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null,
      "payout_date": "2019-08-28",
      "payout_type": "BANK_ACCOUNT",
      "refunded_amount": null
    }
  ],
  "links": [
    {
      "rel": "next",
      "href": "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"
    }
  ]
}

Content-Type: application/json

The request is invalid for the submitted query parameters.

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.
Error 400
{
  "message": "Validation error",
  "error_code": "INVALID"
}