Accept Payments

Sell something from your own site and get paid into your Avvio balance. You create a checkout link on your server, send the buyer to its shareUrl, and hear about the payment on a webhook. If you have integrated Stripe Checkout, every field here has a name you already know; the mapping table is at the bottom.

This is money arriving. Everything else on this site is money leaving. The two share one API key, one webhook endpoint and one event feed.

Live keys only, for now. Checkout has no sandbox yet. A test key (avvio_test_…) gets 400 TEST_MODE_UNSUPPORTED on every checkout route, and the message says so in one sentence rather than pretending it is a permissions problem. Use a live key against a verified organization: a live link with no payments costs nothing, and you can pause or delete it. We would rather tell you this here than have you discover it after building.

export AVVIO_API_KEY=avvio_live_…
export AVVIO_ORG_ID=cmsx…
export AVVIO_BASE_URL=https://api.avvio.xyz/business/api/v1

Every route lives under /checkout/organizations/{orgId}. Reads work with a read-only key; creating, publishing and pausing need write, and a read-only key on a write is 403 INSUFFICIENT_SCOPE.

1. Create a product#

A product is a name and one fixed price in one currency. Links are made from it, so you describe the thing once and sell it many times.

avvio-payments product create --name "Consulting (60 min)" --currency USD --amount 150.00

# Set AVVIO_IDEMPOTENCY_KEY once; reuse it on every retry.
curl -s -X POST "$AVVIO_BASE_URL/checkout/organizations/$AVVIO_ORG_ID/products" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $AVVIO_IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "name": "Consulting (60 min)",
        "currency": "USD",
        "unitAmount": "150.00"
      }'

const product = await avvio.createProduct({
  name: 'Consulting (60 min)',
  currency: 'USD',
  unitAmount: '150.00',
});
// → { id, name, currency, unitAmount, archivedAt: null, linkCount: 0, … }

Keep id. A link made from a product copies its name and price at that moment; repricing the product later changes nothing about links already made, which is the behaviour you want for a URL you have already sent to people. The description and image are read live, so a typo fixed on the product is fixed on every page.

You can skip this step and send currency + items on the link instead, for a one-off amount. Sending both a productId and items is a 400.

2. Create a link and send the buyer to it#

One call, with publish: true, returns a live link whose shareUrl is the page to redirect the buyer to.

avvio-payments checkout create --product 2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d \
  --success-url https://example.com/thanks --cancel-url https://example.com/pricing \
  --ref order_1042 --meta orderId=1042

# Set AVVIO_IDEMPOTENCY_KEY once; reuse it on every retry.
curl -s -X POST "$AVVIO_BASE_URL/checkout/organizations/$AVVIO_ORG_ID/links" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $AVVIO_IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "productId": "2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d",
        "successUrl": "https://example.com/thanks",
        "cancelUrl": "https://example.com/pricing",
        "clientReferenceId": "order_1042",
        "metadata": {
          "orderId": "1042"
        },
        "publish": true
      }'

const link = await avvio.createCheckoutLink({
  productId: product.id,                    // 2a7b8c9d-1e2f-4a5b-8c9d-0e1f2a3b4c5d
  successUrl: 'https://example.com/thanks',
  cancelUrl: 'https://example.com/pricing',
  clientReferenceId: 'order_1042',          // your order id: the join key
  metadata: { orderId: '1042' },
  publish: true,                             // live now; the response carries shareUrl
});
res.redirect(link.shareUrl);

What the four Stripe-shaped fields do:

Also worth knowing:

• methods omitted means card. The hosted card page takes cards, wallets and PayPal in one. Pass methods explicitly to offer bank or crypto (each needs the account or address to pay into) or to combine rails. methods: [] is a link nothing can pay, and we take you at your word.

• fromName defaults to your organization's name. It is what the buyer sees on the page and, failing a statementDescriptor, on their statement.

• Without publish: true you get a draft: not publicly readable, editable with PATCH, deletable. POST /links/{linkId}/publish makes it live. The dashboard works this way; a server integration usually does not need the intermediate state.

• Idempotency-Key is required on every write. Every POST, PATCH and DELETE under /checkout refuses an API-key call without one (400 IDEMPOTENCY_KEY_REQUIRED), and a retry under the same key returns the original response rather than a second link or product. The Node SDK mints one per call when you do not pass it. See Idempotency.

