Create a transaction

curl --request POST \
  --url https://api.kordio.io/ledger/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "payment_intent": "pi_acme_1234",
    "channel": "web"
  },
  "postings": [
    {
      "account": "cash:usd",
      "amount": "10000000",
      "currency": "USDC",
      "direction": "debit"
    },
    {
      "account": "accounts_receivable:acme",
      "amount": "9700000",
      "currency": "USDC",
      "direction": "credit"
    },
    {
      "account": "revenue:subscriptions",
      "amount": "300000",
      "currency": "USDC",
      "direction": "credit"
    }
  ]
}
'

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

POST

ledger

transactions

curl --request POST \
  --url https://api.kordio.io/ledger/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "payment_intent": "pi_acme_1234",
    "channel": "web"
  },
  "postings": [
    {
      "account": "cash:usd",
      "amount": "10000000",
      "currency": "USDC",
      "direction": "debit"
    },
    {
      "account": "accounts_receivable:acme",
      "amount": "9700000",
      "currency": "USDC",
      "direction": "credit"
    },
    {
      "account": "revenue:subscriptions",
      "amount": "300000",
      "currency": "USDC",
      "direction": "credit"
    }
  ]
}
'

{
  "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"

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

dry_run

boolean

default:false

Body

application/json

postings

object[]

required

Minimum array length: 2

Show child attributes

idempotency_key

string

Alternative to the Idempotency-Key header. Required if header absent. Charset [A-Za-z0-9_:.-], max 255 bytes.

Maximum string length: 255

Example:

"pi_acme_1234_capture"

metadata

object

Free-form caller annotations. Mutable via PATCH.

Example:

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

value_date

string<date-time>

When the value transferred (vs booking_date, which is when we recorded the entry). Used by reports. Defaults to the booking time.

Example:

"2026-05-14T10:00:00Z"

Response

Replayed (same Idempotency-Key as a prior call).

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

Create a transaction

Authorizations

Headers

Query Parameters

Body

Response