> ## Documentation Index
> Fetch the complete documentation index at: https://developers.staging01.melio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Move money from an internal account to an external account: amounts, dates, delivery preferences, compliance, and editing.

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](/docs/idempotency).

## Amounts

All monetary amounts are expressed in **minor units (cents)**. For example, `125000` represents \$1,250.00. Currency defaults to `USD`.

<Note>
  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.
</Note>

## 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](/docs/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`.

| Value                   | Rail         | Speed                  |
| ----------------------- | ------------ | ---------------------- |
| `standard-ach`          | ACH          | 2-3 business days      |
| `same-day-ach`          | ACH          | same business day      |
| `rtp`                   | ACH          | same day, real-time    |
| `standard-check`        | Check        | 7–9 business days      |
| `express-check`         | Check        | 3-5 business days      |
| `overnight-check`       | Check        | 1 business day         |
| `domestic-wire`         | Wire         | 3 business days        |
| `instant-domestic-wire` | Wire         | Fast same business day |
| `virtual-card`          | Virtual card | 3 business days        |
| `instant-virtual-card`  | Virtual card | same business day      |

<Note>
  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](/docs/eligibility) tool to check first.
</Note>

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

```json theme={null}
{
  "compliance": {
    "type": "goods-and-services"
  }
}
```

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.

```json theme={null}
{
  "compliance": {
    "type": "goods-and-services",
    "goodsReceived": true,
    "merchantCategoryCode": "5734"
  }
}
```

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

## Related

* [Payment lifecycle](/docs/payment-lifecycle) - statuses, transitions, and webhooks.
* [Delivery ETA](/docs/delivery-eta) - preview delivery dates.
* [Fee Calculator](/docs/fee-calculator) - preview fees.
* [Eligibility](/docs/eligibility) - check fast-payment eligibility.
* [Idempotency](/docs/idempotency) - safe payment creation.