GoCardless Components for Partners#

If you're integrating GoCardless Components on behalf of multiple merchant organisations rather than a single merchant integrating for itself, session tokens and creditor scoping both need extra care. Each merchant you manage is a separate GoCardless organisation, and both the session token you mint and the bootstrap data you request are scoped to exactly one organisation at a time. There are no "partner-level" credentials that reach across every merchant you manage.

This guide assumes each merchant has already given you an API access token. It builds on GoCardless Components — read that first for the frontend setup and public token flow.

1. One access token per merchant#

Each merchant you manage issues you their own API access token, scoped to their organisation only — not one token that spans every merchant you manage. If you manage 5 merchants, you'll need to hold 5 access tokens, each usable only for its own organisation. Everything downstream — session tokens, creditor scoping — inherits from whichever access token you use to make the request.

2. Minting a session token per merchant#

POST /session_tokens mints a session token from the access token in your Authorization header. The token it returns is scoped to that access token's organisation only.

POST /session_tokens HTTP/1.1
Authorization: Bearer <merchant_specific_access_token>
Content-Type: application/json
 
{
  "session_tokens": {
    "policies": ["ui_components"]
  }
}

HTTP/1.1 201
Content-Type: application/json
 
{
  "session_tokens": {
    "id": "SESH00001078YT4H",
    "token": "sesh_live_mdhBfRflA-uuR9ptHN8Q94HOoRqIiMx7yAbII02Q"
  }
}

Before you can mint one for a merchant, your access token for that merchant needs the ui_components capability granted (only the ui_components policy is supported during Early Access).

3. Creditor validation: partners vs. a single merchant#

A single-merchant integration usually never needs to set a creditor ID, since the organisation only has one creditor.

Merchants you manage as a partner are often different: an organisation can have more than one creditor underneath it. Pass that merchant's creditor ID when you initialise the Component and the SDK scopes the checkout to that creditor for you. Do this by default for every partner-managed merchant — omitting it falls back to resolving at the organisation level, which is only safe when the merchant has a single creditor.

Every creditor ID you pass must belong to the same organisation as the access token that minted the session token.

4. Putting it all together#

For each checkout:

1. Look up the API access token the merchant gave you for the merchant the payer is checking out with.
2. On your backend, POST /session_tokens with that access token to mint a session token scoped to that merchant's organisation.
3. Pass the session token to the frontend and initialise the Component with it, along with that merchant's creditor ID (or omit it for the default organisation-level creditor resolution).
4. Mount the Billing Component as normal — see GoCardless Components for the frontend setup.

What's next?#