Authentication
Send your secret key from your server: Authorization: Bearer al_sk_test_…. Test keys only see sandbox data; live keys only live data. Never use secret keys in browsers or mobile apps.
Idempotency, errors, limits
Send Idempotency-Key on POSTs (required for refunds, captures and cancels). Errors return { error: { type, code, message, request_id } }. Rate limit: 100 requests / 10 s per key (HTTP 429 with Retry-After).
Webhooks
Verify x-platform-signature: t=<unix>,v1=<hex>: compute HMAC-SHA256 with your endpoint secret over <t>.<raw body>, compare in constant time and reject timestamps older than 5 minutes. Events may arrive more than once or out of order, dedupe on id. Fulfill orders from checkout.session.completed / payment.succeeded, never from browser redirects.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(secret: string, header: string, rawBody: string) {
const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header) ?? [];
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Event types: payment.succeeded, payment.failed, payment.processing, payment.requires_action, payment.canceled, payment.refunded, payment.disputed, refund.updated, checkout.session.completed, checkout.session.expired, invoice.finalized, invoice.paid, invoice.overdue, invoice.voided, account.capabilities_updated, subscription.created, subscription.updated, subscription.canceled, connected_account.updated, transfer.paid, transfer.reversed
post/v1/checkout/sessions· Create a checkout session
Body
currency* | string |
line_items | object[] |
amount | integer |
description | string |
mode | "payment" | "subscription" |
price | string |
tax_amount | integer |
shipping_amount | integer |
discount_amount | integer |
customer | string |
customer_email | string |
collect_billing_address | boolean |
collect_shipping_address | boolean |
success_url | string |
cancel_url | string |
expires_in_minutes | integer |
merchant_reference | string |
metadata | object |
allowed_origins | string[] |
template | string |
on_behalf_of | string |
commission_amount | integer |
get/v1/checkout/sessions· List checkout sessions
Parameters
limit (query)starting_after (query)status (query)
get/v1/checkout/sessions/{id}· Retrieve a checkout session
post/v1/checkout/sessions/{id}/expire· Expire an open checkout session
Parameters
id (path, required)Idempotency-Key (header)
get/v1/payments· List payments
Parameters
limit (query)starting_after (query)status (query)currency (query)payment_method (query)customer (query)on_behalf_of (query)created_gte (query)created_lt (query)
get/v1/payments/{id}· Retrieve a payment
post/v1/payments/{id}/refunds· Refund a payment (full or partial)
Always processed through the provider connection that created the payment. Final status arrives via refund.updated / payment.refunded events.
Parameters
id (path, required)Idempotency-Key (header, required)
Body
amount | integer |
reason | "duplicate" | "fraudulent" | "requested_by_customer" |
refund_application_fee | boolean |
metadata | object |
get/v1/payments/{id}/refunds· List refunds for a payment
post/v1/payments/{id}/capture· Capture an authorized payment
Parameters
id (path, required)Idempotency-Key (header, required)
post/v1/payments/{id}/cancel· Cancel an unconfirmed or authorized payment
Parameters
id (path, required)Idempotency-Key (header, required)
post/v1/agent_payments· Charge an AI agent's payment token
Pass the scoped, single-seller payment token an AI agent obtained from the buyer (a shared payment token, spt_…). The payment is created and confirmed on your provider account through the same pipeline as every other payment. Agent payments must be turned on in Settings → AI agent payments.
Parameters
Idempotency-Key (header, required)
Body
shared_payment_token* | string |
amount* | integer |
currency* | string |
description | string |
merchant_reference | string |
customer_email | string |
metadata | object |
agent | object |
get/v1/agent_payments/config· Agent payment configuration to share with agents
Whether agent payments are on, the network profile ID agents must scope tokens to, and your per-payment cap.
post/v1/accounts· Create a connected account
A seller on your marketplace or a user of your platform. We create their provider account and return a provider-hosted onboarding link to send them. Your own account must be able to take payments, because commissions are paid into it.
Body
display_name* | string |
email* | string |
country* | string |
default_currency* | string |
business_type | "individual" | "company" | "non_profit" |
external_reference | string |
commission_rate_bps | integer |
metadata | object |
return_url | string |
refresh_url | string |
get/v1/accounts· List connected accounts
Parameters
limit (query)starting_after (query)
get/v1/accounts/{id}· Retrieve a connected account
post/v1/accounts/{id}/onboarding_links· Create a provider onboarding link
Links expire after a few minutes; create a new one each time you send it.
Body
return_url | string |
refresh_url | string |
get/v1/transfers· List commission transfers
Commissions from connected-account payments, transferred to your own provider account.
Parameters
limit (query)connected_account (query)
get/v1/refunds/{id}· Retrieve a refund
post/v1/payment-links· Create a payment link
Body
title* | string |
description | string |
image_url | string |
currency* | string |
amount_type | "fixed" | "customer_chooses" |
amount | integer |
min_amount | integer |
max_amount | integer |
recurring | object |
expires_at | integer |
max_uses | integer |
collect_billing_address | boolean |
collect_shipping_address | boolean |
success_url | string |
cancel_url | string |
get/v1/payment-links· List payment links
get/v1/payment-links/{id}· Retrieve a payment link
post/v1/payment-links/{id}· Enable or disable a payment link
Parameters
id (path, required)Idempotency-Key (header)
post/v1/invoices· Create a draft invoice
Body
customer* | string |
currency* | string |
items* | object[] |
discount_amount | integer |
due_date* | integer |
memo | string |
footer | string |
get/v1/invoices· List invoices
Parameters
status (query)customer (query)
get/v1/invoices/{id}· Retrieve an invoice
post/v1/invoices/{id}/finalize· Finalize a draft invoice
Parameters
id (path, required)Idempotency-Key (header)
post/v1/invoices/{id}/send· Send an invoice (finalizes drafts)
Parameters
id (path, required)Idempotency-Key (header)
post/v1/invoices/{id}/void· Void an invoice
Parameters
id (path, required)Idempotency-Key (header)
post/v1/invoices/{id}/mark-uncollectible· Mark an invoice uncollectible
Parameters
id (path, required)Idempotency-Key (header)
post/v1/customers· Create a customer
Body
email | string |
name | string |
phone | string |
billing_address | object |
shipping_address | object |
metadata | object |
get/v1/customers· List customers
Parameters
limit (query)starting_after (query)email (query)
get/v1/customers/{id}· Retrieve a customer
post/v1/customers/{id}· Update a customer
Parameters
id (path, required)Idempotency-Key (header)
Body
email | string |
name | string |
phone | string |
billing_address | object |
shipping_address | object |
metadata | object |
post/v1/products· Create a product with a price (one-time or recurring)
Body
name* | string |
description | string |
image_url | string |
price* | object |
get/v1/products· List products and prices
get/v1/subscriptions· List customer subscriptions
post/v1/subscriptions/{id}/cancel· Cancel a subscription
Parameters
id (path, required)Idempotency-Key (header)
get/v1/merchant/account· Retrieve your account
get/v1/merchant/capabilities· Provider-reported processing capabilities
post/v1/developer/webhooks· Create a webhook endpoint (secret returned once)
Body
url* | string |
description | string |
events* | "payment.succeeded" | "payment.failed" | "payment.processing" | "payment.requires_action" | "payment.canceled" | "payment.refunded" | "payment.disputed" | "refund.updated" | "checkout.session.completed" | "checkout.session.expired" | "invoice.finalized" | "invoice.paid" | "invoice.overdue" | "invoice.voided" | "account.capabilities_updated" | "subscription.created" | "subscription.updated" | "subscription.canceled" | "connected_account.updated" | "transfer.paid" | "transfer.reversed" | string[] |
get/v1/developer/webhooks· List webhook endpoints
get/v1/developer/webhooks/{id}· Retrieve a webhook endpoint
post/v1/developer/webhooks/{id}· Enable/disable a webhook endpoint
Parameters
id (path, required)Idempotency-Key (header)
get/v1/events· List events