Create a checkout session

Before mounting <swirepay-checkout>, your backend must create a checkout session by calling Swirepay's checkout-session API. This call requires your secret API key and must be made server-side. Never expose the secret key in browser JavaScript or ship it with your frontend bundle.

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-api-key>

The checkout session controls what the SDK is allowed to collect and where it is allowed to run. Use either:

payment — initialize a direct payment.
order — initialize payment for an inventory order.

The checkout-session API also supports other scopes, but this guide covers only payment and order.

Request fields

Field	Required	Description
`scope`	Yes	Use `payment` for a direct payment or `order` for an inventory order checkout.
`acceptedDomain`	Yes	The HTTPS origin where the SDK will be hosted, for example `https://checkout.example.com`. It must be a valid HTTPS origin.
`amount`	Payment: Yes / Order: No	Amount in the smallest currency unit. For example, `1001` represents USD 10.01. Required for `payment`; not required for `order`.
`currency`	Payment: Yes	Currency code such as `USD`. Required together with `amount` for `payment`.
`paymentType`	No	Restricts the SDK to only the specified payment methods. If omitted, the SDK uses all payment types enabled for the corresponding Swirepay account.
`inventoryOrder`	Order: Yes	Inventory-order configuration. Required when `scope` is `order`.

Supported paymentType values:

CARD, ACH_LEGACY, ZIP_ACH, X_ACH, RAPID_ACH, PAYPAL_WALLET,
GOOGLE_PAY_US, APPLE_PAY_US, INSTANT_ACH, SWIFT_ACH

Include whichever of these you want available in the checkout — see the method guides (Card, ACH, Apple Pay, PayPal, Google Pay) for the exact value(s) each payment method needs. You can combine multiple values to expose several payment methods in the same checkout.

Direct payment session (`scope: payment`)

Use payment when you want to collect a standalone payment directly through the SDK.

curl --location 'https://api.swirepay.com/v3/checkout-session' \
  --header 'x-api-key: <your-secret-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "payment",
    "acceptedDomain": "https://checkout.example.com",
    "amount": 1001,
    "currency": "USD",
    "paymentType": ["CARD", "ACH_LEGACY"]
  }'

For payment scope:

scope must be payment.
amount and currency are required.
acceptedDomain must be the valid HTTPS origin where <swirepay-checkout> is embedded.
paymentType is optional. When provided, only those payment methods are exposed by the SDK. When omitted, all payment types enabled for the account are eligible to be shown.

Example response:

{
  "message": "OK",
  "entity": {
    "paymentSessionGid": "paymentsession-abb0ddcc650a4211931fd8b031cfa851",
    "scope": "payment",
    "encryption": "eyJjIjoiY3NfNDE0NmY3MGEtOWEwMy00MTJmLTgwYTAtYjI4MTExMDRjZjg3IiwiayI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXBNN2xNQzg1Qi9aRVhvWFRTdHFjSzdsalpaN0JzQnJJT1NrUUJpWXhIMkp0UWpMZktQNVFqalY5aG5YQW01YktGWis2U2ZnZEcyTTlub2xQM1U3cGJBPT0iLCJpIjoiOWFjZTdhYWQtYmQyNC00NzJjLWE2YmItNmZmOTE3NmQyYTZiIiwiZSI6MTc4Nzc5NzUxODA0Nn0=",
    "expires_at": 1787797518046
  },
  "responseCode": 200,
  "status": "SUCCESS"
}

Use entity.encryption as the SDK's secureToken. Record entity.paymentSessionGid in your backend so you can reconcile the payment result with your own order or transaction record and with Swirepay webhook events.

Inventory order session (`scope: order`)

Use order when the checkout is tied to a Swirepay inventory order. For this scope, the inventoryOrder object is required, and amount is not required.

The following fields are mandatory for an order checkout:

inventoryOrder
inventoryOrder.shopGid
inventoryOrder.inventoryOrderLineItems

Inventory order is currently supported for Card and ACH only — any wallet paymentType you include alongside an order-scope session is silently dropped from the checkout.

Example:

curl --location 'https://api.swirepay.com/v3/checkout-session' \
  --header 'x-api-key: <your-secret-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "order",
    "currency": "USD",
    "paymentType": [
      "GOOGLE_PAY_US",
      "APPLE_PAY_US",
      "PAYPAL_WALLET",
      "CARD",
      "ACH_LEGACY",
      "X_ACH",
      "ZIP_ACH",
      "RAPID_ACH"
    ],
    "inventoryOrder": {
      "shopGid": "shop-c58a9fc661ae43eb955f42529641baf2",
      "redirectUrl": "https://www.google.com",
      "orderType": "WEB",
      "mode": "ONLINE_ORDER",
      "inventoryOrderLineItems": [
        {
          "itemGid": "item-4fde02cbb9bd498ba884c8e81ced8084",
          "quantity": 2
        }
      ]
    },
    "acceptedDomain": "https://checkout.example.com"
  }'

