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.
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:
  • Large payments - when amount is greater than 300000 ($3,000.00), you must set "goodsReceived": true in the compliance object, confirming the goods or services were received.
  • Card-originating payments - when the originating account is a card (type: card), you must supply merchantCategoryCode (the counterparty’s 4-digit MCC) in the compliance object.

​
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.