Cancel a payment

POST

payments

{paymentId}

cancel

Cancel a payment

const options = {
  method: 'POST',
  headers: {'Melio-Entity-Id': '<melio-entity-id>', 'api-key': '<api-key>'}
};

fetch('https://api.melio.com/v2/payments/{paymentId}/cancel', 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}/cancel"

headers = {
    "Melio-Entity-Id": "<melio-entity-id>",
    "api-key": "<api-key>"
}

response = requests.post(url, headers=headers)

print(response.text)

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Melio-Entity-Id"] = '<melio-entity-id>'
request["api-key"] = '<api-key>'

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

package main

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

func main() {

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

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Melio-Entity-Id", "<melio-entity-id>")
	req.Header.Add("api-key", "<api-key>")

	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",
  "deliveryDate": "2026-07-14",
  "status": "canceled",
  "metadata": {
    "invoiceId": "INV-2043"
  },
  "createdAt": "2026-07-08T15:04:05Z",
  "updatedAt": "2026-07-08T15:20:00Z"
}

{
  "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

Response

The canceled 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

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_-]+$

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

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

createdAt

string<date-time>

updatedAt

string<date-time>

⌘I

Cancel a payment

const options = {
  method: 'POST',
  headers: {'Melio-Entity-Id': '<melio-entity-id>', 'api-key': '<api-key>'}
};

fetch('https://api.melio.com/v2/payments/{paymentId}/cancel', 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}/cancel"

headers = {
    "Melio-Entity-Id": "<melio-entity-id>",
    "api-key": "<api-key>"
}

response = requests.post(url, headers=headers)

print(response.text)

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Melio-Entity-Id"] = '<melio-entity-id>'
request["api-key"] = '<api-key>'

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

package main

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

func main() {

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

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Melio-Entity-Id", "<melio-entity-id>")
	req.Header.Add("api-key", "<api-key>")

	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",
  "deliveryDate": "2026-07-14",
  "status": "canceled",
  "metadata": {
    "invoiceId": "INV-2043"
  },
  "createdAt": "2026-07-08T15:04:05Z",
  "updatedAt": "2026-07-08T15:20:00Z"
}

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

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

Entities

Accounts

Payments

Tools

Webhooks

Authorizations

Headers

Path Parameters

Response