Skip to main content
SwiftPay exposes three 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.

Hosted Checkout

UI-complete checkout flow managed by SwiftPay. (coming soon)

Embedded iFrame

In-app payment surface with event callbacks. (coming soon)

​
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.

​
Hosted Checkout

Status: Coming soon. This is the low-friction mode. You generate invoices with the same REST API, then send users to a SwiftPay-hosted payment URL. The product goal is to remove frontend complexity while preserving API-side control.

​
How it will work

  • Create invoice using REST.
  • Redirect user to a hosted page derived from invoice context.
  • User pays on-chain in a dedicated SwiftPay interface.
  • Callback/return path and webhook still drive final order state on your backend.
Planned shape: 
https://pay.swiftpay.finance/{invoice_id}
Use this mode if your team wants to launch quickest with minimal UI ownership.

​
Embedded iFrame

Status: Coming soon. This path is for teams that need a branded embedded checkout experience without building payment logic from scratch. SwiftPay handles flow orchestration; you control layout and user journey wrapping.

​
Planned integration contract

<iframe
  src="https://pay.swiftpay.finance/embed/{invoice_id}"
  width="420"
  height="560"
  frameborder="0"
  allow="clipboard-write"
  title="SwiftPay checkout"
></iframe>

window.addEventListener("message", (event) => {
  if (event.data?.type === "payment.confirmed") {
    console.log("invoice paid", event.data.invoice_id)
  }
})

​
Security guardrails

  • Keep secret-key usage strictly on the server.
  • Restrict allowed iframe origins in your CSP/embedding policy.
  • Treat browser messages as UX hints; finalize anything important through backend verification.

​
Recommendation by integration goal

  • You need reliability and full control today → REST API
  • You need launch speed tomorrow → start with REST API, then switch user journey to Hosted Checkout if needed
  • You need a white-label payment surface → plan for Embedded iFrame after GA
For implementation details and request payloads, start from the Quickstart.