PAXORA

Home / Developers

◆ Developers · API v1

Money movement,

one request away.

A predictable REST API for payments, routing, payouts and ledgers. Sandbox in minutes, production when you're ready.

~/checkout — zsh
$
Fictional example APILayers hit · API → Routing → Processing → Settlement

Base URL

api.paxora.example/v1

Format

REST · JSON · HTTPS

Sandbox

Free, no real money

— 01 / Overview

An API that behaves

the way you expect.

Resource-oriented URLs, JSON in and out, standard HTTP codes. Every object carries an ID you can trace from request to settlement.

P.01

Predictable

Nouns for resources, verbs for actions. /v1/payments works the way /v1/payouts does.

P.02

Versioned

Pin a version per key. Breaking changes ship under a new version — never silently.

P.03

Safe to retry

Send an Idempotency-Key and a retried request can never charge twice.

P.04

Event-driven

Signed webhooks tell you when money moves, so you never poll for status.

Response codesFictional example API

200 / 201Success — the object is in the body
402Payment declined — see decline_code
409Idempotency key reused with a different body
429Rate limited — retry with backoff
5xxOur side — safe to retry with the same key

— 02 / API

Four layers.

One reference.

Endpoints are grouped by the clearing layer they act on. Choose a layer to filter the reference.

Showing all 16 endpoints

POST/v1/paymentsCreate a payment01 API
GET/v1/payments/{id}Retrieve a payment and its full timeline01 API
POST/v1/refundsRefund all or part of a payment01 API
POST/v1/customersStore a customer and their payment methods01 API
POST/v1/routing/rulesCreate a routing rule by card, country or amount02 Routing
GET/v1/routing/decisions/{id}Explain why a payment took its route02 Routing
POST/v1/processorsConnect an additional processor02 Routing
POST/v1/payments/{id}/captureCapture an authorised payment03 Processing
POST/v1/risk/assessmentsScore a payment before you submit it03 Processing
GET/v1/disputesList open disputes and deadlines03 Processing
POST/v1/disputes/{id}/evidenceSubmit evidence for a dispute03 Processing
GET/v1/balancesLive balances per currency and account04 Settlement
POST/v1/payoutsSend funds to a bank account04 Settlement
POST/v1/virtual_accountsOpen a virtual account for a customer or entity04 Settlement
GET/v1/ledger/entriesRead double-entry ledger lines04 Settlement
GET/v1/reconciliation/reportsDaily reconciliation, matched to the cent04 Settlement

— 03 / Quickstart

From zero to first payment

in four steps.

Everything below runs in the sandbox. No real money moves until you switch to live keys.

01

Step 01 · ~2 min

Get sandbox keys

Request a sandbox. Test keys appear in your dashboard — publishable for the browser, secret for your server.

Request sandbox access →

.env
export PAXORA_SECRET_KEY="sk_test_51Hx…4f2a"
export PAXORA_WEBHOOK_SECRET="whsec_…"

02

Step 02 · ~1 min

Install an SDK

Official libraries wrap authentication, retries and idempotency for you. Prefer raw HTTP? cURL works too.

All SDKs →

terminal
npm install @paxora/node

03

Step 03 · ~5 min

Create a payment

One call. PAXORA routes it, authorises it and schedules settlement — the response tells you exactly what happened.

Full example in four languages →

create-payment.js
const payment = await paxora.payments.create({
  amount: 124000, currency: "EUR", route: "smart",
});

04

Step 04 · ~5 min

Listen for webhooks

Forward sandbox events to your machine, verify the signature, and update your order when payment.succeeded arrives.

Verifying signatures →

terminal
paxora listen --forward-to localhost:3000/webhooks
→ payment.succeeded pay_8Hk2Qm4Tz [200 OK]

● Go live · swap sk_test_ for sk_live_ once your account is reviewed

— 04 / Examples

Same payment.

Your language.

Create a €1,240.00 payment with smart routing and a settlement account. Copy any tab — the response is identical.

POST/v1/paymentsResponse201 Created
create-payment.sh · Fictional example API
curl https://api.paxora.example/v1/payments \
  -u $PAXORA_SECRET_KEY: \
  -H "Idempotency-Key: order_48213" \
  -d amount=124000 \
  -d currency=EUR \
  -d customer=cus_4QmT9 \
  -d route=smart \
  -d "settlement[account]=va_eu_main"
