Melio-Sonar-Token header carries session information that Melio uses as part of processing a request.
Embedding Sonar is required. Partners must embed the Sonar SDK and send the Melio-Sonar-Token header on every request listed in When to embed it. Melio validates your implementation before you go live.
When to embed it
Load the SDK and mint a session on any page where the end user takes an action that leads directly to one of these calls:The session must be minted on the same page, in the same user action, immediately before the write call it’s attached to. A token minted earlier in the flow (for example at login) or on a different page may not be accepted. If a flow doesn’t reach your server until later (a multi-step form saved as a draft), mint the session at the final confirmation step - not at the start of the form.
Publishable key
You receive a publishable key during onboarding. It is safe to embed in client-side code (web or mobile) and is used only to initialize the MelioSonar SDK. It is not a secret and grants no access to the API.How to embed it
1
Load the SDK
Add the SDK script to the page where the sensitive action happens:
2
Mint a session
Create a session right before the user submits the action:
3
Forward the token
Send
session.token as the Melio-Sonar-Token header on the write request that follows that same action:4
Handle failures
An invalid or expired token returns Branch on
400 with error code INVALID_SONAR_TOKEN. Check for that code, mint a fresh session, and retry the request with the new token. Never drop the header and resubmit without it.code, not on the status: other validation errors also return 400, and re-minting won’t fix them.Content Security Policy
The SDK talks to two hosts: it loads fromsonar.melio.com (sonar.staging01.melio.com in sandbox) and mints the session token on a Melio session service under meliopayments.com. If your site sends a Content-Security-Policy header, allow both. Otherwise the browser blocks the token request and createSession rejects with a generic Failed to fetch, with no other error.
createSession fails with Failed to fetch, check the browser console for a CSP violation first.
What happens if you skip it
Omitting the token, or sending an expired or invalid one, can result in otherwise-valid payments being declined. The API won’t reject the request for a missing header, but the payment decision downstream may come back negative. Partners that don’t implement Sonar on the listed requests won’t pass go-live validation.Checklist for partners
- The SDK is embedded and the token is sent on every request in the “When to embed it” table.
- SDK script loaded on every page that leads to one of the listed endpoints.
- The SDK is loaded and the token is sent on both the “add funding source” and the “add delivery method” pages.
- Make Sure the SDK script is loaded in the right environment (sandbox/production)
- Session minted immediately before the write call, on the same page/action, not earlier in the flow.
session.tokenforwarded asMelio-Sonar-Tokenon that call.400 INVALID_SONAR_TOKEN(invalid/expired token) handled by re-minting and retrying, never by dropping the header.- If your site uses a Content-Security-Policy, the Sonar SDK host and
*.meliopayments.comare allowed (see Content Security Policy).