Skip to content
SumUp Developer

Transactions

SumUp API reference and code samples.

Transactions

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

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.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

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;
Transactions

Retrieve a transaction

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.

Problem

  • type string uri required

    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 uri

    A URI reference that identifies the specific occurrence of the problem.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

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
}
Transactions

List transactions

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:  ascending descending

    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:  SUCCESSFUL CANCELLED FAILED REFUNDED CHARGE_BACK

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

  • payment_types []string

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

  • entry_modes[] []string

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

  • types []string
    Options:  PAYMENT REFUND CHARGE_BACK

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

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

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

Problem

  • type string uri required

    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 uri

    A URI reference that identifies the specific occurrence of the problem.

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"
    }
  ]
}
Transactions

Retrieve a transactionDeprecated

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.

Problem

  • type string uri required

    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 uri

    A URI reference that identifies the specific occurrence of the problem.

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

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
}
Transactions

List transactionsDeprecated

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:  ascending descending

    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:  SUCCESSFUL CANCELLED FAILED REFUNDED CHARGE_BACK

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

  • payment_types []string

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

  • types []string
    Options:  PAYMENT REFUND CHARGE_BACK

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

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

Error

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

Problem

  • type string uri required

    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 uri

    A URI reference that identifies the specific occurrence of the problem.

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"
    }
  ]
}