Skip to main content
The Melio-Sonar-Token header carries session information that Melio uses as part of processing a request. For some partners, enabling the Sonar session token on specific write requests is a condition of the payment guarantees or approval rates in their agreement. Whether embedding the SDK is mandatory depends on your integration and terms. Check your documentation or confirm with your Melio integration contact whether it applies to you.
If the token is required and it’s missing, malformed, or expired, requests may be declined that would otherwise have been approved. This is easy to miss: the header is optional at the API level, so nothing fails loudly in testing if you skip it. Confirm whether it applies to you 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.
The publishable key and your API key are different credentials with opposite handling. The publishable key is client-side and used only to initialize the MelioSonar SDK. Your API key is a server-side secret used to authenticate API requests (Authorization: Bearer <api-key>). Never put your API key in client-side code, and never use the publishable key to call 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 a 403. Treat it like any other validation error: re-mint a fresh session and retry. Don’t silently drop the header and resubmit without it if it’s required.

​
What happens if you skip it

  • If it is not required: requests still work normally, and there’s no hard requirement to fix. Embedding it is still recommended as good practice.
  • If it is required: omitting it, or sending an expired/invalid token, can result in otherwise-valid payments being declined. The endpoint won’t reject the request for missing the header, but the payment decision downstream may come back negative.
If you’re not sure which case applies, confirm with your Melio partner/integration contact before launch. This gap usually shows up as an unexplained rise in declines after go-live, not as an integration error.

​
Checklist for partners

  • Confirm whether the Sonar token is required for your integration.
  • SDK script loaded on every page that leads to one of the 5 listed endpoints.
  • Session minted immediately before the write call, on the same page/action, not earlier in the flow.
  • session.token forwarded as Melio-Sonar-Token on that call.
  • 403 (invalid/expired token) handled by re-minting, not by dropping the header and retrying without it.