List payments

GET

payments

List payments

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

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

import requests

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

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

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

print(response.text)

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.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"

	req, _ := http.NewRequest("GET", 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))

}

{
  "hasMore": true,
  "data": [
    {
      "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": "standard-ach",
      "deliveryDate": "2026-07-14",
      "status": "scheduled",
      "metadata": {
        "invoiceId": "INV-2043",
        "department": "operations"
      },
      "fees": [],
      "createdAt": "2026-07-08T15:04:05Z",
      "updatedAt": "2026-07-08T15:04:05Z"
    },
    {
      "id": "pay_1a2b3c4d5e6f7a8b",
      "externalId": "invoice-2041",
      "amount": 4200,
      "currency": "USD",
      "originatingAccountId": "acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "receivingAccountId": "acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "deductionDate": "2026-07-09",
      "deliveryPreference": "same-day-ach",
      "deliveryDate": "2026-07-11",
      "status": "completed",
      "metadata": {},
      "fees": [
        {
          "type": "same-day-ach",
          "chargeTo": "originator",
          "percent": {
            "rate": 0.5,
            "max": 3000
          },
          "amount": 21,
          "status": "charged"
        }
      ],
      "tracking": {
        "type": "ach",
        "traceNumber": "021000021234567",
        "sentAt": "2026-07-09T18:30:00Z",
        "clearedAt": "2026-07-11T07:15:00Z"
      },
      "createdAt": "2026-07-07T09:22:00Z",
      "updatedAt": "2026-07-07T09:22:00Z"
    }
  ]
}

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

Query Parameters

limit

integer

default:50

Maximum number of resources to return, 1 to 50. Defaults to 50.

Required range: 1 <= x <= 50

startingAfter

string

Cursor for forward (older) pagination: a resource id. The page returned starts immediately after this resource. Mutually exclusive with endingBefore.

endingBefore

string

Cursor for backward (newer) pagination: a resource id. The page returned ends immediately before this resource. Mutually exclusive with startingAfter.

externalId

string

Return only the payment whose externalId matches (your own id).

status

enum<string>

Filter by payment status.

Available options:

scheduled,

in-progress,

completed,

failed,

canceled

originatingAccountId

string

Return only payments drawn from this internal originating account (acct_).

receivingAccountId

string

Return only payments sent to this external receiving account (acct_).

created[gte]

string<date-time>

Return payments created at or after this RFC 3339 timestamp.

created[lte]

string<date-time>

Return payments created at or before this RFC 3339 timestamp.

metadata

object

Filter by metadata key/value pairs, e.g. metadata[invoiceId]=INV-42. Matches payments whose metadata contains every supplied pair.

Hide child attributes

metadata.{key}]

string

Response

A page of payments, newest first.

data

object[]

required

Hide child attributes

data.deliveryPreference

enum<string>

required

Effective delivery preference. Reflects the faster variant when one was applied, otherwise the receiving rail's normal-speed value. Card-funded ACH and wire payments always report the fast name (same-day-ach / instant-domestic-wire) — a card collect is immediate, so those payments deliver at the fast speed.

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card,

counterparty-choice,

international-fx,

fast-international-fx,

international-gusd

data.fees

object[]

required

The fees charged for this payment. 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). Receiver-side fees appear when the receiver upgraded the payment (see receiverUpgrade): rtp and same-day-ach are netted — deducted from the amount the receiver is paid. An instant-virtual-card upgrade carries no fee.

Hide child attributes

data.fees.type

enum<string>

required

What the fee is for. Delivery-method fees use the delivery preference they apply to (standard-ach, same-day-ach, rtp, standard-check, express-check, overnight-check, domestic-wire, instant-domestic-wire, counterparty-choice, international-fx, fast-international-fx, international-gusd); funding-source fees use the funding-source type (card).

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

counterparty-choice,

international-fx,

fast-international-fx,

international-gusd,

card

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

data.fees.status

enum<string>

required

Whether the fee has been charged or is still pending.

Available options:

charged,

pending

data.fees.fixed

object

Present when the fee is a flat amount.

Hide child attributes

data.fees.fixed.value

integer

Flat fee, minor units (cents)

data.fees.percent

object

Present when the fee is a percentage of the payment amount.

Hide child attributes

data.fees.percent.rate

number

Percentage rate (e.g. 2.9 = 2.9%)

data.fees.percent.min

integer

