Skip to main content
A payment links one internal account (the debit side) to one external account (the credit side). When you create a payment, you specify the amount, the date Melio should debit the originating account, and how fast you want the funds to arrive. Melio returns the estimated delivery date based on your delivery preference. Creating a payment requires an Idempotency-Key header so the request is safe to retry. See Idempotency.

Amounts

All monetary amounts are expressed in minor units (cents). For example, 125000 represents $1,250.00. Currency defaults to USD.
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.

Deduction date vs. delivery date

Two dates appear on every payment:
  • deductionDate - the date you request Melio to debit the originating (internal) account. You provide this when creating the payment.
  • deliveryDate - the estimated date the payee receives funds. Melio calculates and returns this in the response based on the chosen deliveryPreference. You cannot set it directly.
To preview delivery dates before creating a payment, use the Delivery ETA tool.

Delivery preferences

Choose a deliveryPreference whose rail matches the receiving account’s type. Sending a preference for the wrong rail is rejected with 400.
Payment delivery speed depends on the deliveryPreference you choose. When paying from a bank account, ACH-based deliveries are bound by daily ACH cutoff times: a payment submitted before the cutoff on a business day starts processing that day, while one submitted after the cutoff (or on a weekend or bank holiday) rolls over to the next business day. RTP payments are not tied to these cutoffs and can be sent 24/7, including weekends and holidays.Because the exact date depends on the rail, the cutoff, and the submission time, present the user with the estimated delivery date for each available delivery option before creating a payment, using POST /tools/delivery-eta.
The preference’s rail must match the receiving account’s type. For example, standard-ach and same-day-ach require an external account with type: ach; standard-check requires type: check. All fast variants (same-day-ach, rtp, express-check, overnight-check, instant-domestic-wire, instant-virtual-card) additionally require an ACH originating account and pass a per-payment eligibility check.
A fast variant that is ineligible is rejected with 400 and never silently downgraded. Use the Eligibility tool to check first.

Compliance

Every payment requires a compliance object, discriminated by type. It captures the purpose of the transfer and satisfies regulatory requirements. goods-and-services is the only supported type today.
Two additional rules apply based on the payment’s characteristics: Card-originating payments When a payment is funded by a card, you must tell us about the counterparty you are paying: their merchant category code (MCC) and their business address. Both travel in the compliance.card object on POST /v2/payments. Bank-funded (ACH) payments do not need either. This page covers what to send, why the card networks require it, and how to collect it from your users without adding a form to every payment.
merchantAddress is not the check mailing address. It is compliance data about the counterparty’s business, sent to the card networks - it never affects where a payment is delivered.

Why the card networks need this

A payout funded by a card is not a transfer — it is a card transaction, and the counterparty you are paying is the merchant on it. Under the card networks’ payment-facilitator rules, a transaction presented on behalf of another business must carry that business’s own details: the networks treat the sponsored business as the merchant of record, and require a facilitator to identify it on every authorization. Visa, Mastercard and American Express each require the sub-merchant’s identifier, name, location and category code to be sent with the transaction.

The MCC classifies the counterparty’s business

An MCC is a four-digit code describing a business’s primary line of trade - 5045 is computers and peripherals, 7372 is prepackaged software, 8931 is accounting and bookkeeping services. Once assigned, it drives three separate decisions that all happen before a payment settles:
  • Whether the transaction is allowed at all. Some categories are restricted or outright prohibited on certain card products, and others require the acquirer to register the business with the scheme first. A prohibited MCC is not a fee problem - the payment is declined.
  • What the transaction costs. Interchange is priced partly by category, with higher-risk lines of business priced higher. The B2B interchange programs that make commercial-card acceptance economic are conditioned on the right category being present.
  • How the issuer treats it. Category drives rewards eligibility, spend controls, and the fraud models an issuer runs at authorization time.
