Transaction APIs, the developer way.

Transactology is a programmable money movement engine. Authorize, capture, refund, and reconcile transactions across 142 currencies through a single, idempotent REST API.

i

Heads up. Test mode keys start with tx_test_. Live mode keys start with tx_live_. Never commit your secret key to version control.

Make your first charge

Send a POST request to /v3/charges with an amount, currency, and a payment source token. The API responds with a fully reified Transaction object in under 80 ms.

 1import Transactology from "@transactology/node";
 2
 3const tx = new Transactology(process.env.TX_SECRET_KEY);
 4
 5const charge = await tx.charges.create({
 6  amount:      2499,
 7  currency:    "usd",
 8  source:      "src_3aWqLpYbN1",
 9  description: "Order #4471",
10  metadata:    { order_id: "4471" }
11});
12
13// charge.status === "succeeded"

 1import os
 2import transactology
 3
 4transactology.api_key = os.environ["TX_SECRET_KEY"]
 5
 6charge = transactology.Charge.create(
 7    amount=2499,
 8    currency="usd",
 9    source="src_3aWqLpYbN1",
10    description="Order #4471",
11    metadata={"order_id": "4471"},
12)
13
14# charge.status == "succeeded"

 1package main
 2
 3import (
 4    "os"
 5    tx "github.com/transactology/transactology-go"
  6)
 7
 8func main() {
 9    client := tx.NewClient(os.Getenv("TX_SECRET_KEY"))
10    charge, _ := client.Charges.Create(&tx.ChargeParams{
11        Amount:   2499,
12        Currency: "usd",
13        Source:   "src_3aWqLpYbN1",
14    })
15    _ = charge
16}

 1curl https://api.transactology.dev/v3/charges \
 2  -u "$TX_SECRET_KEY:" \
 3  -d amount=2499 \
 4  -d currency=usd \
 5  -d source=src_3aWqLpYbN1 \
 6  -d description="Order #4471" \
 7  -d "metadata[order_id]"=4471

Authentication

The API uses HTTP Basic Auth. Pass your secret key as the username; the password is left empty. All requests must be made over HTTPS — plain HTTP requests are rejected at the edge.

GET /v3/account Request

# Authorization: Basic base64(tx_live_KZb...:)
curl https://api.transactology.dev/v3/account \
  -u "tx_live_KZb6qN3JfWqTbN9LpRcVe2Hs:" \
  -H "Transactology-Version: 2026-04-01"

200 OK application/json Response

{
  "id": "acct_1Qx9PnLhT3kF8m",
  "object": "account",
  "business_name": "Northwind Trading Co.",
  "country": "US",
  "default_currency": "usd",
  "charges_enabled": true,
  "payouts_enabled": true,
  "livemode": true
}

Environment Prefix Scope Rate limit

Test tx_test_ Sandbox transactions 100 req/s

Live tx_live_ Real money movement 500 req/s

Restricted tx_rstr_ Scoped read/write 100 req/s

The Transaction object

A Transaction is the canonical record of money movement. Every charge, refund, payout, and adjustment produces exactly one transaction with a strictly monotonic ledger sequence.

Attributes

id string: Unique identifier prefixed with txn_.
amount integer: Amount in the smallest currency unit (cents, satoshi, etc.).
currency enum: Three-letter ISO 4217 code, lowercased.
status enum: pending | succeeded | failed | reversed
ledger_seq integer: Monotonic ledger position. Never reused.
created timestamp: Unix epoch seconds when the transaction was first written.
metadata hash: Up to 50 key/value pairs you can attach for your own bookkeeping.

transaction.json

{
  "id": "txn_1Q9PnTLhT3kF8mZ4",
  "object": "transaction",
  "amount": 2499,
  "currency": "usd",
  "status": "succeeded",
  "ledger_seq": 88471203,
  "source": {
    "id": "src_3aWqLpYbN1",
    "type": "card",
    "brand": "visa",
    "last4": "4242"
  },
  "created": 1762329611,
  "livemode": true,
  "metadata": {
    "order_id": "4471"
  }
}

Listening for events

Subscribe to webhook events to react to state changes. Each event is signed with HMAC-SHA256 — verify the Tx-Signature header before trusting the payload.

 1import express from "express";
 2import Transactology from "@transactology/node";
 3
 4const app = express();
 5const tx  = new Transactology(process.env.TX_SECRET_KEY);
 6
 7app.post("/hooks", express.raw({type: "*/*"}), (req, res) => {
 8  const sig = req.headers["tx-signature"];
 9  const evt = tx.webhooks.verify(req.body, sig, process.env.TX_HOOK_SECRET);
10
11  switch (evt.type) {
12    case "charge.succeeded":
13      ledger.credit(evt.data.id);
14      break;
15    case "charge.refunded":
16      ledger.debit(evt.data.id);
17      break;
18  }
19  res.sendStatus(200);
20});

 1import os
 2from flask import Flask, request
 3import transactology
 4
 5app = Flask(__name__)
 6
 7@app.post("/hooks")
 8def handle():
 9    sig   = request.headers["Tx-Signature"]
10    event = transactology.Webhook.verify(
11        request.data, sig, os.environ["TX_HOOK_SECRET"]
12    )
13    if event.type == "charge.succeeded":
14        ledger.credit(event.data.id)
15    return ("", 200)

 1func hookHandler(w http.ResponseWriter, r *http.Request) {
 2    body, _ := io.ReadAll(r.Body)
 3    sig    := r.Header.Get("Tx-Signature")
 4    event, err := webhook.Verify(body, sig, os.Getenv("TX_HOOK_SECRET"))
 5    if err != nil {
 6        http.Error(w, "bad signature", 400)
 7        return
 8    }
 9    dispatch(event)
10    w.WriteHeader(200)
11}

Event catalog

charge.succeeded

Authorized and captured. Funds are committed to the ledger.

charge.refunded

Funds returned to the original source. Includes partial refunds.

dispute.created

Issuer initiated a chargeback. Evidence due within 7 days.

payout.paid

Funds settled to your linked bank account.

transaction.reversed

Acquirer reversal posted. Fires for late authorizations.

account.updated

Capabilities, requirements, or settings changed on the account.

Errors

Transactology uses conventional HTTP response codes. 2xx indicates success, 4xx a client error, and 5xx indicates a Transactology-side issue (rare).

200 OK Everything worked as expected.

400 Bad Request The request was unacceptable, often missing a required parameter.

401 Unauthorized No valid API key provided.

402 Request Failed The parameters were valid but the request failed.

409 Conflict Idempotency key reused with mismatching parameters.

429 Too Many Requests Rate limit exceeded. Back off using exponential strategy.

500 Server Error Something went wrong on Transactology's end.