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 400 INVALID_SONAR_TOKEN.

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.

counterparty-choice is the only value for a counterparty-choice receiving account: the counterparty picks the rail when they provide their details, and the payment then reports that rail's normal-speed preference.

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card,

counterparty-choice,

international-gusd

compliance

object

required

Compliance details, discriminated by type. Only goods-and-services is supported today; other payment types may 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 500 keys; each key 1 to 40 chars and may not contain square brackets ([ ], reserved for the metadata[key] filter); value ≤100 chars. The whole object must serialize to at most 128KB of JSON. 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,

counterparty-choice,

international-fx,

fast-international-fx,

international-gusd

fees

object[]

required

The fees charged for this payment. 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). Receiver-side fees appear when the receiver upgraded the payment (see receiverUpgrade): rtp and same-day-ach are netted — deducted from the amount the receiver is paid. An instant-virtual-card upgrade carries no fee.

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, counterparty-choice, 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,

counterparty-choice,

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

failureReason

object

Why a payment failed. Present only when status is failed, and absent otherwise.

Codes are named after the industry code that produced them - the NACHA return code for an ACH return (R02_ACCOUNT_CLOSED), CARD_ for an ISO 8583 card decline - so a code can be matched against a bank return without a translation table. Failures with no industry code behind them (a returned check, a risk decision) carry a descriptive name instead.

type says which leg of the payment failed, so the same code serves both legs: R02_ACCOUNT_CLOSED under failed-to-collect refers to the payer's account, and under failed-to-deliver to the recipient's. Always read code together with type.

message is human-readable and may be reworded at any time, so do not parse or match on it. New code values may be added within an existing type, so treat an unrecognized code as the generic code for its type (COLLECTION_FAILED, DELIVERY_FAILED or RISK_DECLINED) rather than as an error.

Hide child attributes

failureReason.type

enum<string>

required

Which leg of the payment failed.

failed-to-collect - the funds could not be debited from the originating account, so no money left the payer. Typically fixable by the payer (top up the account, fix the bank details) and then re-creating the payment.

failed-to-deliver - the funds were collected but could not be credited to the receiving account, and are returned to the payer. Usually needs corrected recipient details before re-creating the payment.

risk-declined - the payment was declined in review before any money moved.

Available options:

failed-to-collect,

failed-to-deliver,

risk-declined

failureReason.code

enum<string>

required

Stable, machine-readable failure code, named after the industry code behind it.

NACHA return codes (R##_*) can appear under failed-to-collect or failed-to-deliver; type says which account the code refers to.

Card declines (CARD_*) are ISO 8583 issuer responses and appear only under failed-to-collect, since only the payer funds a payment with a card.

Delivery outcomes (CHECK_RETURNED, VIRTUAL_CARD_EXPIRED, CANCELED_BY_RECIPIENT, RECIPIENT_DETAILS_NOT_PROVIDED) have no industry code behind them and appear only under failed-to-deliver.

Risk codes (VERIFICATION_FAILED, UNSUPPORTED_BUSINESS_TYPE, UNSUPPORTED_LOCATION, PAYMENT_NOT_ALLOWED, DUPLICATE_PAYMENT_DETECTED, RISK_DECLINED) appear only under risk-declined. Declines are reported as the bare RISK_DECLINED whenever the underlying reason cannot be disclosed, so it does not imply the reason is unknown.

Available options:

R01_INSUFFICIENT_FUNDS,

R02_ACCOUNT_CLOSED,

R03_NO_ACCOUNT,

R04_INVALID_ACCOUNT_NUMBER,

R05_UNAUTHORIZED_DEBIT,

R08_PAYMENT_STOPPED,

R09_UNCOLLECTED_FUNDS,

R10_NOT_AUTHORIZED,

R13_INVALID_ROUTING_NUMBER,

R16_ACCOUNT_FROZEN,

R20_NON_TRANSACTION_ACCOUNT,

R23_CREDIT_REFUSED,

R29_CORPORATE_NOT_AUTHORIZED,

R84_CREDIT_EXCEPTION,

CARD_DO_NOT_HONOR,

CARD_INVALID_TRANSACTION,

CARD_INSUFFICIENT_FUNDS,

CARD_LIMIT_EXCEEDED,

CARD_BALANCE_UNAVAILABLE,

CHECK_RETURNED,

VIRTUAL_CARD_EXPIRED,

CANCELED_BY_RECIPIENT,

RECIPIENT_DETAILS_NOT_PROVIDED,

VERIFICATION_FAILED,

UNSUPPORTED_BUSINESS_TYPE,

UNSUPPORTED_LOCATION,

PAYMENT_NOT_ALLOWED,

DUPLICATE_PAYMENT_DETECTED,

RISK_DECLINED,

COLLECTION_FAILED,

DELIVERY_FAILED

failureReason.message

string

required

Human-readable explanation of the failure. Display-only; do not match on it.

Example:

{
  "type": "failed-to-collect",
  "code": "R01_INSUFFICIENT_FUNDS",
  "message": "The account had insufficient funds to cover the payment."
}

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

tracking

object

Delivery tracking for the payment, discriminated by type. Appears once the rail has actually reported something — absent for wire and virtual-card payments, which report nothing, and for payments whose delivery has not reached the rail yet (a scheduled payment never carries it). A present object always holds at least one identifier or timestamp; the remaining fields fill in as the delivery progresses, so treat each of them as optional.

Option 1
Option 2

Hide child attributes

tracking.type

enum<string>

required

Available options:

ach

tracking.traceNumber

string

The ACH trace number of the delivery transfer, as reported by the network — the RTP root id for an RTP delivery. Absent until the transfer has been submitted.

tracking.sentAt

string<date-time>

When the delivery transfer was submitted to the network.

tracking.clearedAt

string<date-time>

When the delivery transfer settled at the receiving bank.

receiverUpgrade

object

Present when the receiving party upgraded the payment from the payment notification Melio sent them. The upgrade itself is the payment's deliveryPreference (rtp, same-day-ach or instant-virtual-card) and receivingAccountId; the upgradedFrom* fields hold what you originally chose. A speed upgrade (rtp, same-day-ach) keeps the receiving account; the others move the payment to an account the receiver added (a bank account in place of a check, or a virtual card). The receiver pays for the upgrade — see the receiver-side entries in fees. An upgraded payment can no longer be updated (409 PAYMENT_UPGRADED_BY_RECEIVER).

Hide child attributes

receiverUpgrade.upgradedFromDeliveryPreference

enum<string>

required

The normal-speed delivery preference of the receiving account you chose, named as in deliveryPreference (e.g. standard-ach, standard-check, or same-day-ach for a card-funded payment).

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card,

counterparty-choice,

international-fx,

fast-international-fx,

international-gusd

receiverUpgrade.upgradedFromReceivingAccountId

string

required

The receiving account you chose (acct_). Equal to receivingAccountId when the upgrade kept it.

createdAt

string<date-time>

updatedAt

string<date-time>

Entities

Accounts

Attachments

Payments

Tools

Authorizations

Headers

Body

Response