Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swiftpay.finance/llms.txt

Use this file to discover all available pages before exploring further.

SwiftPay exposes four integration modes. They are intentionally different in ownership, speed, and customization so you can start quickly and scale without re-architecting.

REST API

Production-ready and server-controlled invoice flow.

x402

HTTP 402 per-request payments for any API endpoint.

Hosted Checkout

UI-complete checkout flow managed by SwiftPay.

Embedded iFrame

In-app payment surface with event callbacks.

​
REST API

Status: Available now. Use this when you want ownership of the payment lifecycle. It is the best default for most integrations because you control request timing, idempotency strategy, invoice metadata, and reconciliation logic.

​
What you build

  1. Create an invoice from your backend.
  2. Persist the returned invoice and map it to your internal order object.
  3. Render amount, token, chain, and expiry to your users.
  4. Listen and act on invoice state changes via polling or webhooks.
  5. Finalize fulfillment only after your backend confirms payment status.

​
Authentication and keys

Get both keys from https://cockpit.swiftpay.finance → Settings (/settings):
  • sk_live_... (server secret key)
  • pk_live_... (publishable key for public/checkout flows)
For private invoice APIs use: 
X-Swift-Key: sk_live_...

​
Example implementation pattern

curl -X POST "https://api.swiftpay.finance/v1/invoices" \
  -H "Content-Type: application/json" \
  -H "X-Swift-Key: sk_live_your_secret_key" \
  -d '{
    "externalRef": "order_8823",
    "amountExpected": 250,
    "token": "USDC",
    "chains": ["ethereum", "polygon", "base"],
    "metadata": {
      "customerEmail": "dev@swiftpay.finance",
      "orderType": "membership"
    }
  }'

{
  "id": "inv_01HABC...",
  "status": "pending",
  "chain": "ethereum",
  "address": "0x4f...9d2",
  "expiresAt": "2026-03-10T12:45:00Z"
}
Store the returned id and externalRef together, then use either:
  • periodic status checks for internal dashboards, or
  • webhook-driven processing for automated order completion.
For the complete request/response contract, see:
Never expose your sk_live_... key in browser code. Keep it server-side only.

​
x402

Status: Available now. Use this when you want to charge per API request rather than per invoice. There is no checkout redirect — the payment happens in the HTTP round-trip itself. This is the right default for AI endpoints, data APIs, and machine-to-machine services.

​
How it works

  1. Register a forwarder in the dashboard (one-time per merchant).
  2. Register each protected route as an endpoint via POST /v1/x402/endpoints.
  3. Add a middleware to your server that implements the two-round 402 gate.

​
The two-round flow

Round 1 — no payment  →  server returns HTTP 402 + PaymentRequirements
Round 2 — X-PAYMENT header  →  server calls SwiftPay settle → serves resource
For the full integration guide, code examples, and idempotency patterns, see the x402 guide.
Your sk_live_* key is required to fetch requirements and settle payments — keep it server-side only.

​
Hosted Checkout

Status: Available now. This is the low-friction mode. You generate invoices with the same REST API, then send users to a SwiftPay-hosted payment URL (https://pay.swiftpay.finance/{invoice_id}). The payment page handles chain/token selection, wallet connections, and payment signing — no frontend work required. Best for:
  • Minimal frontend effort — no custom checkout UI needed
  • Mobile-first experiences — full-screen mobile optimization
  • Email/SMS payments — shareable payment links
  • Marketplace — independent checkout per invoice
  • Link-based flows — QR codes, social sharing, print campaigns
How it works:
  1. Create invoice using REST API
  2. Redirect user to hosted page
  3. User completes payment on SwiftPay’s interface
  4. User returns to your app via callback URL
  5. Webhook notifies your backend
For complete implementation guide, best practices, and examples, see Hosted Checkout Integration.

​
Embedded iFrame

Status: Available now. This path is for teams that need a branded embedded checkout experience without building payment logic from scratch. SwiftPay handles payment orchestration; you control the page layout and surrounding UX. Best for:
  • Seamless checkout — users stay on your domain
  • Custom page layout — full control over surrounding UX
  • Single-page apps — no page redirects
  • Modal checkouts — dialog or overlay
  • White-label — branded payment experience
  • Cart integration — checkout in cart summary page
How it works:
  1. Create invoice on your backend
  2. Embed iframe with invoice ID
  3. User completes payment in iframe
  4. iFrame sends events via postMessage
  5. Handle payment confirmation events
<iframe
  src="https://pay.swiftpay.finance/{invoice_id}?embed=true"
  style="width: 100%; height: 600px; border: none;"
></iframe>

<script>
window.addEventListener("message", (event) => {
  if (event.origin !== "https://pay.swiftpay.finance") return;
  
  if (event.data?.type === "payment.completed") {
    console.log("Payment confirmed", event.data.invoiceId);
  }
});
</script>
For complete implementation guide, event types, security considerations, and React examples, see Embedded iFrame Integration.

​
Comparison Table

FeatureREST APIx402HostediFrame
FlowRedirect + webhook2-round HTTP 402RedirectEmbedded
Checkout UIYou buildNoneSwiftPaySwiftPay
Mobile✅N/A✅ Optimized✅
Custom layout✅——✅
ImplementationMediumMediumLowMedium
Setup time~1 day~1 day~30 min~2 hours
Best forFull controlAPI paywallsFastest launchWhite-label

​
Recommendation by integration goal

  • Invoice payments with full control → REST API
  • Per-request API monetization → x402
  • Launch speed with minimal work → Hosted Checkout
  • Custom checkout experience → Embedded iFrame
  • SDKs for frontend → See SDKs Overview
For implementation details and request payloads, start from the Quickstart.