Refund a card payment (full or partial)

curl --request POST \
  --url https://api.suby.fi/api/refund/{paymentId} \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "reason": "Customer requested refund",
  "amountInCents": 500,
  "idempotencyKey": "refund-pay_abc123-01HZ..."
}
'

import requests

url = "https://api.suby.fi/api/refund/{paymentId}"

payload = {
    "reason": "Customer requested refund",
    "amountInCents": 500,
    "idempotencyKey": "refund-pay_abc123-01HZ..."
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reason: 'Customer requested refund',
    amountInCents: 500,
    idempotencyKey: 'refund-pay_abc123-01HZ...'
  })
};

fetch('https://api.suby.fi/api/refund/{paymentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.suby.fi/api/refund/{paymentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'Customer requested refund',
    'amountInCents' => 500,
    'idempotencyKey' => 'refund-pay_abc123-01HZ...'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.suby.fi/api/refund/{paymentId}"

	payload := strings.NewReader("{\n  \"reason\": \"Customer requested refund\",\n  \"amountInCents\": 500,\n  \"idempotencyKey\": \"refund-pay_abc123-01HZ...\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.suby.fi/api/refund/{paymentId}")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"Customer requested refund\",\n  \"amountInCents\": 500,\n  \"idempotencyKey\": \"refund-pay_abc123-01HZ...\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.suby.fi/api/refund/{paymentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"Customer requested refund\",\n  \"amountInCents\": 500,\n  \"idempotencyKey\": \"refund-pay_abc123-01HZ...\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "paymentId": "pay_abc123",
    "status": "PARTIALLY_REFUNDED",
    "refundedAmountCents": 500,
    "remainingRefundableCents": 500,
    "feeDebt": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

Refunds

Refund a card payment (full or partial)

Refunds a card (fiat) payment. Only payments with status PAYMENT_SUCCESS, CHECKOUT_SUCCESS (or PARTIALLY_REFUNDED, for a further partial) and source FIAT can be refunded. Crypto payments cannot be refunded from API.

Full vs partial refund

Omit amountInCents → the full remaining amount is refunded and the payment becomes REFUNDED.
Provide amountInCents → only that amount (in cents, in the payment’s currency) is refunded. You may call the endpoint multiple times as long as the cumulative refunded amount does not exceed the captured total (grossAmountCents). While a residual amount remains, the payment is PARTIALLY_REFUNDED; once the cumulative refunds reach the captured total it flips to REFUNDED.

The cumulative amount refunded so far is exposed as refundedAmountCents on the payment, and each call returns the remainingRefundableCents still available.

Webhooks: a partial refund emits PARTIAL_REFUNDED; the refund that completes the full amount (or a plain full refund) emits PAYMENT_REFUNDED.

Sandbox mode: For sandbox product payments, the refund skips the payment provider call and directly updates the payment status.

POST

api

refund

{paymentId}

Refund a card payment (full or partial)

curl --request POST \
  --url https://api.suby.fi/api/refund/{paymentId} \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "reason": "Customer requested refund",
  "amountInCents": 500,
  "idempotencyKey": "refund-pay_abc123-01HZ..."
}
'

import requests

url = "https://api.suby.fi/api/refund/{paymentId}"

payload = {
    "reason": "Customer requested refund",
    "amountInCents": 500,
    "idempotencyKey": "refund-pay_abc123-01HZ..."
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reason: 'Customer requested refund',
    amountInCents: 500,
    idempotencyKey: 'refund-pay_abc123-01HZ...'
  })
};

fetch('https://api.suby.fi/api/refund/{paymentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.suby.fi/api/refund/{paymentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'Customer requested refund',
    'amountInCents' => 500,
    'idempotencyKey' => 'refund-pay_abc123-01HZ...'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.suby.fi/api/refund/{paymentId}"

	payload := strings.NewReader("{\n  \"reason\": \"Customer requested refund\",\n  \"amountInCents\": 500,\n  \"idempotencyKey\": \"refund-pay_abc123-01HZ...\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.suby.fi/api/refund/{paymentId}")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"Customer requested refund\",\n  \"amountInCents\": 500,\n  \"idempotencyKey\": \"refund-pay_abc123-01HZ...\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.suby.fi/api/refund/{paymentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"Customer requested refund\",\n  \"amountInCents\": 500,\n  \"idempotencyKey\": \"refund-pay_abc123-01HZ...\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "paymentId": "pay_abc123",
    "status": "PARTIALLY_REFUNDED",
    "refundedAmountCents": 500,
    "remainingRefundableCents": 500,
    "feeDebt": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

Authorizations

X-Suby-Api-Key

string

header

required

API key authentication

Headers

Idempotency-Key

string

Optional. A unique string you generate per refund. Retrying a request with the same key replays the original result (response header Idempotency-Replayed: true) instead of issuing the refund again — making a timed-out request safe to retry. Reusing a key with a different request body returns 409. Especially important for partial refunds, which are otherwise legitimately repeatable.

Maximum string length: 255

Path Parameters

paymentId

string

required

Body

application/json

reason

string

Reason for the refund

Maximum string length: 500

Example:

"Customer requested refund"

amountInCents

integer

Optional. Amount to refund in cents, in the payment's currency. Omit to refund the full remaining amount. When provided, must not exceed the remaining refundable amount (grossAmountCents - refundedAmountCents).

Required range: x >= 1

Example:

500

idempotencyKey

string

Optional alternative to the Idempotency-Key header (the header takes precedence). Same behavior — retrying with the same value replays the original result instead of re-refunding.

Maximum string length: 255

Example:

"refund-pay_abc123-01HZ..."

Response

Refund initiated (or the stored result replayed for a repeated Idempotency-Key).

success

boolean

Example:

true

data

object

Show child attributes

Cancel a subscription Refund via payment route (deprecated)

Overview

Endpoints

Refund a card payment (full or partial)

Full vs partial refund

Authorizations

Headers

Path Parameters

Body

Response