Minimum fee, minor units (cents)

data.fees.percent.max

integer

Maximum fee, minor units (cents)

data.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).

data.id

string

Opaque payment id (pay_)

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

data.amount

integer

data.currency

string

data.originatingAccountId

string

Internal originating account id (acct_)

data.receivingAccountId

string

External receiving account id (acct_)

data.deductionDate

string<date>

data.deliveryDate

string<date>

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

data.failureReason

object

Why a payment failed. Present only when status is failed, and absent otherwise.

Codes are named after the industry code that produced them - the NACHA return code for an ACH return (R02_ACCOUNT_CLOSED), CARD_ for an ISO 8583 card decline - so a code can be matched against a bank return without a translation table. Failures with no industry code behind them (a returned check, a risk decision) carry a descriptive name instead.

type says which leg of the payment failed, so the same code serves both legs: R02_ACCOUNT_CLOSED under failed-to-collect refers to the payer's account, and under failed-to-deliver to the recipient's. Always read code together with type.

message is human-readable and may be reworded at any time, so do not parse or match on it. New code values may be added within an existing type, so treat an unrecognized code as the generic code for its type (COLLECTION_FAILED, DELIVERY_FAILED or RISK_DECLINED) rather than as an error.

Hide child attributes

data.failureReason.type

enum<string>

required

Which leg of the payment failed.

failed-to-collect - the funds could not be debited from the originating account, so no money left the payer. Typically fixable by the payer (top up the account, fix the bank details) and then re-creating the payment.

failed-to-deliver - the funds were collected but could not be credited to the receiving account, and are returned to the payer. Usually needs corrected recipient details before re-creating the payment.

risk-declined - the payment was declined in review before any money moved.

Available options:

failed-to-collect,

failed-to-deliver,

risk-declined

data.failureReason.code

enum<string>

required

Stable, machine-readable failure code, named after the industry code behind it.

