Update a payment

PATCH

payments

{paymentId}

Update a payment

const options = {
  method: 'PATCH',
  headers: {
    'Melio-Entity-Id': '<melio-entity-id>',
    'api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deliveryPreference: 'rtp',
    noteToRecipient: 'Invoice 42 (updated)',
    metadata: {invoiceId: 'INV-2043'}
  })
};

fetch('https://api.melio.com/v2/payments/{paymentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.melio.com/v2/payments/{paymentId}"

payload = {
    "deliveryPreference": "rtp",
    "noteToRecipient": "Invoice 42 (updated)",
    "metadata": { "invoiceId": "INV-2043" }
}
headers = {
    "Melio-Entity-Id": "<melio-entity-id>",
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.melio.com/v2/payments/{paymentId} \
  --header 'Content-Type: application/json' \
  --header 'Melio-Entity-Id: <melio-entity-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "deliveryPreference": "rtp",
  "noteToRecipient": "Invoice 42 (updated)",
  "metadata": {
    "invoiceId": "INV-2043"
  }
}
'

HttpResponse<String> response = Unirest.patch("https://api.melio.com/v2/payments/{paymentId}")
  .header("Melio-Entity-Id", "<melio-entity-id>")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deliveryPreference\": \"rtp\",\n  \"noteToRecipient\": \"Invoice 42 (updated)\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.melio.com/v2/payments/{paymentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Melio-Entity-Id"] = '<melio-entity-id>'
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deliveryPreference\": \"rtp\",\n  \"noteToRecipient\": \"Invoice 42 (updated)\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.melio.com/v2/payments/{paymentId}"

	payload := strings.NewReader("{\n  \"deliveryPreference\": \"rtp\",\n  \"noteToRecipient\": \"Invoice 42 (updated)\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Melio-Entity-Id", "<melio-entity-id>")
	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "pay_9f8c7b6a5d4e3f21",
  "externalId": "invoice-2043",
  "amount": 125000,
  "currency": "USD",
  "originatingAccountId": "acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "receivingAccountId": "acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "deductionDate": "2026-07-10",
  "deliveryPreference": "rtp",
  "deliveryDate": "2026-07-10",
  "status": "scheduled",
  "noteToRecipient": "Invoice 42 (updated)",
  "metadata": {
    "invoiceId": "INV-2043"
  },
  "createdAt": "2026-07-08T15:04:05Z",
  "updatedAt": "2026-07-08T15:12:00Z"
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "BUSINESS_NOT_ELIGIBLE",
    "message": "Business is not eligible to make payments. See the limitations endpoint for details."
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

Authorizations

api-key

string

header

required

Headers

Melio-Entity-Id

string

required

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

Path Parameters

paymentId

string

required

Body

application/json

Fields that can be changed on a payment before it begins processing. All fields are optional; only supplied fields are updated.

amount

integer

Minor units (cents). Amount changes may be rejected (400) when the partner is not configured to allow them or when the payment spans multiple bills.

deductionDate

string<date>

The debit/schedule date

deliveryPreference

enum<string>

See CreatePaymentRequest.deliveryPreference. The preference's rail must match the payment's receiving account; fast variants remain subject to the per-payment eligibility check and are rejected with 400 when ineligible.

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card

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

The updated payment.

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

string

required

The fee category (e.g. ach, card, expedited-ach).

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>

deliveryPreference

enum<string>

Effective delivery preference. Reflects the faster variant when one was applied, otherwise the receiving rail's normal-speed value.

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card

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>

⌘I

Update a payment

const options = {
  method: 'PATCH',
  headers: {
    'Melio-Entity-Id': '<melio-entity-id>',
    'api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deliveryPreference: 'rtp',
    noteToRecipient: 'Invoice 42 (updated)',
    metadata: {invoiceId: 'INV-2043'}
  })
};

fetch('https://api.melio.com/v2/payments/{paymentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.melio.com/v2/payments/{paymentId}"

payload = {
    "deliveryPreference": "rtp",
    "noteToRecipient": "Invoice 42 (updated)",
    "metadata": { "invoiceId": "INV-2043" }
}
headers = {
    "Melio-Entity-Id": "<melio-entity-id>",
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.melio.com/v2/payments/{paymentId} \
  --header 'Content-Type: application/json' \
  --header 'Melio-Entity-Id: <melio-entity-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "deliveryPreference": "rtp",
  "noteToRecipient": "Invoice 42 (updated)",
  "metadata": {
    "invoiceId": "INV-2043"
  }
}
'

HttpResponse<String> response = Unirest.patch("https://api.melio.com/v2/payments/{paymentId}")
  .header("Melio-Entity-Id", "<melio-entity-id>")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deliveryPreference\": \"rtp\",\n  \"noteToRecipient\": \"Invoice 42 (updated)\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.melio.com/v2/payments/{paymentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Melio-Entity-Id"] = '<melio-entity-id>'
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deliveryPreference\": \"rtp\",\n  \"noteToRecipient\": \"Invoice 42 (updated)\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.melio.com/v2/payments/{paymentId}"

	payload := strings.NewReader("{\n  \"deliveryPreference\": \"rtp\",\n  \"noteToRecipient\": \"Invoice 42 (updated)\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Melio-Entity-Id", "<melio-entity-id>")
	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "pay_9f8c7b6a5d4e3f21",
  "externalId": "invoice-2043",
  "amount": 125000,
  "currency": "USD",
  "originatingAccountId": "acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "receivingAccountId": "acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "deductionDate": "2026-07-10",
  "deliveryPreference": "rtp",
  "deliveryDate": "2026-07-10",
  "status": "scheduled",
  "noteToRecipient": "Invoice 42 (updated)",
  "metadata": {
    "invoiceId": "INV-2043"
  },
  "createdAt": "2026-07-08T15:04:05Z",
  "updatedAt": "2026-07-08T15:12:00Z"
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "BUSINESS_NOT_ELIGIBLE",
    "message": "Business is not eligible to make payments. See the limitations endpoint for details."
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

Entities

Accounts

Payments

Tools

Webhooks

Authorizations

Headers

Path Parameters

Body

Response