Refund a transaction

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

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

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

OAuth scopes: Requires one of: payments, refunds.write.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes paymentsrefunds.write

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

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

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

Body parameters

application/json

Optional amount for partial refunds.

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

Example: 5

Responses

201application/json

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

400application/problem+json

The refund request is invalid.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

403application/problem+json

The request is authenticated but not permitted for this operation.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

404application/problem+json

The requested transaction does not exist or does not belong to the merchant.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

409application/problem+json

The transaction cannot be refunded due to business constraints.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

422application/problem+json

The refund could not be processed by the payment processor.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Code sample

curl --request POST \
  --url https://api.sumup.com/v1.0/merchants/MH4H92C7/payments/4ffb8dfc-7f2b-413d-a497-2ad00766585e/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 5
}'

import SumUp from "@sumup/sdk";

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

  const result = await client.transactions.refund(
    "MH4H92C7",
    "4ffb8dfc-7f2b-413d-a497-2ad00766585e",
    {
      "amount": 5
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Transactions.RefundAsync(
            "your-merchant-code",
            "example-id",
            new TransactionsRefundRequest
            {
                Amount = 5f,
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

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

import os

import sumup

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

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

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

$body = [
    'amount' => 5,
];

$result = $sumup->transactions()->refund(
    'MH4H92C7',
    '4ffb8dfc-7f2b-413d-a497-2ad00766585e',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

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

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

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

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::transactions::RefundRequest::builder()
        .amount(5f32)
        .build();
    let response = client
        .transactions()
        .refund("MERCHANT_CODE", "TRANSACTION_ID", Some(body))
        .await
        .expect("refund request failed");
    println!("{response:#?}");
}

Response example

{}

{
  "type": "https://developer.sumup.com/problem/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "amount must be greater than zero"
}

{
  "type": "https://developer.sumup.com/problem/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "users is not allowed to make a refund"
}

{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Transaction not found"
}

{
  "type": "https://developer.sumup.com/problem/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The transaction is not refundable in its current state"
}

{
  "type": "https://developer.sumup.com/problem/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Refund failed.",
  "errors": [
    {
      "code": "INVALID_AMOUNT",
      "detail": "Amount exceeds the refundable amount",
      "reason": "amount_too_high",
      "max_refundable_amount": 1000
    }
  ]
}