Checkout Integration Guide
This guide covers everything you need to know about integrating SwiftPay checkout into your application.
How It Works
Create Session
Your server creates a checkout session via the API
Redirect Customer
Redirect the customer to the SwiftPay hosted checkout page
Customer Pays
Customer enters payment details and completes payment
Handle Result
Customer is redirected back to your site; webhook confirms payment
Creating a Checkout Session
Basic Example
const session = await fetch("https://api.swiftpay.cx/api/checkout/sessions", {
method: "POST",
headers: {
Authorization: "Bearer mp_live_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
name: "Product Name",
price: 29.99,
quantity: 1,
description: "Product description",
imageUrl: "https://example.com/product.jpg",
},
],
customer: {
email: "[email protected]",
},
urls: {
success: "https://yoursite.com/success?session_id={SESSION_ID}",
cancel: "https://yoursite.com/cancel",
failure: "https://yoursite.com/failure",
},
}),
});
Request Parameters
List of items in the checkout.
Product name (max 255 characters)
Unit price in dollars (e.g., 29.99)
Product description (max 1000 characters)
Redirect URLs after checkout
Redirect URL after successful payment. Use {SESSION_ID} placeholder.
Redirect URL if customer cancels
Redirect URL if payment fails
Order description for your records
Whether to collect shipping address
Custom metadata for your records
value
string | number | boolean
required
Metadata value
Checkout URL
After creating a session, redirect the customer to:
https://app.swiftpay.cx/checkout/{session_id}
// Using Next.js redirect
import { redirect } from 'next/navigation';
export async function createCheckout(formData) {
const session = await createCheckoutSession(formData);
redirect(`https://app.swiftpay.cx/checkout/${session.id}`);
}
Handling the Result
Success Redirect
When payment succeeds, the customer is redirected to your success URL:
https://yoursite.com/success?session_id=sess_abc123
Never rely solely on the redirect to confirm payment. Always verify via
webhook or API.
Verify Payment Status
// Verify the payment was successful
const response = await fetch(
`https://api.swiftpay.cx/api/checkout/sessions/${sessionId}`,
{
headers: { Authorization: "Bearer mp_live_your_api_key" },
}
);
const session = await response.json();
if (session.data.status === "completed") {
// Payment confirmed - fulfill the order
}
Session Statuses
| Status | Description |
|---|
pending | Session created, awaiting payment |
processing | Payment is being processed |
completed | Payment successful |
failed | Payment failed |
expired | Session expired (after 24 hours) |
Collecting Shipping Address
Set askShipping: true to collect the customer’s shipping address:
const session = await createSession({
items: [...],
customer: { email: '[email protected]' },
askShipping: true,
urls: { ... }
});
{
"shippingAddressLine1": "123 Main St",
"shippingCity": "San Francisco",
"shippingState": "CA",
"shippingPostalCode": "94102",
"shippingCountry": "US"
}
const session = await createSession({
items: [...],
customer: { email: '[email protected]' },
metadata: [
{ key: 'order_id', value: 'ORD-12345' },
{ key: 'customer_id', value: 'cust_abc123' },
{ key: 'subscription', value: true }
],
urls: { ... }
});
Webhook Integration
For production, always use webhooks to confirm payments:
// Your webhook endpoint
app.post("/webhooks/swiftpay", async (req, res) => {
const signature = req.headers["x-webhook-signature"];
// Verify signature
if (!verifySignature(req.body, signature, webhookSecret)) {
return res.status(401).send("Invalid signature");
}
const event = req.body;
if (event.eventType === "checkout.succeeded") {
const sessionId = event.payload.sessionId;
// Fulfill the order
}
res.status(200).send("OK");
});
Best Practices
Always Use Webhooks
Don’t rely on redirects alone. Webhooks ensure you never miss a payment.
Store Session IDs
Save the session ID with your order for easy reference and debugging.
Use Metadata
Link sessions to your internal orders using metadata.
Handle All Statuses
Build UI for pending, completed, and failed states.
