Sonar session token

The 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.

The Sonar token is required on the requests listed below. If it’s missing, malformed, or expired, requests may be declined that would otherwise have been approved. This is easy to miss: the API doesn’t reject a request for a missing header, so nothing fails loudly in testing if you skip it. Your integration is not complete until the token is sent on every listed request.

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:

User action	API call	Mint a session on
Creating a business/individual entity	`POST /entities`	The entity creation / onboarding form
Updating a business/individual entity	`PATCH /entities/{entityId}`	The entity update form. Required whenever your integration offers this action.
Adding an account: a funding source (internal account) or a delivery method for a vendor (external account)	`POST /accounts`	Both the “add funding source” form and the “add delivery method” page
Linking an existing account	`POST /accounts/link`	The account-linking flow (e.g. Plaid-style connect UI)
Verifying a linked account	`POST /accounts/{accountId}/verify/link`	The micro-deposit / verification confirmation screen
Submitting a payment	`POST /payments`	The payment review/confirm screen
Updating a payment	`PATCH /payments/{paymentId}`	The payment review/confirm screen. Required whenever your integration offers this action.

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 via the api-key header (no Bearer prefix). Never put your API key in client-side code, and never use the publishable key to call the API.

How to embed it

Load the SDK

Add the SDK script to the page where the sensitive action happens:

For sandbox:
<script src="https://sonar.staging01.melio.com/v1/sonar-sdk.js" async></script>

For production: 
<script src="https://sonar.melio.com/v1/sonar-sdk.js" async></script>

Mint a session

Create a session right before the user submits the action:

const session = await MelioSonar.createSession(publishableKey, { businessEntityId });

Forward the token

Send session.token as the Melio-Sonar-Token header on the write request that follows that same action:

POST /v2/payments
api-key: <your-api-key>
Melio-Sonar-Token: <session.token>

Handle failures

An invalid or expired token returns a 403. Treat it like any other validation error: re-mint a fresh session and retry. Never drop the header and resubmit without it.

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.token forwarded as Melio-Sonar-Token on that call.
403 (invalid/expired token) handled by re-minting, never dropped.

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Legal

When to embed it

Publishable key

How to embed it

What happens if you skip it

Checklist for partners