> ## Documentation Index
> Fetch the complete documentation index at: https://developers.staging01.melio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sonar session token

> Mint a Sonar session and forward it as the Melio-Sonar-Token header so legitimate payments aren't wrongly declined.

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.

<Warning>
  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.
</Warning>

## 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                  |
| Adding a bank account or funding source | `POST /accounts`                         | The "add account" form                                 |
| 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                      |

<Note>
  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.
</Note>

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

<Warning>
  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.
</Warning>

## How to embed it

<Steps>
  <Step title="Load the SDK">
    Add the SDK script to the page where the sensitive action happens:

    ```html theme={null}
    <script src="https://sonar.melio.com/v1/sonar-sdk.js" async></script>
    ```
  </Step>

  <Step title="Mint a session">
    Create a session right before the user submits the action:

    ```js theme={null}
    const session = await MelioSonar.createSession(publishableKey, { businessEntityId });
    ```
  </Step>

  <Step title="Forward the token">
    Send `session.token` as the `Melio-Sonar-Token` header on the write request that follows that same action:

    ```http theme={null}
    POST /v2/payments
    api-key: <your-api-key>
    Melio-Sonar-Token: <session.token>
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Note>
  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.
</Note>

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