Set up checkout

Get a business account, card payments, an API key and a webhook endpoint ready before your first live payment.

Before you start

An organization that already pays out can start at step 2, because checkout shares its key, webhook endpoint and event feed. A test key skips steps 1 and 2: your sandbox organization is already verified and able to sell by card. Build there first (Environments & sandbox).

Summary

1. Create a business account and verify it (KYB), in the dashboard.
2. Apply for card payments under Checkout.
3. Create an API key and a webhook endpoint under Developers.
4. Check both with GET /checkout/organizations/{orgId}/products.

---

Steps 1 to 4 happen in the dashboard, once. Bank and crypto links need only step 2; card links also need step 3, and until it is done a publish: true create keeps the link as a draft with a publishError.

1. Create a business account

   Sign in at business.avvio.xyz with your work email and a one-time code, and add a passkey if you like. Name your business and choose Create Business Account. This creates your organization, which holds the balance, links, API keys and team. Of the dashboard’s setup tasks, checkout needs Create account and Verify your account.

   Verify the business

   Open Verify and complete business verification (KYB). It asks for the legal entity, its beneficial owners and one control person, the individual who runs the business. Card onboarding verifies exactly that person, so it cannot start until the application names one.

   Status	What it means
   Draft	Not sent yet. Finish and submit it
   Under review	With us. We email you when it is done
   Needs information	We asked for something. The dashboard shows what, and a button to answer
   Approved	Every organization-scoped route opens, including checkout
   Rejected	Contact support

   Until then, checkout routes answer 403 with “This organization must complete business verification before it can accept payments.” Our approval counts as verified, and so does the card processor reporting the business able to charge. Bank and stablecoin payments go live on approval; cards need step 2.

2. Enable card payments

   Open Checkout and choose Accept card payments. Anyone on your team can file the application. Cards are in pilot, so if you cannot have them yet, the panel says so in place of the button.

   Cards are processed by Whop, which verifies the control person your KYB names. The consent screen lists what is shared: the business’s registered name, address, tax ID, structure and activity, and the control person’s name, date of birth, phone, home address, tax number, ID photos and selfie. Tick both boxes. If you are not the control person, you attest that you may consent for them. Consent is recorded once.

   The card account opens in about a minute. If the ID photos and selfie on your verification were accepted, the identity check runs from them and nobody is contacted. Otherwise the page says what to fix, and the control person does a two-minute ID and selfie check on their phone. The dashboard shows the link to send them, and Whop emails the account owner too.

   Switch	Turns on when	What it lets you do
   Card payments	The card account is open	Publish links with methods: [{ "kind": "card" }]; buyers pay by card, Apple Pay and Google Pay
   Withdrawals	The identity check passes	Move card money to your bank from Checkout → Balance

   Card money waits in your card balance until withdrawals are on. Buyers see WHOP* and your business name on their statement; edit the descriptor in the same panel.

   A card link published before this is done gets a 201 but stays a draft with a publishError (Accept a checkout payment). Finish onboarding, then call POST /checkout/organizations/{orgId}/links/{linkId}/publish. Bank and crypto links skip this step.

3. Create an API key and a webhook endpoint

   Both live under Developers, which owners, admins and operators can open.

   The API key

   Choose Create API key and fill in four fields:

   Field	Pick
   Name	Where it will live (orders-service), so a leaked key is traceable
   Permission	Transact to create products and links. Read-only gets 403 INSUFFICIENT_SCOPE on any write. Refunds need a separate scope (Refund a payment)
   Expiry	One year by default, two at most
   Allowed IP addresses	Optional. Your servers’ egress addresses

   Caution

   The complete key is shown once and we store only a hash. Anyone holding it can act as your business, so keep it in a secrets vault and never in a browser bundle, app or ticket. If it leaks, revoke it and issue a successor (Authentication).

   export AVVIO_API_KEY=avvio_…
   export AVVIO_ORG_ID=cmsx…        # your organization id, a cuid
   export AVVIO_BASE_URL=https://api.avvio.xyz/business/api/v1

   Use the opaque cmsx… organization id shown on the same page, not an org_-prefixed alias.

   The webhook endpoint

   Open the Webhooks tab and choose Add endpoint:

   1. URL: https only. In the sandbox, use a public HTTPS tunnel such as cloudflared or ngrok.
   2. Events: payout types are pre-selected and checkout types are not. An endpoint receives only the checkout events it names, so tick the checkout_payment.* types you handle.
   3. Signing secret: shown once, as whsec_…. Store it beside the API key and verify with it (Receive and verify webhooks).

   Endpoints are managed only in the dashboard; a key can list them read-only at GET /organizations/{organizationId}/webhook-endpoints (Webhooks).

4. Check the setup

   Make one read before you write anything:

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

   A new organization gets []. A 403 with the verification message means step 1 is not finished; a 401 means the key is wrong or revoked.

   @avvio/payments covers most of partner-checkout.openapi.yaml: use 0.8.0 or newer for refunds and 0.7.0 or newer for updateCheckoutLink. Publishing a draft, deleting a draft, and reading, updating or archiving a product have no SDK method yet, so call those over HTTP. From an API key, every POST, PATCH and DELETE needs an Idempotency-Key.

   Next, accept a checkout payment.