Create a payment

POST

payments

Create a payment

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'Melio-Entity-Id': '<melio-entity-id>',
    'api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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',
    compliance: {type: 'goods-and-services'},
    externalId: 'invoice-2043',
    noteToRecipient: 'July materials order',
    metadata: {invoiceId: 'INV-2043', department: 'operations'}
  })
};

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"

payload = {
    "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",
    "compliance": { "type": "goods-and-services" },
    "externalId": "invoice-2043",
    "noteToRecipient": "July materials order",
    "metadata": {
        "invoiceId": "INV-2043",
        "department": "operations"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Melio-Entity-Id": "<melio-entity-id>",
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request POST \
  --url https://api.melio.com/v2/payments \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Melio-Entity-Id: <melio-entity-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "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",
  "compliance": {
    "type": "goods-and-services"
  },
  "externalId": "invoice-2043",
  "noteToRecipient": "July materials order",
  "metadata": {
    "invoiceId": "INV-2043",
    "department": "operations"
  }
}
'

HttpResponse<String> response = Unirest.post("https://api.melio.com/v2/payments")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Melio-Entity-Id", "<melio-entity-id>")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 125000,\n  \"currency\": \"USD\",\n  \"originatingAccountId\": \"acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"receivingAccountId\": \"acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n  \"deductionDate\": \"2026-07-10\",\n  \"deliveryPreference\": \"standard-ach\",\n  \"compliance\": {\n    \"type\": \"goods-and-services\"\n  },\n  \"externalId\": \"invoice-2043\",\n  \"noteToRecipient\": \"July materials order\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\",\n    \"department\": \"operations\"\n  }\n}")
  .asString();

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::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Melio-Entity-Id"] = '<melio-entity-id>'
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 125000,\n  \"currency\": \"USD\",\n  \"originatingAccountId\": \"acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"receivingAccountId\": \"acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n  \"deductionDate\": \"2026-07-10\",\n  \"deliveryPreference\": \"standard-ach\",\n  \"compliance\": {\n    \"type\": \"goods-and-services\"\n  },\n  \"externalId\": \"invoice-2043\",\n  \"noteToRecipient\": \"July materials order\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\",\n    \"department\": \"operations\"\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"

	payload := strings.NewReader("{\n  \"amount\": 125000,\n  \"currency\": \"USD\",\n  \"originatingAccountId\": \"acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"receivingAccountId\": \"acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n  \"deductionDate\": \"2026-07-10\",\n  \"deliveryPreference\": \"standard-ach\",\n  \"compliance\": {\n    \"type\": \"goods-and-services\"\n  },\n  \"externalId\": \"invoice-2043\",\n  \"noteToRecipient\": \"July materials order\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\",\n    \"department\": \"operations\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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",
  "deliveryDate": "2026-07-14",
  "status": "scheduled",
  "noteToRecipient": "July materials order",
  "metadata": {
    "invoiceId": "INV-2043",
    "department": "operations"
  },
  "createdAt": "2026-07-08T15:04:05Z",
  "updatedAt": "2026-07-08T15:04:05Z"
}

{
  "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": {
    "type": "conflict_error",
    "code": "DUPLICATE_EXTERNAL_ID",
    "message": "A payment with externalId 'invoice-2043' already exists."
  }
}

Authorizations

api-key

string

header

required

Headers

Idempotency-Key

string

required

Required unique key (UUID recommended) that makes payment creation safe to retry by replaying the original response; retained 24h per partner, omitting it returns 400.

Maximum string length: 255

Melio-Sonar-Token

string

Signed MelioSonar session token from the initiating device, used for risk evaluation; invalid or expired tokens return 403.

Melio-Entity-Id

string

required

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

Body

application/json

amount

integer

required

Minor units (cents)

originatingAccountId

string

required

Internal originating account id (acct_), the debit account

receivingAccountId

string

required

External receiving account id (acct_), the credit account

deductionDate

string<date>

required

deliveryPreference

enum<string>

required

Required, and explicit about the receiving rail. Pick the normal-speed value that matches the receiving external account (standard-ach, standard-check, domestic-wire, virtual-card). The faster variants, same-day-ach / rtp (ach), express-check / overnight-check (check), instant-domestic-wire (domestic-wire), and instant-virtual-card (virtual-card), require an ACH originating account and pass a per-payment eligibility check. The preference's rail must match the receiving external account, otherwise the request is rejected with 400; a faster variant that is ineligible for the payment is likewise rejected with 400 (never silently downgraded).