When publishing is refused#

Publishing a card link mints the hosted page behind it, and that step can be refused: a business whose card onboarding is not finished, a currency the card processor cannot price. When that happens inside a publish: true create, the call still answers 201 with the kept draft and a publishError saying why:

{
  "id": "4f1c2a9e-…",
  "slug": "7e2a9c4b1d0f",
  "status": "draft",                 // not "sent"
  "shareUrl": "https://…/i/7e2a9c4b1d0f",   // answers 404 while a draft
  "…": "…",
  "publishError": {
    "status": 400,
    "type": "BAD_REQUEST",
    "message": "This business is not set up to accept cards yet. Finish card onboarding, then publish the link."
  }
}

Branch on status !== "sent", then read publishError. Its type uses the same vocabulary as an error envelope (BAD_REQUEST, CONFLICT, NOT_FOUND, FORBIDDEN, INTERNAL, or a more specific code). Fix the cause and POST /links/{linkId}/publish, or DELETE the draft. It comes back as a 201 rather than an error on purpose: a stored idempotent response is only kept for a success, so an error would release your key and an automatic retry would create a second draft. A draft is invisible and unpayable either way.

Link states#

A live link cannot be edited: it is a URL someone may already be looking at, and repricing it under them is a money bug. Pause it and create a new one. A link that has been live cannot be deleted either, because its payments live under it. Pause is the one exit.

3. Fulfil on checkout_payment.paid#

The webhook is how your server learns the buyer paid. Four event types make up the family:

Subscribe explicitly. An endpoint registered with an empty events list receives every payout-side type but not this family. Name the types you want when you register the endpoint (a live endpoint is registered from the dashboard by a human, for the reasons in Webhooks):

{ "url": "https://example.com/hooks/avvio", "events": ["checkout_payment.paid", "checkout_payment.refunded", "checkout_payment.reversed"] }

This is deliberate: a receiver written for payouts that answers 4xx to a type it does not know would climb toward auto-disable, and a checkout feature must not switch off a payout webhook.

The body is the same envelope as every other event, with data shaped as WebhookCheckoutPayment:

{
  "id": "cmf9x1b2c0003q8b7h6j8k0lm",   // equals svix-id. Dedupe on this
  "sequence": "48213",
  "type": "checkout_payment.paid",
  "createdAt": "2026-09-12T10:00:04.000Z",
  "apiVersion": 1,
  "livemode": true,
  "data": {
    "paymentId": "cmf9x1b2c0003q8b7h6j8k0lm",
    "linkId": "4f1c2a9e-8f7d-4c3b-9a2e-6b5d4c3f2a10",
    "linkSlug": "7e2a9c4b1d0f",
    "productId": "2a7b8c9d-…",
    "clientReferenceId": "order_1042",   // your join key
    "metadata": { "orderId": "1042" },
    "status": "paid",
    "failureCode": null,
    "kind": "card",                      // card | bank | crypto | cashapp. Never the processor
    "amount": "150.00",                  // decimal string in `currency`
    "currency": "USD",
    "fee": "4.35",                       // "0.00" when none was stated
    "net": "145.65",                     // null when the processor did not say
    "refunded": null,
    "paidAt": "2026-09-12T10:00:04.000Z",
    "createdAt": "2026-09-12T09:59:58.000Z"
  }
}

A handler that does the four things that matter:

const { verifyWebhook } = require('@avvio/payments');

app.post('/hooks/avvio', express.raw({ type: '*/*' }), async (req, res) => {
  let event;
  try {
    event = verifyWebhook({ body: req.body, headers: req.headers, secret: process.env.AVVIO_WEBHOOK_SECRET });
  } catch {
    return res.sendStatus(400);                       // 1. verify over the raw bytes
  }
  res.sendStatus(200);                                // ack first, work after

  if (event.type !== 'checkout_payment.paid') return handleOther(event);
  if (await seen(event.id)) return;                   // 2. dedupe on the event id
  const { clientReferenceId, amount, currency } = event.data;
  const order = await orders.find(clientReferenceId); // 3. join on YOUR reference
  if (!order) return alert('paid, no order', event);
  if (order.total !== amount || order.currency !== currency) {
    return alert('amount mismatch', event);           // 4. compare amount + currency
  }
  await fulfil(order, event.data.paymentId);
});

