Refund a transaction

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

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.

1
curl https://api.sumup.com/v0.1/me/refund/{txn_id} \
2
 -X POST \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{}'

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

3
const client = new SumUp();
4

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

7
});

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Transactions.RefundAsync(
6
    "txn_id",
7
    new RefundTransactionBody
8
    {
9

10
    }
11
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.transactions().refundTransaction(
6
  "txn_id",
7
  RefundTransactionBody.builder()
8

9
    .build()
10
);

1
from sumup import Sumup
2

3
client = Sumup()
4

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

7
))

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

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

5
]);

1
client := sumup.NewClient()
2

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

5
})

1
use sumup::Client;
2

3
let client = Client::default();
4

5
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.

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

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

3
const client = new SumUp();
4

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

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Transactions.GetAsync(
6
    "MH4H92C7"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.transactions().getTransactionV2_1(
6
  "MH4H92C7"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.transactions.get("MH4H92C7")

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

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

1
client := sumup.NewClient()
2

3
result, err := client.Transactions.Get(context.Background(), "MH4H92C7")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.transactions().get("MH4H92C7", sumup::GetTransactionV2_1Params{
6
    id: Some("id".to_string()),
7
    internal_id: Some("internal_id".to_string()),
8
    transaction_code: Some("transaction_code".to_string()),
9
    foreign_transaction_id: Some("foreign_transaction_id".to_string()),
10
    client_transaction_id: Some("client_transaction_id".to_string()),
11
}).await;

1
{
2
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
3
  "transaction_code": "TEENSK4W2K",
4
  "amount": 10.1,
5
  "currency": "EUR",
6
  "timestamp": "2020-02-29T10:56:56.876Z",
7
  "status": null,
8
  "payment_type": null,
9
  "installments_count": null,
10
  "merchant_code": "MH4H92C7",
11
  "vat_amount": 6,
12
  "tip_amount": 3,
13
  "entry_mode": null,
14
  "auth_code": "053201",
15
  "internal_id": 1763892018,
16
  "product_summary": null,
17
  "payouts_total": null,
18
  "payouts_received": null,
19
  "payout_plan": null,
20
  "foreign_transaction_id": "J13253253x1",
21
  "client_transaction_id": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
22
  "username": null,
23
  "fee_amount": 8,
24
  "lat": null,
25
  "lon": null,
26
  "horizontal_accuracy": null,
27
  "merchant_id": 136902,
28
  "device_info": {
29
    "name": "m0xx",
30
    "system_name": "Android",
31
    "model": "GT-I9300",
32
    "system_version": "4.3",
33
    "uuid": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
34
  },
35
  "simple_payment_type": null,
36
  "verification_method": null,
37
  "card": {
38
    "last_4_digits": "3456",
39
    "type": null
40
  },
41
  "elv_account": {
42
    "sort_code": "87096214",
43
    "last_4_digits": "5674",
44
    "sequence_no": 1,
45
    "iban": "DE60870962140012345674"
46
  },
47
  "local_time": null,
48
  "payout_date": "2019-08-28",
49
  "payout_type": null,
50
  "process_as": "CREDIT",
51
  "products": [
52
    {
53
      "name": "Purchase reader for merchant with code ME3FCAVF",
54
      "price_label": null,
55
      "price": 100,
56
      "vat_rate": null,
57
      "single_vat_amount": null,
58
      "price_with_vat": null,
59
      "vat_amount": null,
60
      "quantity": 1,
61
      "total_price": 100,
62
      "total_with_vat": null
63
    }
64
  ],
65
  "vat_rates": [
66
    {
67
      "rate": 0.045,
68
      "net": 1.36,
69
      "vat": 0.06,
70
      "gross": 1.42
71
    }
72
  ],
73
  "transaction_events": [
74
    {
75
      "id": null,
76
      "event_type": null,
77
      "status": null,
78
      "amount": 58.8,
79
      "due_date": "2020-05-25",
80
      "date": "2020-05-25",
81
      "installment_number": 1,
82
      "timestamp": "2020-05-25T10:49:42.784Z"
83
    }
84
  ],
85
  "simple_status": null,
86
  "links": [
87
    {
88
      "rel": null,
89
      "href": null,
90
      "type": null
91
    }
92
  ],
93
  "events": [
94
    {
95
      "id": null,
96
      "transaction_id": null,
97
      "type": null,
98
      "status": null,
99
      "amount": null,
100
      "timestamp": null,
101
      "fee_amount": null,
102
      "installment_number": null,
103
      "deducted_amount": null,
104
      "deducted_fee_amount": null
105
    }
106
  ],
107
  "location": {
108
    "lat": null,
109
    "lon": null,
110
    "horizontal_accuracy": null
111
  },
112
  "tax_enabled": null
113
}

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

Options: CASH POS ECOM RECURRING BITCOIN BALANCE MOTO BOLETO DIRECT_DEBIT APM UNKNOWN

Filters the returned results by the specified list of payment types used for the transactions.
entry_modes[] []string

Options: BOLETO SOFORT IDEAL BANCONTACT EPS MYBANK SATISPAY BLIK P24 GIROPAY PIX QR_CODE_PIX APPLE_PAY GOOGLE_PAY PAYPAL NONE CHIP MANUAL_ENTRY CUSTOMER_ENTRY MAGSTRIPE_FALLBACK MAGSTRIPE DIRECT_DEBIT CONTACTLESS MOTO CONTACTLESS_MAGSTRIPE N/A

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.

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

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

3
const client = new SumUp();
4

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

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Transactions.ListAsync(
6
    "MH4H92C7"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.transactions().listTransactionsV2_1(
6
  "MH4H92C7"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.transactions.list("MH4H92C7")

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

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

1
client := sumup.NewClient()
2

3
result, err := client.Transactions.List(context.Background(), "MH4H92C7")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.transactions().list("MH4H92C7", sumup::ListTransactionsV2_1Params{
6
    transaction_code: Some("transaction_code".to_string()),
7
    order: Some("order".to_string()),
8
    limit: Some("limit".to_string()),
9
    users: Some("users".to_string()),
10
    statuses: Some("statuses[]".to_string()),
11
    payment_types: Some("payment_types".to_string()),
12
    entry_modes: Some("entry_modes[]".to_string()),
13
    types: Some("types".to_string()),
14
    changes_since: Some("changes_since".to_string()),
15
    newest_time: Some("newest_time".to_string()),
16
    newest_ref: Some("newest_ref".to_string()),
17
    oldest_time: Some("oldest_time".to_string()),
18
    oldest_ref: Some("oldest_ref".to_string()),
19
}).await;

1
{
2
  "items": [
3
    {
4
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
5
      "transaction_code": "TEENSK4W2K",
6
      "amount": 10.1,
7
      "currency": "EUR",
8
      "timestamp": "2020-02-29T10:56:56.876Z",
9
      "status": null,
10
      "payment_type": null,
11
      "installments_count": null,
12
      "product_summary": null,
13
      "payouts_total": null,
14
      "payouts_received": null,
15
      "payout_plan": null,
16
      "transaction_id": null,
17
      "client_transaction_id": null,
18
      "user": null,
19
      "type": null,
20
      "card_type": null,
21
      "payout_date": "2019-08-28",
22
      "payout_type": "BANK_ACCOUNT",
23
      "refunded_amount": null
24
    }
25
  ],
26
  "links": [
27
    {
28
      "rel": "next",
29
      "href": "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"
30
    }
31
  ]
32
}

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.

1
curl https://api.sumup.com/v0.1/me/transactions \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

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

3
const client = new SumUp();
4

5
const result = await client.transactions.getDeprecated();

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Transactions.GetDeprecatedAsync();

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.transactions().getTransaction();

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.transactions.get_deprecated()

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

3
$result = $sumup->transactions->getDeprecated();

1
client := sumup.NewClient()
2

3
result, err := client.Transactions.GetDeprecated(context.Background())

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.transactions().get_deprecated(sumup::GetTransactionParams{
6
    id: Some("id".to_string()),
7
    internal_id: Some("internal_id".to_string()),
8
    transaction_code: Some("transaction_code".to_string()),
9
}).await;

1
{
2
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
3
  "transaction_code": "TEENSK4W2K",
4
  "amount": 10.1,
5
  "currency": "EUR",
6
  "timestamp": "2020-02-29T10:56:56.876Z",
7
  "status": null,
8
  "payment_type": null,
9
  "installments_count": null,
10
  "merchant_code": "MH4H92C7",
11
  "vat_amount": 6,
12
  "tip_amount": 3,
13
  "entry_mode": null,
14
  "auth_code": "053201",
15
  "internal_id": 1763892018,
16
  "product_summary": null,
17
  "payouts_total": null,
18
  "payouts_received": null,
19
  "payout_plan": null,
20
  "foreign_transaction_id": "J13253253x1",
21
  "client_transaction_id": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
22
  "username": null,
23
  "fee_amount": 8,
24
  "lat": null,
25
  "lon": null,
26
  "horizontal_accuracy": null,
27
  "merchant_id": 136902,
28
  "device_info": {
29
    "name": "m0xx",
30
    "system_name": "Android",
31
    "model": "GT-I9300",
32
    "system_version": "4.3",
33
    "uuid": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
34
  },
35
  "simple_payment_type": null,
36
  "verification_method": null,
37
  "card": {
38
    "last_4_digits": "3456",
39
    "type": null
40
  },
41
  "elv_account": {
42
    "sort_code": "87096214",
43
    "last_4_digits": "5674",
44
    "sequence_no": 1,
45
    "iban": "DE60870962140012345674"
46
  },
47
  "local_time": null,
48
  "payout_date": "2019-08-28",
49
  "payout_type": null,
50
  "process_as": "CREDIT",
51
  "products": [
52
    {
53
      "name": "Purchase reader for merchant with code ME3FCAVF",
54
      "price_label": null,
55
      "price": 100,
56
      "vat_rate": null,
57
      "single_vat_amount": null,
58
      "price_with_vat": null,
59
      "vat_amount": null,
60
      "quantity": 1,
61
      "total_price": 100,
62
      "total_with_vat": null
63
    }
64
  ],
65
  "vat_rates": [
66
    {
67
      "rate": 0.045,
68
      "net": 1.36,
69
      "vat": 0.06,
70
      "gross": 1.42
71
    }
72
  ],
73
  "transaction_events": [
74
    {
75
      "id": null,
76
      "event_type": null,
77
      "status": null,
78
      "amount": 58.8,
79
      "due_date": "2020-05-25",
80
      "date": "2020-05-25",
81
      "installment_number": 1,
82
      "timestamp": "2020-05-25T10:49:42.784Z"
83
    }
84
  ],
85
  "simple_status": null,
86
  "links": [
87
    {
88
      "rel": null,
89
      "href": null,
90
      "type": null
91
    }
92
  ],
93
  "events": [
94
    {
95
      "id": null,
96
      "transaction_id": null,
97
      "type": null,
98
      "status": null,
99
      "amount": null,
100
      "timestamp": null,
101
      "fee_amount": null,
102
      "installment_number": null,
103
      "deducted_amount": null,
104
      "deducted_fee_amount": null
105
    }
106
  ],
107
  "location": {
108
    "lat": null,
109
    "lon": null,
110
    "horizontal_accuracy": null
111
  },
112
  "tax_enabled": null
113
}

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

Options: CASH POS ECOM RECURRING BITCOIN BALANCE MOTO BOLETO DIRECT_DEBIT APM UNKNOWN

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.

1
curl https://api.sumup.com/v0.1/me/transactions/history \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

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

3
const client = new SumUp();
4

5
const result = await client.transactions.listDeprecated();

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Transactions.ListDeprecatedAsync();

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.transactions().listTransactions();

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.transactions.list_deprecated()

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

3
$result = $sumup->transactions->listDeprecated();

1
client := sumup.NewClient()
2

3
result, err := client.Transactions.ListDeprecated(context.Background())

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.transactions().list_deprecated(sumup::ListTransactionsParams{
6
    transaction_code: Some("transaction_code".to_string()),
7
    order: Some("order".to_string()),
8
    limit: Some("limit".to_string()),
9
    users: Some("users".to_string()),
10
    statuses: Some("statuses[]".to_string()),
11
    payment_types: Some("payment_types".to_string()),
12
    types: Some("types".to_string()),
13
    changes_since: Some("changes_since".to_string()),
14
    newest_time: Some("newest_time".to_string()),
15
    newest_ref: Some("newest_ref".to_string()),
16
    oldest_time: Some("oldest_time".to_string()),
17
    oldest_ref: Some("oldest_ref".to_string()),
18
}).await;

1
{
2
  "items": [
3
    {
4
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
5
      "transaction_code": "TEENSK4W2K",
6
      "amount": 10.1,
7
      "currency": "EUR",
8
      "timestamp": "2020-02-29T10:56:56.876Z",
9
      "status": null,
10
      "payment_type": null,
11
      "installments_count": null,
12
      "product_summary": null,
13
      "payouts_total": null,
14
      "payouts_received": null,
15
      "payout_plan": null,
16
      "transaction_id": null,
17
      "client_transaction_id": null,
18
      "user": null,
19
      "type": null,
20
      "card_type": null,
21
      "payout_date": "2019-08-28",
22
      "payout_type": "BANK_ACCOUNT",
23
      "refunded_amount": null
24
    }
25
  ],
26
  "links": [
27
    {
28
      "rel": "next",
29
      "href": "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending"
30
    }
31
  ]
32
}