Create a payment

Authorizations

api-key

string

header

required

Headers

Idempotency-Key

string

required

Required unique key (UUID recommended) that makes payment creation safe to retry by replaying the original response; retained 24h per partner, omitting it returns 400.

Maximum string length: 255

Melio-Sonar-Token

string

Signed MelioSonar session token from the initiating device, used for risk evaluation; invalid or expired tokens return 403.

Melio-Entity-Id

string

required

Entity the request operates on — an entity id (ent_<uuid>) or me (the partner's sole entity).

Body

application/json

Option 1
Option 2

Which payload applies follows from deliveryPreference: the two international-fx values take CreateFxPaymentRequest, every other value takes CreateUsdPaymentRequest.

amount

integer

required

Minor units of the currency the counterparty is paid in — the amount they receive. For a converted payment (CreateFxPaymentRequest) that is the foreign amount, and the entity is debited the equivalent in USD at the applied rate.

originatingAccountId

string

required

Internal originating account id (acct_), the debit account

receivingAccountId

string

required

External receiving account id (acct_), the credit account

deductionDate

string<date>

required

deliveryPreference

enum<string>

required

Required, and explicit about the receiving rail and delivery speed.

The preference's rail must match the receiving external account, otherwise the request is rejected with 400.

With a bank (ACH) originating account, funds are collected before they are delivered (the good-funds model): the standard values deliver at the rail's normal speed, and the faster variants are subject to a per-payment eligibility check — an ineligible fast variant is rejected with 400 (never silently downgraded).

With a card originating account, the collect is immediate, so ACH and wire payments already deliver at the fast speed: use same-day-ach (not standard-ach) and instant-domestic-wire (not domestic-wire) — the superseded standard values are rejected with 400, and no eligibility check applies to these two. Check values are unchanged, and virtual-card receiving accounts cannot be paid from a card originating account.

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card,

international-gusd

compliance

object

required

Compliance details, discriminated by type. Only goods-and-services is supported today; future payment types (internal money movement, mass payouts) will add their own variants with different fields.

Hide child attributes

compliance.type

enum<string>

required

Available options:

goods-and-services

compliance.goodsReceived

boolean

The payer confirms the goods or services were received. Required to be true only for card-originated payments above $3,000 (amount greater than 300000 minor units). Not required for non-card payments or for amounts at or below the threshold.

compliance.card

object

Compliance details the card networks require about the counterparty. Required, with all of its fields, when the originating account is a card; ignored for every other originating account type.

Hide child attributes

compliance.card.merchantCategoryCode

string

required

The counterparty's 4-digit MCC (merchant category code).

Pattern: ^\d{4}$

compliance.card.merchantAddress

object

The counterparty's business address. Required for card-originated payments, the same as the MCC. Saved on the counterparty, so the most recent payment's address is the one held on record.

Hide child attributes

compliance.card.merchantAddress.line1

string

required

Street address. Must not be a PO box for the business (physical) address.

compliance.card.merchantAddress.city

string

required

compliance.card.merchantAddress.state

string

required

Two-letter US state or territory code (e.g. NY, CA). Must be a recognized USPS abbreviation.

Pattern: ^[A-Za-z]{2}$

compliance.card.merchantAddress.postalCode

string

required

US ZIP code, 5 or 9 digits, with or without a hyphen before the last 4 (e.g. 10118, 10118-1234).

Pattern: ^\d{5}(-?\d{4})?$

compliance.card.merchantAddress.line2

string

compliance.card.merchantAddress.aptNumber

string

compliance.card.merchantAddress.countryCode

enum<string>

default:US

Available options:

US

currency

string

default:USD

The currency the counterparty is paid in, which must match the receiving account's. USD for every domestic rail and for international-gusd, where it is the default and safe to omit; on CreateFxPaymentRequest it is required and must be the account's own currency. A mismatch — including USD against an international-fx account, which is never dollar-denominated — is rejected with 400 VALIDATION_ERROR.

attachmentId

string

A supporting document for this payment, from POST /attachments (att_<id>).

Some international destinations will not accept a payment without one — the provider decides which, based on the destination country's risk rating, and the requirement can also depend on whether you have paid that counterparty before. When it applies and no attachmentId is given, the payment is rejected with 400 ATTACHMENT_REQUIRED; upload the document and retry. Sending one where it is not required is always accepted.

The document is attached at creation, so it cannot be added or replaced with PATCH /payments/{paymentId}. The attachment must belong to the same entity as the payment, otherwise the request is rejected with 404.

Example:

"att_9f8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"

noteToSelf

string

Payer-private memo, never shown to the recipient

noteToRecipient

string

Note shown to the payment recipient

externalId

string

Your own unique identifier for the resource. Unique per partner per resource type (reusing one returns 409 DUPLICATE_EXTERNAL_ID). Distinct from the Idempotency-Key header, which dedupes the request rather than identifying the resource.

Maximum string length: 255

Pattern: ^[A-Za-z0-9_-]+$

metadata

object

Free-form string key/value pairs stored and returned verbatim, never interpreted by Melio. Up to 50 keys; each key 1 to 40 chars and may not contain square brackets ([ ], reserved for the metadata[key] filter); value ≤100 chars. Filterable via metadata[key].

Hide child attributes

metadata.{key}

string

Maximum string length: 100

Response

Payment created.

deliveryPreference

enum<string>

required

Effective delivery preference. Reflects the faster variant when one was applied, otherwise the receiving rail's normal-speed value. Card-funded ACH and wire payments always report the fast name (same-day-ach / instant-domestic-wire) — a card collect is immediate, so those payments deliver at the fast speed.

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card,

international-fx,

fast-international-fx,

international-gusd

fees

object[]

required

The fees charged for this payment, as recorded by the fees service. Includes both the originator-side and receiver-side fees; use chargeTo on each item to tell them apart. Always present — an empty array when no fees have been recorded yet (e.g. a freshly created payment).

Hide child attributes

fees.type

enum<string>

required

What the fee is for. Delivery-method fees use the delivery preference they apply to (standard-ach, same-day-ach, rtp, standard-check, express-check, overnight-check, domestic-wire, instant-domestic-wire, international-fx, fast-international-fx, international-gusd); funding-source fees use the funding-source type (card).

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

international-fx,

fast-international-fx,

international-gusd,

card

fees.chargeTo

enum<string>

required

Which side of the payment the fee is levied on: the account originating the payment or the account receiving it. Works for both estimated (calculator) and applied (payment) fees.

Available options:

originator,

receiver

fees.status

enum<string>

required

Whether the fee has been charged or is still pending.

Available options:

charged,

pending

fees.fixed

object

Present when the fee is a flat amount.

Hide child attributes

fees.fixed.value

integer

Flat fee, minor units (cents)

fees.percent

object

Present when the fee is a percentage of the payment amount.

Hide child attributes

fees.percent.rate

number

Percentage rate (e.g. 2.9 = 2.9%)

fees.percent.min

integer

Minimum fee, minor units (cents)

fees.percent.max

integer

Maximum fee, minor units (cents)

fees.amount

integer

The resolved fee for the requested payment amount, in minor units (cents). Absent only when the fee cannot be resolved without a per-payment quote (e.g. tiered pricing).

string

Opaque payment id (pay_)

externalId

string

Maximum string length: 255

Pattern: ^[A-Za-z0-9_-]+$

amount

integer

currency

string

originatingAccountId

string

Internal originating account id (acct_)

receivingAccountId

string

External receiving account id (acct_)

deductionDate

string<date>

deliveryDate

string<date>

status

enum<string>

While a payment is being reviewed it is reported as scheduled; there is no separate review status.

Available options:

scheduled,

in-progress,

completed,

failed,

canceled

noteToSelf

string

Payer-private memo, never shown to the recipient

noteToRecipient

string

Note shown to the payment recipient

metadata

object

Hide child attributes

metadata.{key}

string

Maximum string length: 100

createdAt

string<date-time>

updatedAt

string<date-time>

Entities

Accounts

Attachments

Payments

Tools

Webhooks

Authorizations

Headers

Body

Response