The Melio Web SDK lets partners embed core Melio workflows — such as Pay Flow, onboarding, and settings — directly into their own UI with minimal effort. It provides a high-level API for launching flows while managing authentication, lifecycle, and secure communication under the hood.
prepare call, auth code, SDK setup, events, testing checklist). Start here./v1/pay-flow/prepare, /v2/auth/code) with a built-in request sender against the Public QA and Certification environments.MelioSDK, configs, and types).npm install @melio-eng/web-sdk
import { MelioSDK } from "@melio-eng/web-sdk";
// Create SDK instance
const melioSDK = new MelioSDK();
// Initialize the SDK with your authorization code
const init = melioSDK.init("AUTH_CODE_FROM_YOUR_BACKEND", {
partnerName: "your-partner-name", // required
environment: "production", // optional — defaults to 'production'
keepAlive: true, // optional — keeps the session warm
});
init.on("authenticationSucceeded", () => {
// Open the Pay Flow with the Melio bill IDs returned by /pay-flow/prepare
const payFlow = melioSDK.openPayFlow({
containerId: "melio-payflow-container",
billIds: ["bill_abc123"],
billIdType: "melio",
});
payFlow.on("completed", (data) => {
console.log("Payment completed:", data);
});
});
init.on("authenticationFailed", () => {
// Re-mint the auth code on your backend and retry
});
The full integration (backend
POST /pay-flow/prepare, minting the auth code, and handling every event) is documented in the Pay Flow Integration Guide.
melioSDK.init(authenticationCode: string, options: InitOptions): InitFlowInstance
Parameters:
authenticationCode (string, required): short-lived, user-scoped code minted on your backendoptions (InitOptions, required): Configuration options
partnerName (string, required): The partner name for the SDK instancekeepAlive (boolean): If true, the session will be kept alive in the background via an invisible iframeenvironment (Environment): The environment to use for API endpoints (defaults to 'production')branchOverride (string): Advanced/testing onlyinit returns an InitFlowInstance you can listen on for authenticationSucceeded / authenticationFailed.
| Environment | SDK environment |
API base URL |
|---|---|---|
| Production | production (default) |
https://partnerships.melioservices.com |
| Staging | staging01 |
https://partnerships.staging01.melioservices.com |
| Public QA | public-qa |
https://partnerships.public-qa.melioservices.com |
| Certification | certification |
https://partnerships.certification.melioservices.com |
| Localhost | localhost |
http://localhost:3005 |
| Flow | Method | Use it for |
|---|---|---|
| Pay Flow | melioSDK.openPayFlow({ containerId, billIds, billIdType: "melio" }) |
Pay one or more bills. Pass the Melio bill IDs returned by POST /pay-flow/prepare with billIdType: "melio". |
| Just Pay Flow | melioSDK.openJustPayFlow({ containerId, externalVendorIds }) |
Vendor-based payment (start from a vendor rather than a specific bill). |
| Payments Dashboard | melioSDK.openPaymentsDashboard({ containerId, paymentId? }) |
Let users view and manage their payments inside your product. |
| Onboarding | melioSDK.openOnboarding({ containerId }) |
Collect any missing account / KYC information directly in Melio. |
| Settings | melioSDK.openSettings({ containerId }) |
Host Melio account settings within your product. |
Each flow method returns a FlowInstance that allows you to register event listeners:
const flow = melioSDK.openPayFlow({
containerId: "melio-payflow-container",
billIds: ["bill_abc123"],
billIdType: "melio",
});
flow.on("loaded", () => console.log("Flow rendered"));
flow.on("completed", (data) => console.log("Payment completed:", data));
flow.on("error", (err) => console.warn("Flow error:", err.errorCode));
flow.on("exit", () => console.log("User exited the flow"));
flow.on("navigated", (p) => console.log("Navigated to:", p.target));
Available Events:
loaded: The flow iframe has renderedcompleted: The user successfully finished a flowerror: A flow error occurred (e.g. billsSyncFailed)exit: The user exited the iframenavigated: Navigation occurred inside the iframeauthenticationSucceeded / authenticationFailed: emitted on the init instanceWhen keepAlive: true is passed to init(), the SDK renders a hidden 1x1 pixel iframe that points to Melio's authentication endpoint. This iframe:
USER_ACTIVE_PING postMessages to MelioThis mechanism avoids redundant SSO handshakes and ensures seamless flow launches without delays.
containerIdauthUrl with token, target, entrypoint, and context (e.g., billIds)postMessageNeed an API key, partner name, or help? Contact your Melio partnerships representative.