Assigning the category is the facilitator’s job, not a formality passed through from the payer — the rules put the obligation on the facilitator to evaluate each sponsored business and assign the MCC that matches its primary business. That is why we ask you to send the counterparty’s real category rather than a default. In practice this means an MCC you send can be rejected:
  • Some MCCs are prohibited for some card networks. American Express in particular accepts a narrower set than Visa or Mastercard, and a funding source that would otherwise work becomes unavailable for that counterparty.
  • A card payment can also fail after it is scheduled, with an invalid-MCC failure from the processor, if the category does not hold up downstream.
Send the category that describes what the counterparty actually does. A catch-all code applied to every counterparty is the single most common cause of declines here, and it is the kind of misclassification the schemes audit for.

The merchant address identifies where that business is

Alongside the name and category, the authorization message carries the merchant’s location the card acceptor’s city, state and country. It is a small field, and it does a lot of work:
  • It is what the cardholder sees. The acceptor name and location string is the descriptor that lands on the card statement, and it is usually shown to the cardholder verbatim.
  • It classifies the transaction as domestic or cross-border, which changes both the rules that apply and the price.
  • It feeds fraud scoring at authorization, and it is part of the record if the transaction is later disputed.
An address that is missing or wrong does not usually fail loudly at authorization. It shows up later as an unrecognizable line on a statement, a cardholder who does not know what they paid for, and a dispute that is harder to defend.

Collecting this from your users

You need these details once per counterparty, not once per payment. The pattern that works:
  1. Ask when the counterparty is created, alongside the bank details - while the user is already entering the payee’s information and has it in front of them.
  2. Store both against your own record of that counterparty.
  3. Replay them on every card payment. They are cheap to send, and resending keeps the record current.
  4. Only prompt again when something changes - a corrected address, or a category that was rejected.
If your users cannot pick a category, do not make them guess from the full list. Offer a short set of codes that fit the kinds of businesses they actually pay, and map your own industry taxonomy onto MCCs behind the scenes. Because the requirement is card-only, an integration that funds exclusively from bank accounts can skip the collection entirely — and one that supports both should gate the prompt on the originating account type rather than showing it to everyone. A card payment that clears these checks can still be rejected later for a prohibited category, one that is valid in shape but not accepted on that card network. Handle both: a 400 at request time, and a payment that fails after scheduling.

Tracking

Once a payment starts moving, the rail carrying it reports back an identifier and a few timestamps. These surface on the payment as a tracking object, discriminated by type this is the value you quote to a recipient who says the money never arrived, or to a bank tracing it.
traceNumber is the ACH trace number as the network reports it for an rtp delivery it is the RTP root id, the equivalent identifier on that network. It is a string, not a number: the values are fixed-width and carry leading zeros,checkNumber is the serial number printed on the check, the one the recipient reads off the paper. Wire and virtual-card payments report nothing and never carry tracking.
tracking is absent more often than it is present, and three different situations look identical in the response: the payment has not begun delivery yet (the common case right after POST /v2/payments), the rail does not report at all (wire, virtual card), or the payment failed or was canceled before delivery.Fields within a present object also fill in over time, so tracking can arrive carrying little more than its type an ACH transfer in flight has traceNumber and sentAt but no clearedAt until it settles.Treat every field as optional, including the identifier, and branch on type rather than on deliveryPreference
tracking is part of the payment, so it comes back from GET /v2/payments/{id} and on every item of GET /v2/payments, a payment created a moment ago cannot have a delivery transfer yet.

Editing payments

You can update a payment with PATCH /payments/{id} only while its status is scheduled. The editable fields are:
  • amount (may be rejected with 400 when your partner configuration does not allow amount changes, or when the payment spans multiple bills)
  • deductionDate
  • deliveryPreference
  • noteToSelf
  • noteToRecipient
  • externalId
  • metadata
Only the fields you send are changed. Once a payment transitions to in-progress, it is locked: a PATCH returns 409 PAYMENT_NOT_EDITABLE, and a cancel returns 409 PAYMENT_NOT_CANCELABLE.

Notes

Two separate note fields let you attach free-text context to a payment:
  • noteToSelf - a payer-private memo, never shown to the recipient. Use it for internal memos or reference numbers.
  • noteToRecipient - shown to the payment recipient. Use it to communicate invoice numbers, PO references, or payment context.