application/json · 182 ms
{
  "id": "pay_8Hk2Qm4Tz",
  "object": "payment",
  "amount": 124000,
  "currency": "EUR",
  "status": "succeeded",
  "route": {
    "processor": "acquirer_b",
    "reason": "highest_approval",
    "attempts": 1
  },
  "settlement": {
    "account": "va_eu_main",
    "expected": "T+1"
  }
}
route.reasonWhy the routing layer chose this processor — no black box.
settlement.expectedWhen the funds land in the settlement account.

— 05 / Auth

Every request proves

who sent it.

Keys identify you, scopes limit what they can do, signatures prove our webhooks are ours, and idempotency keys make retries safe.

A.01

API keys

Authenticate with HTTP Basic auth: your secret key is the username, the password is empty. Keys are prefixed by type and mode, so a test key can never touch live money.

pk_

publishable — safe in the browser

sk_

secret — server only, never in client code

rk_

restricted — limited to the scopes you choose

KeyTypeMode
pk_test_••••••••7Qa1PublishableTest
sk_test_••••••••4f2aSecretTest
rk_live_••••••••9Lc0RestrictedLive
Rotate any key without downtime · old key valid 24 hExample values

A.02

Scopes

Give every service the smallest key it needs. A checkout service can create payments without ever being able to send a payout.

Restricted key ·checkout-service

ScopeReadWrite
payments✓Allowed✓Allowed
refunds✓AllowedDenied
balances✓AllowedDenied
payoutsDeniedDenied
webhooksDeniedDenied

A.03

Signed webhooks

Every event carries a Paxora-Signature header: a timestamp and an HMAC-SHA256 of the raw body, signed with your endpoint secret. Verify it before you trust the payload, and reject anything older than five minutes.

verify.js · Fictional example API
const event = paxora.webhooks.verify(
  rawBody,                                // the unparsed request body
  req.headers["paxora-signature"],
  process.env.PAXORA_WEBHOOK_SECRET,     // whsec_…
  { tolerance: 300 }                    // seconds
);
if (event.type === "payment.succeeded") {
  await orders.markPaid(event.data.id);
}

A.04

Idempotency keys

Networks fail. Send a unique Idempotency-Key with every POST and we store the first result for 24 hours — a retry returns that same result instead of creating a second payment.

09:41:07.000
POST/v1/paymentskey: order_48213201 · pay_8Hk2Qm4Tz created
09:41:07.182
Response lost — connection timed outClient sees nothing
09:41:09.000
POST/v1/paymentskey: order_48213201 · pay_8Hk2Qm4Tz replayed
ResultOne payment, one charge —
Idempotent-Replayed: trueCharged once

— 06 / SDKs

Libraries for

the stack you run.

Typed clients with retries, pagination and idempotency built in.

JS

Node.js

v4.2.0 · TypeScript types

npm install @paxora/node

PY

Python

v3.8.1 · async + sync

pip install paxora

GO

Go

v2.5.0 · context-aware

go get paxora.example/sdk-go

RB

Ruby

v3.1.4 · Rails-friendly

gem install paxora

JV

Java

v5.0.2 · JDK 17+

implementation "com.paxora:paxora-java:5.0.2"

PHP

PHP

v2.9.0 · PSR-18 client

composer require paxora/paxora-php

Integrations & tooling

Webhook CLI

Forward sandbox events to localhost and replay any of them.

● Available

API collection

Every endpoint, pre-authenticated, for your API client of choice.

● Available

Accounting export

Daily journal files mapped to your chart of accounts.

● Beta

Data warehouse sync

Ledger and payment tables, refreshed hourly.

● Beta

— 07 / Docs

Documentation index.

Jump to any part of this page, or ask an engineer directly.

D.01

Quickstart

First payment in four steps

→

D.02

API reference

Endpoints by clearing layer

→

D.03

Code examples

cURL, Node.js, Python, Go

→

D.04

API keys

Types, modes and rotation

→

D.05

Scopes

Least-privilege restricted keys

→

D.06

Webhooks

Events and signature checks

→

D.07

Idempotency

Retry without double charges

→

D.08

SDKs & tooling

Six languages, CLI, exports

→

D.09

Changelog

What shipped this month

→

◆ $ paxora init

Start building in the sandbox.

Test keys today. A solutions engineer when you're ready for production.

Create a free website with Framer, the website builder loved by startups, designers and agencies.