Example response:

{
  "message": "OK",
  "entity": {
    "inventoryOrderGid": "inventoryorder-8df4f67319fb4ed29f4c54c79dffd0b7",
    "scope": "order",
    "encryption": "eyJjIjoiY3NfNjg5ZWIzNDItZTkwOS00ODkxLTliZDktMzFkYjM1NmVmMzkyIiwiayI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRWpTM01XVWc2Y2VtcW0xOEJWVzE0QnRFSk95ai9KUmp1Q1BVblAyTU1tQ0dWNDdvUFpwOGJRRmNoV1FGRksycEd1WmJxV0FWK2FPTWJtM0dKQmtPSDd3PT0iLCJpIjoiZGRlYjI2MmEtNzEzMS00OTdhLTgxM2EtNjIzMzU4YmM2ZTEyIiwiZSI6MTc4Nzc5ODA2Njk3OH0=",
    "expires_at": 1787798066978
  },
  "responseCode": 200,
  "status": "SUCCESS"
}

For an order checkout, use entity.encryption as the SDK's secureToken. The response identifies the created inventory order through entity.inventoryOrderGid.

Checkout-session validation errors

The checkout-session API validates the scope-specific requirements before creating the session. Common errors include the following.

Invalid `acceptedDomain`

Returned when acceptedDomain is not a valid HTTPS origin.

{
  "dateTime": 1787797277795,
  "status": "036c04152ad189886ebae5dfc27c0e1e:FAILED",
  "responseCode": 412,
  "message": "acceptedDomain must be a valid HTTPS origin",
  "messageCode": "5545",
  "actionRequired": null,
  "exceptionReason": "acceptedDomain must be a valid HTTPS origin"
}

Missing `scope`

{
  "dateTime": 1787797332155,
  "status": "717d8eab579bd38d2b292dd70ab0ddf6:FAILED",
  "responseCode": 400,
  "message": "Request validation failed - scope:must not be null",
  "messageCode": "5008",
  "actionRequired": null,
  "exceptionReason": "scope is invalid"
}

Missing `amount` or `currency` for payment scope

{
  "dateTime": 1787797349626,
  "status": "59e462b9794821aa6918be542db5c327:FAILED",
  "responseCode": 412,
  "message": "amount and currency are required for PAYMENT checkout sessions",
  "messageCode": "5331",
  "actionRequired": null,
  "exceptionReason": "amount and currency are required for PAYMENT checkout sessions"
}

Missing `inventoryOrder` for order scope

{
  "dateTime": 1787797378487,
  "status": "7974d077efedb71f4fdc8b15cd2d8971:FAILED",
  "responseCode": 412,
  "message": "inventoryOrder is required for ORDER checkout sessions",
  "messageCode": "5331",
  "actionRequired": null,
  "exceptionReason": "inventoryOrder is required for ORDER checkout sessions"
}

Backend integration example

Your application backend can wrap the Swirepay checkout-session API and return only the session values your frontend needs:

// server.js — never expose SWIREPAY_SECRET_KEY to the browser
app.post('/api/swirepay/checkout-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: 'payment',
      amount: req.body.amountInCents,
      currency: 'USD',
      paymentType: ['CARD'],
      acceptedDomain: 'https://checkout.example.com'
    })
  });

  const result = await response.json();

  if (!response.ok) {
    return res.status(result.responseCode || response.status).json(result);
  }

  // Record result.entity.paymentSessionGid against your own order/customer record here
  // before responding to the frontend.

  res.json({
    secureToken: result.entity.encryption,
    paymentSessionGid: result.entity.paymentSessionGid,
    expiresAt: result.entity.expires_at
  });
});

The frontend should receive the secureToken from your backend, then assign it to the secureToken property on <swirepay-checkout>. The Swirepay secret API key must never be sent to the browser.

API reference

Full request/response schemas, including the order-scope and error-response shapes, are also available as a generated reference: Create a checkout session. The same physical endpoint also has a scope: "transfer" variant used by <swirepay-contact-onboarding> and <swirepay-transfer-center> — see the Transfer Center API's own Checkout Session reference for that variant.

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 — then pick your payment method's guide for the method-specific details.

Endpoint​

Request fields​

Direct payment session (scope: payment)​

Inventory order session (scope: order)​

Checkout-session validation errors​

Invalid acceptedDomain​

Missing scope​

Missing amount or currency for payment scope​

Missing inventoryOrder for order scope​

Backend integration example​

API reference​

Next steps​