Available options:

standard-ach,

same-day-ach,

rtp,

standard-check,

express-check,

overnight-check,

domestic-wire,

instant-domestic-wire,

virtual-card,

instant-virtual-card

compliance

object

required

Compliance details, discriminated by type. Only goods-and-services is supported today; future payment types (internal money movement, mass payouts) will add their own variants with different fields.

Hide child attributes

compliance.type

enum<string>

required

Available options:

goods-and-services

compliance.goodsReceived

boolean

The payer confirms the goods or services were received. Required to be true for payments above $3,000 (amount greater than 300000 minor units).

compliance.merchantCategoryCode

string

The counterparty's 4-digit MCC (merchant category code). Required when the originating account is a card.

Pattern: ^\d{4}$

currency

string

default:USD

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

Payment created.

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

Create a payment

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'Melio-Entity-Id': '<melio-entity-id>',
    'api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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',
    compliance: {type: 'goods-and-services'},
    externalId: 'invoice-2043',
    noteToRecipient: 'July materials order',
    metadata: {invoiceId: 'INV-2043', department: 'operations'}
  })
};

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"

payload = {
    "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",
    "compliance": { "type": "goods-and-services" },
    "externalId": "invoice-2043",
    "noteToRecipient": "July materials order",
    "metadata": {
        "invoiceId": "INV-2043",
        "department": "operations"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Melio-Entity-Id": "<melio-entity-id>",
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request POST \
  --url https://api.melio.com/v2/payments \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Melio-Entity-Id: <melio-entity-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "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",
  "compliance": {
    "type": "goods-and-services"
  },
  "externalId": "invoice-2043",
  "noteToRecipient": "July materials order",
  "metadata": {
    "invoiceId": "INV-2043",
    "department": "operations"
  }
}
'

HttpResponse<String> response = Unirest.post("https://api.melio.com/v2/payments")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Melio-Entity-Id", "<melio-entity-id>")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 125000,\n  \"currency\": \"USD\",\n  \"originatingAccountId\": \"acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"receivingAccountId\": \"acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n  \"deductionDate\": \"2026-07-10\",\n  \"deliveryPreference\": \"standard-ach\",\n  \"compliance\": {\n    \"type\": \"goods-and-services\"\n  },\n  \"externalId\": \"invoice-2043\",\n  \"noteToRecipient\": \"July materials order\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\",\n    \"department\": \"operations\"\n  }\n}")
  .asString();

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::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Melio-Entity-Id"] = '<melio-entity-id>'
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 125000,\n  \"currency\": \"USD\",\n  \"originatingAccountId\": \"acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"receivingAccountId\": \"acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n  \"deductionDate\": \"2026-07-10\",\n  \"deliveryPreference\": \"standard-ach\",\n  \"compliance\": {\n    \"type\": \"goods-and-services\"\n  },\n  \"externalId\": \"invoice-2043\",\n  \"noteToRecipient\": \"July materials order\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\",\n    \"department\": \"operations\"\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"

	payload := strings.NewReader("{\n  \"amount\": 125000,\n  \"currency\": \"USD\",\n  \"originatingAccountId\": \"acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"receivingAccountId\": \"acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n  \"deductionDate\": \"2026-07-10\",\n  \"deliveryPreference\": \"standard-ach\",\n  \"compliance\": {\n    \"type\": \"goods-and-services\"\n  },\n  \"externalId\": \"invoice-2043\",\n  \"noteToRecipient\": \"July materials order\",\n  \"metadata\": {\n    \"invoiceId\": \"INV-2043\",\n    \"department\": \"operations\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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",
  "deliveryDate": "2026-07-14",
  "status": "scheduled",
  "noteToRecipient": "July materials order",
  "metadata": {
    "invoiceId": "INV-2043",
    "department": "operations"
  },
  "createdAt": "2026-07-08T15:04:05Z",
  "updatedAt": "2026-07-08T15:04:05Z"
}

{
  "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": {
    "type": "conflict_error",
    "code": "DUPLICATE_EXTERNAL_ID",
    "message": "A payment with externalId 'invoice-2043' already exists."
  }
}

Entities

Accounts

Payments

Tools

Webhooks

Authorizations

Headers

Body

Response