Refund a transaction (partial or full)

curl --request POST \
  --url https://api.kordio.io/ledger/v1/transactions/{id}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "5000000",
  "idempotency_key": "refund_pi_acme_1234_partial_01",
  "metadata": {
    "reason": "customer requested partial refund"
  }
}
'

import requests

url = "https://api.kordio.io/ledger/v1/transactions/{id}/refund"

payload = {
    "amount": "5000000",
    "idempotency_key": "refund_pi_acme_1234_partial_01",
    "metadata": { "reason": "customer requested partial refund" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: '5000000',
    idempotency_key: 'refund_pi_acme_1234_partial_01',
    metadata: {reason: 'customer requested partial refund'}
  })
};

fetch('https://api.kordio.io/ledger/v1/transactions/{id}/refund', 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.kordio.io/ledger/v1/transactions/{id}/refund",
  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([
    'amount' => '5000000',
    'idempotency_key' => 'refund_pi_acme_1234_partial_01',
    'metadata' => [
        'reason' => 'customer requested partial refund'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.kordio.io/ledger/v1/transactions/{id}/refund"

	payload := strings.NewReader("{\n  \"amount\": \"5000000\",\n  \"idempotency_key\": \"refund_pi_acme_1234_partial_01\",\n  \"metadata\": {\n    \"reason\": \"customer requested partial refund\"\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.kordio.io/ledger/v1/transactions/{id}/refund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"5000000\",\n  \"idempotency_key\": \"refund_pi_acme_1234_partial_01\",\n  \"metadata\": {\n    \"reason\": \"customer requested partial refund\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.kordio.io/ledger/v1/transactions/{id}/refund")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"5000000\",\n  \"idempotency_key\": \"refund_pi_acme_1234_partial_01\",\n  \"metadata\": {\n    \"reason\": \"customer requested partial refund\"\n  }\n}"

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

{
  "object": "account",
  "id": "3061ec4e-c959-49ba-a0f6-99186a7bd5d8",
  "postings": [
    {
      "object": "posting",
      "account": "accounts_receivable:acme",
      "amount": "9700000",
      "currency": "USDC",
      "direction": "credit",
      "id": 14829,
      "transaction": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pending": false,
      "tags": {
        "region": "EU",
        "department": "sales"
      },
      "value_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "idempotency_key": "pi_acme_1234_capture",
  "reverses": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reversed_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "refunds": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "refund_amount": "<string>",
  "exchange_rate": "1.0823",
  "base_currency": "USD",
  "quote_currency": "USDC",
  "metadata": {
    "payment_intent": "pi_acme_1234",
    "channel": "web"
  },
  "balances": [
    {
      "object": "account",
      "account": "accounts_receivable:acme",
      "currency": "USDC",
      "posted": "9700000",
      "pending": "0",
      "available": "9700000"
    }
  ],
  "value_date": "2023-11-07T05:31:56Z",
  "booking_date": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Refund a transaction (partial or full)

Books an inverse transaction for the requested amount, scaling every leg of the original (including legs in other currencies) by amount / gross_in(currency). Banker’s rounding; residual on the largest leg per currency, so the new transaction is balanced per currency.

currency is the base currency the caller is refunding. For single-currency originals it may be omitted and is inferred. For multi-currency originals it is required; omitting it returns refund_currency_required (422).

Sum of prior refunds is tracked per currency: a 100% USDC refund does not block a later 100% BTC refund on a USDC+BTC original. Refunds that would exceed the original’s remaining amount in the requested currency return partial_refund_exceeds_original (422). Idempotent on Idempotency-Key.

POST

ledger

transactions

{id}

refund

Refund a transaction (partial or full)

curl --request POST \
  --url https://api.kordio.io/ledger/v1/transactions/{id}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "5000000",
  "idempotency_key": "refund_pi_acme_1234_partial_01",
  "metadata": {
    "reason": "customer requested partial refund"
  }
}
'

import requests

url = "https://api.kordio.io/ledger/v1/transactions/{id}/refund"

payload = {
    "amount": "5000000",
    "idempotency_key": "refund_pi_acme_1234_partial_01",
    "metadata": { "reason": "customer requested partial refund" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: '5000000',
    idempotency_key: 'refund_pi_acme_1234_partial_01',
    metadata: {reason: 'customer requested partial refund'}
  })
};

fetch('https://api.kordio.io/ledger/v1/transactions/{id}/refund', 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.kordio.io/ledger/v1/transactions/{id}/refund",
  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([
    'amount' => '5000000',
    'idempotency_key' => 'refund_pi_acme_1234_partial_01',
    'metadata' => [
        'reason' => 'customer requested partial refund'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.kordio.io/ledger/v1/transactions/{id}/refund"

	payload := strings.NewReader("{\n  \"amount\": \"5000000\",\n  \"idempotency_key\": \"refund_pi_acme_1234_partial_01\",\n  \"metadata\": {\n    \"reason\": \"customer requested partial refund\"\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.kordio.io/ledger/v1/transactions/{id}/refund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"5000000\",\n  \"idempotency_key\": \"refund_pi_acme_1234_partial_01\",\n  \"metadata\": {\n    \"reason\": \"customer requested partial refund\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.kordio.io/ledger/v1/transactions/{id}/refund")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"5000000\",\n  \"idempotency_key\": \"refund_pi_acme_1234_partial_01\",\n  \"metadata\": {\n    \"reason\": \"customer requested partial refund\"\n  }\n}"

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

{
  "object": "account",
  "id": "3061ec4e-c959-49ba-a0f6-99186a7bd5d8",
  "postings": [
    {
      "object": "posting",
      "account": "accounts_receivable:acme",
      "amount": "9700000",
      "currency": "USDC",
      "direction": "credit",
      "id": 14829,
      "transaction": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pending": false,
      "tags": {
        "region": "EU",
        "department": "sales"
      },
      "value_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "idempotency_key": "pi_acme_1234_capture",
  "reverses": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reversed_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "refunds": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "refund_amount": "<string>",
  "exchange_rate": "1.0823",
  "base_currency": "USD",
  "quote_currency": "USDC",
  "metadata": {
    "payment_intent": "pi_acme_1234",
    "channel": "web"
  },
  "balances": [
    {
      "object": "account",
      "account": "accounts_receivable:acme",
      "currency": "USDC",
      "posted": "9700000",
      "pending": "0",
      "available": "9700000"
    }
  ],
  "value_date": "2023-11-07T05:31:56Z",
  "booking_date": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Same flow; ledger:write is required for any mutation.

Headers

Idempotency-Key

string

Required on writes. Stable identifier you choose. The same key always returns the same transaction, forever. Can also be supplied as idempotency_key in the request body. Header wins.

Allowed character set: A-Z, a-z, 0-9, _, :, ., -. Max 255 bytes. Replays of an accepted key return the original response with header Idempotent-Replayed: true so callers can tell a replay from a freshly-committed result.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_:.\-]+$

Example:

"pi_acme_1234_capture"

Path Parameters

string<uuid>

required

Query Parameters

expand

enum<string>[]

Comma-separated. postings.account inlines each posting's account object; balances adds the post-commit balance of every touched account.

Available options:

postings.account,

balances

Body

application/json

amount

required

Refund amount in minor units. Accepts a positive decimal string (recommended) or an integer on write.

Pattern: ^\d+$

Example:

"5000000"

currency

string

The base currency to refund. Optional for single-currency originals (inferred). Required for multi-currency originals; omitting returns refund_currency_required (422).

Example:

"USDC"

idempotency_key

string

Optional body alternative to the Idempotency-Key header. Header wins.

metadata

object

Response

Idempotency replay (original refund returned)

object

enum<string>

required

Discriminator naming the shape of this resource (e.g. account, transaction).

Available options:

transaction

Example:

"account"

string<uuid>

required

Example:

"3061ec4e-c959-49ba-a0f6-99186a7bd5d8"

postings

object[]

required

Show child attributes

idempotency_key

string

Example:

"pi_acme_1234_capture"

reverses

string<uuid> | null

Set when this transaction reverses another.

reversed_by

string<uuid> | null

Set when this transaction has been reversed.

refunds

string<uuid> | null

Set when this transaction refunds another (partial or full).

refund_amount

string | null

Minor units refunded, as a decimal string. Parse with a big-integer or decimal type, never a JS number. Present only on refund transactions.

Pattern: ^-?\d+$

exchange_rate

string | null

Decimal string. Present only when the transaction has postings in more than one currency. The rate that was in effect at write time. It is persisted for audit and restatement, never recomputed.

Example:

"1.0823"

base_currency

string | null

Currency that the exchange rate quotes from. Set with exchange_rate.

Example:

"USD"

quote_currency

string | null

Currency that the exchange rate quotes to. Set with exchange_rate.

Example:

"USDC"

metadata

object

Example:

{
  "payment_intent": "pi_acme_1234",
  "channel": "web"
}

balances

object[]

Returned only when ?expand=balances.

Show child attributes

value_date

string<date-time>

booking_date

string<date-time>

created_at

string<date-time>

updated_at

string<date-time>

Get started

Core concepts

Guarantees

Reference

Endpoints

Refund a transaction (partial or full)

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response