Skip to content
Allidian

Developers

A payments API with no surprises.

Predictable REST resources, integer amounts in minor units, idempotent writes, signed webhooks and a full sandbox that behaves like live.

Get test API keysAPI reference
Developers working at their desks

Developer tools

API reference

Endpoint-by-endpoint documentation with request and response examples.

Learn more

OpenAPI 3 spec

Download the machine-readable spec to generate clients or import into your API tools.

Learn more

Sandbox environment

Separate data, keys and webhooks. Test the full lifecycle with no real money involved.

Learn more

Authentication

Bearer keys, scoped by environment.

Authenticate every request with a secret key in the Authorization header. Keys carry their environment in the prefix: al_sk_test_… for sandbox and al_sk_live_… for live.

Secret keys are shown once at creation and stored only as hashes. Restricted keys can be limited to specific scopes, and any key can be revoked instantly from the dashboard.

  • Never embed secret keys in browsers or mobile apps.
  • A sandbox key can never read or write live data, and vice versa.
list-payments.sh
curl "https://api.allidian.com/v1/payments?limit=10" \
  -H "Authorization: Bearer al_sk_test_..."

Idempotency

Retry without fear of double charges.

Send an Idempotency-Key header on POST requests. If a request is retried with the same key and body, you get the original response instead of a duplicate action.

Money-moving operations such as refunds and captures require an idempotency key. Reusing a key with a different body returns an idempotency_conflict error.

refund.sh
curl -X POST "https://api.allidian.com/v1/payments/<id>/refunds" \
  -H "Authorization: Bearer al_sk_test_..." \
  -H "Idempotency-Key: 6f1c2a90-refund-order-8812" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500 }'
error-response.json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "currency: String must contain exactly 3 character(s)",
    "request_id": "req_8f2c..."
  }
}

Webhooks

Signed events, delivered reliably.

Register HTTPS endpoints per environment. Every delivery includes an x-platform-signature header in the form t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of `${t}.${body}` using your endpoint secret.

Verify the signature against the raw request body, reject old timestamps, and respond with a 2xx status quickly. Failed deliveries are retried with backoff, and each delivery carries x-platform-event-id so you can de-duplicate.

Event types include

  • payment.succeeded
  • payment.failed
  • payment.refunded
  • payment.disputed
  • checkout.session.completed
  • checkout.session.expired
  • invoice.finalized
  • invoice.paid
  • invoice.overdue
  • subscription.created
  • subscription.updated
  • subscription.canceled
  • account.capabilities_updated
verify-webhook.js
import crypto from "node:crypto";

// header: x-platform-signature: t=1761234567,v1=5257a8...
export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // replay window

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Resources

One consistent shape across the API.

List endpoints are paginated with limit and starting_after. Amounts are integers in minor units, alongside a three-letter currency code.

API resources
ResourcePath
Checkout sessions/v1/checkout/sessions
Payments/v1/payments
Refunds/v1/payments/:id/refunds
Payment links/v1/payment-links
Invoices/v1/invoices
Customers/v1/customers
Products & prices/v1/products
Subscriptions/v1/subscriptions
Events/v1/events
Webhook endpoints/v1/developer/webhooks
Account & capabilities/v1/merchant/capabilities

Prefer webhooks to polling

Webhooks tell you the moment a payment succeeds, an invoice is paid or a subscription changes. Use the Events API to reconcile anything you might have missed.

Webhook guide →

Start building in sandbox today.

Create a free Developer account and start making API calls right away. No card required.

Start buildingView documentation

No sales call required. Create an account and access your developer sandbox.

  • Payment succeeded$248.00 · Hosted checkout
  • Invoice paidINV-0142 · $5,616.00
  • Webhook deliveredpayment.succeeded · 200 OK