Skip to main content
The Melio Payouts API is a self-serve API for moving money between businesses. You onboard an entity (the business, with the details required to be payment-eligible), attach the accounts it pays from and to, and make payments - while Melio handles the banking relationships, compliance, and delivery underneath. The business you pay doesn’t need a Melio account. You provide its delivery details, or let Melio collect them directly, and Melio delivers the funds.

​
What you can do

  • Collect and pay out - fund a payment from a bank account (ACH) or a card, and deliver it on the rail that fits the payee.
  • Choose the speed per payment - standard or fast delivery, decided on each payment.
  • Pay any business - payees don’t onboard to Melio to get paid.
  • Stay compliant by default - KYC, KYB, and sanctions screening run underneath every payment.
  • Track everything - subscribe to webhooks for the full payment lifecycle.

​
Core concepts

A handful of resources make up every integration. Each has an opaque, prefixed id that is stable for the life of the resource. A payment moves money from one internal account (the debit side) to one external account (the credit side), on behalf of an entity. A payment can’t be created until the entity is payment-eligible - check the limitations endpoint to see what an entity is allowed to do.

​
Base URLs and environments

Melio provides separate environments for testing and live money movement. Both are versioned under /v2.

​
Authentication

Authenticate every request with your API key, sent in the api-key header. Keep your key secret - never expose it in client-side code or commit it to source control.

Authentication

How to authenticate requests, manage keys, and work across environments.

​
Entity context

Most requests operate on a specific entity and require the Melio-Entity-Id header - either an entity id (ent_<uuid>) or the sentinel me, which resolves to the partner’s sole entity (handy for direct partners).

​
Requests and responses

  • The API speaks JSON - send Content-Type: application/json and read JSON responses.
  • All monetary amounts are in minor units (cents). For example, 125000 represents $1,250.00. Currency defaults to USD.
  • Resource ids are opaque and prefixed (ent_, acct_, pay_). Treat them as strings; never parse or construct them.
  • externalId - attach your own unique identifier to any resource, then look it up with ?externalId= (unique per partner per resource type; reusing one returns 409 DUPLICATE_EXTERNAL_ID).
  • metadata - free-form string key/value pairs Melio stores and returns verbatim but never interprets. Filterable via metadata[key]=value.
Always calculate amounts in cents on your server before sending them to the API. Avoid floating-point arithmetic - represent dollars as integers in your data model and multiply by 100 only at serialization time.

​
Idempotency

Send an Idempotency-Key header on creates so retries are safe: the original response is replayed instead of creating a second resource. It’s required on POST /payments. Keys are retained 24 hours per partner.

​
Pagination

List endpoints are cursor-paginated and return newest-first. The envelope is { "data": [ ... ], "hasMore": true }. Page with limit (1-50, default 50) plus a cursor - startingAfter=<id> for the next (older) page, endingBefore=<id> for the previous (newer) one. Keep going until hasMore is false.

​
Getting started

The typical integration follows these steps:
1

Onboard the entity

POST /entities to create the business (organization plus owner). Melio runs KYC/KYB; check GET /limitations to confirm it’s payment-eligible.
2

Add an internal account

Register the account funds are pulled from - a bank account (via Plaid or account/routing) or a card - with POST /accounts.
3

Add an external account

Add the payee (ACH, check, domestic wire, or virtual card) with POST /accounts.
4

Create a payment

POST /payments referencing the internal and external accounts, amount, deductionDate, and deliveryPreference. Send an Idempotency-Key. Melio returns the estimated delivery date.
5

Track it

Subscribe to webhooks to follow the payment through its lifecycle and know when it’s delivered.
6

Reconcile

Map Melio resources back to your own records using externalId and metadata.
Before creating a payment you can pre-flight it with the Tools endpoints: POST /tools/fee-calculator, POST /tools/fast-payment-eligibility, and POST /tools/delivery-eta - no resource is created.

​
Payment lifecycle

After creation, a payment moves through the following states:
You can edit (PATCH /payments/{id}) or cancel (POST /payments/{id}/cancel) a payment while it’s scheduled. Once it moves to in-progress it’s locked (409 PAYMENT_NOT_EDITABLE / PAYMENT_NOT_CANCELABLE). A payment under risk review is still reported as scheduled - there’s no separate review status.

Authentication

Authenticate requests and manage your API keys.

Payments

Amounts, dates, delivery preferences, and the full payment lifecycle.

Webhooks

Subscribe to lifecycle events and reconcile in real time.