Skip to main content

Create a checkout session

The element needs a secure-token before it will render anything. This token is minted by calling the checkout-session API with your secret key — and because that key can create sessions on your account, this call must happen on your server, never in browser JavaScript. Your backend hands the browser only the resulting token.

This page covers minting the session. For everything downstream of that — mounting the element, props, callbacks, theming — see SDK setup & flow.

Endpoint​

POST https://api.swirepay.com/v3/checkout-session
Content-Type: application/json
x-api-key: <your secret key>

{
  "scope": "transfer",
  "acceptedDomain": "https://your-site.example.com"
}
  • scope must be "transfer" for contact onboarding (as opposed to "payment"/"order", used for <swirepay-checkout>, or "transfer" with toContactGid set, used for <swirepay-transfer-center>).
  • acceptedDomain is the origin of the page that will embed the widget.

Response​

{
  "entity": {
    "scope": "transfer",
    "encryption": "eyJjIjoiLi4uIn0=..."
  }
}

entity.encryption is a compact, base64-encoded token — that string is the value you hand to the element's secureToken property (not entity as a whole). It is a plain JSON blob, not a JWT — the widget parses it directly, so this value must come only from your own server's response, never be constructed client-side.

Backend integration example​

// server.js (your backend — never expose SWIREPAY_SECRET_KEY to the browser)
app.post('/api/swirepay/onboarding-token', async (req, res) => {
  const response = await fetch('https://api.swirepay.com/v3/checkout-session', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.SWIREPAY_SECRET_KEY
    },
    body: JSON.stringify({
      scope: 'transfer',
      acceptedDomain: 'https://your-site.example.com'
    })
  });
  const { entity } = await response.json();
  res.json({ secureToken: entity.encryption });
});

API reference​

Full request/response schemas for the contactOnboarding request/response variant are available as a generated reference: Create a checkout session (transfer scope). That page also documents the <swirepay-transfer-center> variant of this same endpoint (the one with toContactGid set) side by side, so you can see exactly what differs. The payment/order variant used by <swirepay-checkout> has its own reference page.

Next steps​

Once you can mint a session, move on to SDK setup & flow for loading the SDK, mounting the element, the full props reference, and the error/success payload shapes.

On this page