Your store.
Arcana checkout.

Get connected

A small integration.
A complete payment flow.

Use the API from a custom storefront, commerce backend or server extension. Your store owns the cart, pricing and fulfillment. Arcana manages the payment page and payment status.

curl https://arcanapayments.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer $ARCANA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1842_attempt_1" \
  -d '{
    "items": [{"name": "Order 1842", "qty": 1, "amountUsd": 49}],
    "reference": "order_1842",
    "successUrl": "https://your-store.com/order/complete",
    "cancelUrl": "https://your-store.com/cart",
    "collectShipping": false,
    "expiresInMinutes": 60
  }'

Run this from your server or terminal with your merchant’s key. Creating a checkout does not charge a customer.

{
  "id": "inv_3f9c1e2a-7b4d-4c8e-a915-0d62b8e4f7a1",
  "kind": "checkout",
  "status": "open",
  "reference": "order_1842",
  "amountUsd": 49,
  "currency": "USD",
  "url": "https://arcanapayments.com/pay/UNGUESSABLE_TOKEN",
  "expiresAt": "2026-10-08T01:00:00.000Z",
  "expired": false
}

01 · Your backend

Turn a saved order into a checkout.

Calculate the final total on your server, including discounts, tax and shipping. Save the returned id against your order before redirecting the customer to url.

import { createArcanaClient } from "./arcana-payments.mjs";

const arcana = createArcanaClient({
  secretKey: process.env.ARCANA_SECRET_KEY,
});

// order comes from your authenticated server-side cart.
// Calculate products, discounts, tax and shipping in your store.
const checkout = await arcana.createCheckout({
  items: [{ name: "Order " + order.number,
    qty: 1, amountUsd: order.totalCents / 100 }],
  reference: order.publicId,
  collectShipping: false,
  successUrl: "https://your-store.com/order/complete",
  cancelUrl: "https://your-store.com/cart",
}, {
  idempotencyKey: order.paymentAttemptKey,
});

// Save checkout.id on the order, then redirect to checkout.url.
// Retrying this exact request uses the same paymentAttemptKey.

You can send individual line items when you want them shown at checkout. If your store already collects shipping, use collectShipping: false to avoid asking twice.

Reliability

One payment attempt. One key.

Send a stable Idempotency-Key for each order payment attempt. If a request times out, retry the same body with the same key. Arcana returns the checkout already created.

201 New checkout

First successful creation. Save the returned checkout ID.

200 Request replayed

Same merchant, key and normalized order details. The header Idempotency-Replayed: true identifies a retry.

409 Different details

idempotency_conflict means the key already belongs to another request. Review the existing order before starting a new attempt.

Keys use 8–128 letters, numbers, dots, colons, underscores or hyphens. They remain associated with the saved checkout, including after payment or expiry, for as long as the record is retained. Sandbox records expire from storage after 30 days. Changing a cart requires a deliberate new attempt; never rotate a key just because the network failed.

02 · Payment events

Let the payment come to you.

Set a webhook URL for each mode in the merchant settings. The API below configures Live webhooks. Arcana signs each event using that mode’s signing secret and retries failed deliveries.

curl -X PATCH https://arcanapayments.com/api/v1/merchant \
  -H "Authorization: Bearer $ARCANA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://your-store.com/api/arcana/webhook"}'

The event includes eventId and invoice with the checkout ID, your reference, amount, customer, shipping and payment details. An invoice.processing event means payment is still pending.

import { verifyArcanaWebhook, checkoutPaysOrder }
  from "./arcana-payments.mjs";

// In your server's POST handler, before any JSON body parser:
const raw = Buffer.from(await request.arrayBuffer());
const event = verifyArcanaWebhook(
  raw, request.headers, process.env.ARCANA_WEBHOOK_SECRET,
);

if (event.type === "invoice.paid" &&
    event.invoice?.kind === "checkout") {
  // Find the order using your saved Arcana checkout ID.
  const order = await yourOrders.byCheckoutId(event.invoice.id);
  const checkout = await arcana.retrieveCheckout(event.invoice.id);
  if (!order || !checkoutPaysOrder(checkout, {
    checkoutId: order.arcanaCheckoutId,
    reference: order.publicId,
    amountCents: order.totalCents,
  })) throw new Error("Payment does not match this order");

  // Your database transaction should deduplicate event.eventId AND
  // checkout.id, mark the order paid, and queue fulfillment once.
  await yourOrders.recordVerifiedPaymentOnce(order, event, checkout);
}
// Return 2xx only after the durable transaction/queue commits.
// Return an error if verification or durable processing fails.

yourOrders represents your own database integration. Connect the transaction and fulfillment queue before using this outline in production.

03 · Your order system

Confirm the payment on your server.

The buyer returns to successUrl with checkout_id. Use your saved order-to-checkout mapping and the authenticated status endpoint. The redirect alone does not prove payment.

curl https://arcanapayments.com/api/v1/checkout/sessions/inv_YOUR_ID \
  -H "Authorization: Bearer $ARCANA_SECRET_KEY"

A payment already in flight can complete after the checkout expires. Continue processing verified events for the saved checkout. Treat refunds as a separate workflow with the merchant’s payment method.

Request reference

The fields your store sends.

Use Authorization: Bearer <secret key> and Content-Type: application/json. Requests are limited to 64 KiB. Unknown fields and invalid value types are rejected.

itemsrequired

1–100 items. Each has a name (1–200 characters), integer qty (1–10,000), and numeric amountUsd unit price with at most two decimal places. Total: $1–$999,999.99, within merchant limits.

successUrlrequired

HTTPS page to return to after payment. Arcana adds checkout_id. Verify the payment on your server before showing an order as paid.

cancelUrloptional

HTTPS link back to your cart. Returning here does not cancel or refund a payment.

referencerecommended

Your opaque order identifier, up to 100 characters. Keep sensitive customer and product information out of identifiers and URLs.

collectShippingoptional

Defaults to true. Set false for digital products, services, or when your store already has the shipping address.

customerEmailoptional

Prefills the buyer’s email. Leave it out to collect it at checkout.

expiresInMinutesoptional

An integer from 15 to 10,080. Defaults to 1,440 (24 hours). An expired link cannot start a new payment.

railsoptional

A subset of your merchant’s enabled methods, such as stripe_card, stripe_bank, usdc_wallet, or zelle. Omit it to use the merchant configuration. Check rails_dropped in the response.