clientReferenceId on the event is the buyer visit's ?client_reference_id= when the card page carried one, else the one you set on the link. Compare amount and currency against your own record of the order before fulfilling; a buyer paid what the link asked, but the order is yours to check.

Recovering. Webhooks are the fast path, not the guarantee. Every event is also a row in the feed, and a delivery you never received is indistinguishable from one that never fired:

curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/events?type=checkout_payment.paid&since=$SINCE" \
  -H "x-api-key: $AVVIO_API_KEY"

Carry nextSince back as since. The feed publishes a row about two seconds after the write, so a poll fired the instant a test payment lands can be empty for a beat; the webhook does not wait. The recipe is in Reconciliation; a checkout event is one more type on the same feed.

4. The success page#

After a card payment the payer page sends the buyer to your successUrl with two query parameters appended:

https://example.com/thanks?avvio_link=7e2a9c4b1d0f&client_reference_id=order_1042

avvio_link is the link's public slug, the last path segment of shareUrl (the public page carries no id). The create response returns slug beside id, so remember the pair, or list your links and match on slug. client_reference_id is present when we know it (the link's, or the one the buyer's visit carried). Bank and crypto payments never redirect; they settle later and you hear about them on the webhook.

Do not trust the redirect. Anyone can type that URL. The redirect tells the page which order to show; whether it is paid comes from the webhook, or from the authoritative read:

avvio-payments checkout payments <linkId>

curl -s "$AVVIO_BASE_URL/checkout/organizations/$AVVIO_ORG_ID/links/$linkId/payments" \
  -H "x-api-key: $AVVIO_API_KEY"

const { items } = await avvio.listCheckoutPayments(linkId);
const paid = items.find(
  (p) => p.status === 'paid' && p.clientReferenceId === orderId,
);
// amountBase "15000" at decimals 2 is 150.00

Amounts on this read are base units with decimals beside them ("15000" at decimals: 2 is 150.00), the dashboard's convention. The webhook body for the same payment uses decimal strings. clientReferenceId on a payment row is the buyer visit's, card rail only; the link-level one is on the link.

5. No code: a link from the dashboard#

You do not need a server to sell one thing. Create the product and the link in the dashboard, publish it, and paste shareUrl wherever you like:

<a href="https://business.avvio.xyz/i/7e2a9c4b1d0f">Buy now</a>

To carry a per-buyer reference without a server, append ?client_reference_id=<value> to shareUrl:

<a href="https://business.avvio.xyz/i/7e2a9c4b1d0f?client_reference_id=order_1042">Buy now</a>

It arrives as clientReferenceId on the payment and on the event. Two honest limits:

• Card rail only, best effort. It rides the buyer's visit into the card session. It is dropped on the hosted-fallback and 3DS-restore paths, and a bank payer types the link's slug as their reference, so nothing carries it there.

• The link-level clientReferenceId is the authoritative join and works on every rail. If you can create a link per order, do that instead.

6. Refunds, reversals and the silences#

paid is not final. A card payment can be refunded at any time and reversed (charged back) weeks later. A ledger that treats paid as final books reversed money as revenue forever.

Refunds are dashboard-only in this version. An owner or admin issues one from the payment's row. Giving a buyer's money back is a signing decision, the same class as choosing where a payout lands, and the machine member an API key acts as does not hold that role. The refund arrives on your webhook as checkout_payment.refunded and moves refundedBase on the payment.

Three things that are not announced, and that you should read off the payment rather than wait for:

If you reconcile on a schedule, page GET /links/{linkId}/payments for your live links and compare status and refundedBase with what you hold.

settledAt is null in this version: the money is in your balance at the processor, and we do not see it move from there.

7. If you know Stripe#

What has no equivalent here yet: a test mode for checkout, subscriptions, and an API refund. Each is on the list, and none is pretended.

Then#

• Webhooks: signing, retries, and the events table
• Reconciliation: the feed you recover from
• Errors: every code, including TEST_MODE_UNSUPPORTED
• The API reference under the Checkout tag