Multiple Session Support

Multiple Session support lets a single API client use more than one pricing and trading configuration, called a session, under the same client ID and API credentials.

In this guide we will go through what a session is, when you might want to use more than one, and how to send session-specific requests to the API.

What is a session?

A session holds the commercial configuration StoneX applies to your quotes and trades. This includes:

• Margin type and margin levels
• Rate expiry (how long a quote stays valid)
• Value date behaviour
• Whether trading is enabled for quotes

Every API client has a default session. If you have been using the StoneX Payments API before this feature was released, all of your requests have been using your default session, and they will continue to do so.

When should I use multiple sessions?

Multiple sessions are useful if you need different pricing setups but want to keep a single relationship with StoneX. For example:

• You operate several business units, each with its own agreed margin or limits.
• You provide payments to your own commercial clients and need a different configuration for each.
• You want separate value date or rate expiry behaviour for different payment flows.

With multiple sessions, credit lines, limits and reporting stay consolidated under one client ID, rather than being split across separate client accounts.

Step 1: Request your sessions

Sessions are set up and maintained by StoneX. Contact your account management team with the configuration you need for each session. Once set up, we will share a Session ID for each session.

Step 2: Send the X-Session-Id header

To use a specific session, add the X-Session-Id header to your request. The header is supported on the following endpoints:

If you don't send the header, or send it with an empty value, the request will use your default session.

Step 3: Request a quote on a session

Pass the Session ID in the X-Session-Id header when requesting your quote. The quote you receive will be priced using that session's configuration.

curl --request POST \
     --url https://api.sandbox.payments.stonex.com/api/v1/quote \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --header 'X-Session-Id: <your_session_id>' \
     --data '{
       "sellCurrency": "USD",
       "buyCurrency": "EUR",
       "sellAmount": 10000
     }'

Step 4: Book the trade on the same session

Using the quoteId received in the previous step, book the trade and send the same X-Session-Id header.

curl --request POST \
     --url https://api.sandbox.payments.stonex.com/api/v1/trade \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --header 'X-Session-Id: <your_session_id>' \
     --data '{
       "quoteId": "<quote_id>"
     }'

Once the trade is booked, you can continue with Add delivery instructions to a trade and Get status as normal. These endpoints don't need the X-Session-Id header.

How session settings behave

• Each session uses its own configuration. Two sessions with different rate expiry, value date or margin settings will each return their own behaviour.
• Sessions are independent. If one session is disabled, your other sessions are not affected.
• Quote-only sessions. A session can be set up so that quotes are allowed but trading is not. Quote requests on that session will succeed, but trade booking will be rejected.
• Margin fallback. If a session doesn't have its own margin configured, we apply your client-level margin. If no margin is configured at any level, you will receive the existing TRD00011 Configuration missing error.
• Audit trail. The session used is recorded against every quote and trade, so our support team can see which session a trade was booked under.

Error handling

See Error Codes for the full list of errors.

Things to know

• One set of credentials. All sessions share the same API credentials and authentication token.
• Webhooks are shared. Webhooks are currently configured at client level and apply to all of your sessions.
• Client-level settings still apply. Settings such as fees and available currencies are configured at client level and apply to every session.
• Sessions are managed by StoneX. You can't create or edit sessions via the API. Contact your account management team for any changes.

FAQs

Do I need to change anything if I only have one session?
No. If you don't send the X-Session-Id header, your requests use your default session and behave exactly as before.

Can I use multiple sessions in the sandbox?
Yes. Contact your account management team to set up test sessions in the sandbox environment.

Can I use X-Session-Id on the Instruct or Status endpoints?
These endpoints work from the fxId of a booked trade, which already carries its session. You don't need to send the header.