Create a checkout session (`scope: "transfer"`)

Before mounting <swirepay-transfer-center>, your backend must create a checkout session by calling Swirepay's checkout-session API with scope: "transfer". 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, the Send Money form, 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>

Request fields

Field	Required	Description
`scope`	Yes	Must be `"transfer"`.
`acceptedDomain`	Yes	The HTTPS origin where the SDK will be hosted, for example `https://checkout.example.com`. It must be a valid HTTPS origin.
`toContactGid`	Yes	The gid of the fixed recipient contact this transfer session moves money to. The shopper cannot choose an arbitrary recipient — only among this contact's own funding-source accounts (see SDK setup & flow → Funding source selection).
`currency`	Yes	Currency code such as `USD`.
`senderContactGid`	No	When set, scopes the "from" side to this specific contact's own funding-source accounts (instead of the merchant's own funding sources) and requires the shopper to confirm a one-time code before the transfer completes — see SDK setup & flow → Sender-scoped OTP confirmation.
`transferType`	No	If not set then all available types are selected by default. Restricts which transfer-mode chips render in the widget. Supported values: `ACH`, `RAPID_ACH`, `RTP`. If omitted, or if the account's default transfer type isn't in this list, no chip is preselected — see SDK setup & flow → The Send Money form.

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": "transfer",
    "acceptedDomain": "https://checkout.example.com",
    "toContactGid": "contact-5bf93de6e95a4933986e11297e09f6a1",
    "currency": "USD",
    "senderContactGid": "contact-2378de7dcdd4483fb986acbf551aa760",
    "transferType": ["ACH", "RTP"]
  }'

Example response:

{
    "message": "OK",
    "entity": {
        "transferSessionGid": "transfersession-79f52d648ecf482c856789456f0c9aea",
        "scope": "transfer",
        "encryption": "eyJjIjoiY3NfYTc4YTgwMTgtNWM0NC00M2I1LTg0NmQtOWI0NjFmMjYxZTNmIiwiayI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUfghjnbvfmtYTkl2bFZoWmN1T3FwVFBzMUVRWjgvS0VGeXR6cWtHeDNWRVRoMmp2WHJETjA4SkxlQWV1M2l5ajNHTG1Xb2s2RWtEenhjaUNCYmlSdkdhUjlBPT0iLCJpIjoiMWFhOWVlZGYtY2IzNC00OGUxLTgxMGYtMGE0MTIwOGE0OTI4IiwiZSI6MTc4ODk0MDI5MDg1NX0=",
        "transferType": ["ACH", "RTP"],
        "expires_at": 1788940290855
    },
    "responseCode": 200,
    "status": "SUCCESS"
}

Use entity.encryption — and only that field, not the full response entity — as the SDK's secureToken. It's already a compact, base64-encoded token; the widget decodes it internally. Record entity.transferSessionGid in your backend so you can reconcile the transfer result later.

`toContactGid` vs. props on the element

toContactGid is a field you send once, when minting the session — it is never a prop or attribute on <swirepay-transfer-center> itself. The widget resolves the actual recipient contact details itself, server-side, from the transfer session your toContactGid created. There is no way to change the recipient after the session is minted short of minting a new one.

The same applies to senderContactGid and transferType: both are mint-time-only. Changing either means creating a brand-new checkout session (a fresh POST /v3/checkout-session call) and reassigning the element's secureToken to the new session's token — not toggling some other client-side flag.

API reference

Full request/response schemas for the transferCenter request/response variant (the one with toContactGid set) are available as a generated reference: Create a checkout session (transfer scope). That page also documents the <swirepay-contact-onboarding> variant of this same endpoint 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 Send Money form, sender-scoped OTP confirmation, and webhook integration.

Endpoint​

Request fields​

Example​

toContactGid vs. props on the element​

API reference​