NACHA return codes (R##_*) can appear under failed-to-collect or failed-to-deliver; type says which account the code refers to.

Card declines (CARD_*) are ISO 8583 issuer responses and appear only under failed-to-collect, since only the payer funds a payment with a card.

Delivery outcomes (CHECK_RETURNED, VIRTUAL_CARD_EXPIRED, CANCELED_BY_RECIPIENT, RECIPIENT_DETAILS_NOT_PROVIDED) have no industry code behind them and appear only under failed-to-deliver.

Risk codes (VERIFICATION_FAILED, UNSUPPORTED_BUSINESS_TYPE, UNSUPPORTED_LOCATION, PAYMENT_NOT_ALLOWED, DUPLICATE_PAYMENT_DETECTED, RISK_DECLINED) appear only under risk-declined. Declines are reported as the bare RISK_DECLINED whenever the underlying reason cannot be disclosed, so it does not imply the reason is unknown.

Available options:

R01_INSUFFICIENT_FUNDS,

R02_ACCOUNT_CLOSED,

R03_NO_ACCOUNT,

R04_INVALID_ACCOUNT_NUMBER,

R05_UNAUTHORIZED_DEBIT,

R08_PAYMENT_STOPPED,

R09_UNCOLLECTED_FUNDS,

R10_NOT_AUTHORIZED,

R13_INVALID_ROUTING_NUMBER,

R16_ACCOUNT_FROZEN,

R20_NON_TRANSACTION_ACCOUNT,

R23_CREDIT_REFUSED,

R29_CORPORATE_NOT_AUTHORIZED,

R84_CREDIT_EXCEPTION,

CARD_DO_NOT_HONOR,

CARD_INVALID_TRANSACTION,

CARD_INSUFFICIENT_FUNDS,

CARD_LIMIT_EXCEEDED,

CARD_BALANCE_UNAVAILABLE,

CHECK_RETURNED,

VIRTUAL_CARD_EXPIRED,

CANCELED_BY_RECIPIENT,

RECIPIENT_DETAILS_NOT_PROVIDED,

VERIFICATION_FAILED,

UNSUPPORTED_BUSINESS_TYPE,

UNSUPPORTED_LOCATION,

PAYMENT_NOT_ALLOWED,

DUPLICATE_PAYMENT_DETECTED,

RISK_DECLINED,

COLLECTION_FAILED,

DELIVERY_FAILED

data.failureReason.message

string

required

Human-readable explanation of the failure. Display-only; do not match on it.

Example:

{
  "type": "failed-to-collect",
  "code": "R01_INSUFFICIENT_FUNDS",
  "message": "The account had insufficient funds to cover the payment."
}

data.noteToSelf

string

Payer-private memo, never shown to the recipient

data.noteToRecipient

string

Note shown to the payment recipient

data.metadata

object

Free-form string key/value pairs stored and returned verbatim, never interpreted by Melio. Up to 500 keys; each key 1 to 40 chars and may not contain square brackets ([ ], reserved for the metadata[key] filter); value ≤100 chars. The whole object must serialize to at most 128KB of JSON. Filterable via metadata[key].

Hide child attributes

data.metadata.{key}

string

Maximum string length: 100

data.tracking

object

Delivery tracking for the payment, discriminated by type. Appears once the rail has actually reported something — absent for wire and virtual-card payments, which report nothing, and for payments whose delivery has not reached the rail yet (a scheduled payment never carries it). A present object always holds at least one identifier or timestamp; the remaining fields fill in as the delivery progresses, so treat each of them as optional.

Option 1
Option 2

Hide child attributes

data.tracking.type

enum<string>

required

Available options:

ach

data.tracking.traceNumber

string

The ACH trace number of the delivery transfer, as reported by the network — the RTP root id for an RTP delivery. Absent until the transfer has been submitted.

data.tracking.sentAt

string<date-time>

When the delivery transfer was submitted to the network.

data.tracking.clearedAt

string<date-time>

When the delivery transfer settled at the receiving bank.

data.receiverUpgrade

object

Present when the receiving party upgraded the payment from the payment notification Melio sent them. The upgrade itself is the payment's deliveryPreference (rtp, same-day-ach or instant-virtual-card) and receivingAccountId; the upgradedFrom* fields hold what you originally chose. A speed upgrade (rtp, same-day-ach) keeps the receiving account; the others move the payment to an account the receiver added (a bank account in place of a check, or a virtual card). The receiver pays for the upgrade — see the receiver-side entries in fees. An upgraded payment can no longer be updated (409 PAYMENT_UPGRADED_BY_RECEIVER).

Hide child attributes

data.receiverUpgrade.upgradedFromDeliveryPreference

enum<string>

required

The normal-speed delivery preference of the receiving account you chose, named as in deliveryPreference (e.g. standard-ach, standard-check, or same-day-ach for a card-funded payment).

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card,

counterparty-choice,

international-fx,

fast-international-fx,

international-gusd

data.receiverUpgrade.upgradedFromReceivingAccountId

string

required

The receiving account you chose (acct_). Equal to receivingAccountId when the upgrade kept it.

data.createdAt

string<date-time>

data.updatedAt

string<date-time>

hasMore

boolean

required

True when more resources exist after this page; page again using the last item's id as startingAfter.

List payments

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

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

import requests

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

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

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

print(response.text)

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.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"

	req, _ := http.NewRequest("GET", 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))

}

{
  "hasMore": true,
  "data": [
    {
      "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": "standard-ach",
      "deliveryDate": "2026-07-14",
      "status": "scheduled",
      "metadata": {
        "invoiceId": "INV-2043",
        "department": "operations"
      },
      "fees": [],
      "createdAt": "2026-07-08T15:04:05Z",
      "updatedAt": "2026-07-08T15:04:05Z"
    },
    {
      "id": "pay_1a2b3c4d5e6f7a8b",
      "externalId": "invoice-2041",
      "amount": 4200,
      "currency": "USD",
      "originatingAccountId": "acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "receivingAccountId": "acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "deductionDate": "2026-07-09",
      "deliveryPreference": "same-day-ach",
      "deliveryDate": "2026-07-11",
      "status": "completed",
      "metadata": {},
      "fees": [
        {
          "type": "same-day-ach",
          "chargeTo": "originator",
          "percent": {
            "rate": 0.5,
            "max": 3000
          },
          "amount": 21,
          "status": "charged"
        }
      ],
      "tracking": {
        "type": "ach",
        "traceNumber": "021000021234567",
        "sentAt": "2026-07-09T18:30:00Z",
        "clearedAt": "2026-07-11T07:15:00Z"
      },
      "createdAt": "2026-07-07T09:22:00Z",
      "updatedAt": "2026-07-07T09:22:00Z"
    }
  ]
}

Entities

Accounts

Attachments

Payments

Tools

Authorizations

Headers

Query Parameters

Response