Skip to main content
Melio models both sides of a payment as accounts. An internal account is a funding source owned by the entity - the money comes out of it. An external account is a payee’s delivery method - the money goes into it. Every payment links exactly one internal account to one external account.

Ownership types

The ownershipType field indicates which side of the payment the account belongs to:
  • internal - funding sources owned by the entity. Can be an ACH bank account or a card.
  • external - delivery methods for payees. Can be ACH, paper check, domestic wire, virtual card, or counterparty choice (the payee picks the method).

Account types

Counterparty name

External accounts take a counterPartyName. It must follow these rules, or the request returns 400 VALIDATION_ERROR with a message that names the rule (for a disallowed character, the message lists the characters it found):
  • At least 3 characters. The maximum depends on your account; a name that is too long returns the limit in the error.
  • Only unaccented letters (A-Z, a-z), digits, spaces and these symbols: ! " $ % & ' ( ) * + , - . / \ : ; = ? @.
  • Not only digits and punctuation, not an email address, and not test, n/a or new.
Characters that aren’t accepted include # [ ] { } < > | ~ ^ _ and the backtick, accented letters, curly quotes and en or em dashes. Replace them before you send the name:

Account ID

Every account receives an opaque identifier starting with acct_ (for example, acct_7nRv3xBqY5tM). Pass this ID as originatingAccountId (internal) or receivingAccountId (external) when you create a payment. Set externalId if you want to attach your own reference - for example, your internal ledger ID for the bank account. You can filter account list endpoints by externalId to look up accounts without storing Melio IDs. For Plaid-linked bank accounts and card accounts, you cannot collect credentials directly - those flows require a hosted portal. Use POST /accounts/link to generate a short-lived, entity-scoped URL. The body takes a single required field, type: plaid mints a link that runs the Plaid bank-account flow, card mints a link that runs the card flow. You may also pass an optional externalId; the account created through the link is then pinned to it, and the submitter cannot supply a different one.
The response returns the link under data:
Redirect or embed the returned data.url for the entity’s user; the link is no longer usable after expiration. When they complete the flow, Melio creates the account automatically. You can poll GET /accounts or listen for the api.account.created webhook to detect when the account is ready.

Card accounts

Internal card accounts are added through a tokenized card flow rather than the micro-deposit flow used for bank accounts. The card is captured as a vault token along with its BIN, expiry, cardholder name, and billing address, so the raw card number never passes through your servers. A card account is added in one of two ways, both of which feed the same tokenized flow:
  • Hosted card flow - mint a link with POST /accounts/link (type: card). The entity completes card entry on a Melio-hosted page that adds the internal account for them.
  • Direct - approved partners may submit the vaulted card token and its details to POST /accounts themselves.

Which cards are accepted

US-issued debit and credit cards that the card network allows Melio to charge. Prepaid cards and cards issued outside the US aren’t accepted. Whether a specific card is accepted is decided when it’s added, so a card can be refused even if its network is generally supported. A refused card returns 400 CARD_NOT_SUPPORTED. Its message is written for the cardholder, so you can show it as-is. The hosted card page shows the same message.

Test cards

In sandbox, use these test card numbers with any future expiration date and any CVC: Other numbers, including real cards, may be refused in sandbox with CARD_NOT_SUPPORTED. Test with the numbers above.

Bank account verification

The isVerified field reflects whether Melio has confirmed the entity controls the account. It is present only on internal accounts; for external accounts (payees, ownershipType: external) verification does not apply and the field is absent. An internal account is added either through Plaid or, for selected partners only, by supplying the account and routing numbers directly. An internal ACH account may start as isVerified: false and must be verified before you can originate a payment from it. Verification runs through Plaid:
  1. Call POST /accounts/{accountId}/verify/link to get a short-lived, Melio-hosted link.
  2. Hand the link to the entity. It opens a Melio-hosted page where they complete Plaid account verification. This is typically instant when they authenticate with their bank, or micro-deposits as a fallback when instant verification isn’t available or the user selects the micro-deposit flow.
  3. When verification completes, isVerified flips to true. Subscribe to api.account.updated to learn when this happens.
Until isVerified is true, payments cannot be originated from the account.

Counterparty choice accounts

Use a counterparty-choice account when you know only the payee’s name and email. Melio emails the payee an invitation to choose how to get paid and enter their own details.
  • Before the payee responds, you can already pay the account with deliveryPreference: counterparty-choice, the only preference it accepts. The payment is scheduled and waits for the payee.
  • When the payee chooses, the same account (same id) changes type to ach, check or virtual-card, and you receive api.account.updated. Waiting payments move to that rail’s normal-speed preference (standard-ach, standard-check or virtual-card), and you receive api.payment.updated for each.
  • After that, the account works like any other external account of its new type.

Paying before the payee responds

Create the payment right away. You don’t need to hold it on your side: Melio holds it and sends it once the payee provides their details.
  • The originating account is not debited when you create the payment. It is debited only after the payee provides their details. Until then, the payment is scheduled and waits for the payee.
  • The payee may choose a rail other than a bank account, such as a paper check or a virtual card. The payment then goes out on that rail.

Learning that the payee has chosen

When the payee chooses how to get paid, you receive two webhooks, in this order:
  1. api.account.updated for the same account id. The account keeps its id and its type changes to the payee’s choice (for example ach).
  2. api.payment.updated for each payment that was waiting. Each payment now reports that rail’s normal-speed preference (for example standard-ach).
To match the events to your own records, use externalId. Every event also carries id, entityId and entityExternalId (your id for the business). On api.account.updated, externalId is the one you set on the account. On api.payment.updated, it is the payment’s own externalId. Match the payee with the account event, and each payment with its payment event. If several payments are waiting, they all move to the payee’s chosen rail at the same moment, and you receive one api.payment.updated per payment. A payment you create after the payee has chosen is not re-announced: it uses the new rail’s delivery preferences like any other payment.

Fees and delivery dates

Counterparty choice payments are not free. When the payment is created, no fee is charged yet, because the payee hasn’t chosen how to get paid. The fee is calculated once the payee picks a delivery method, and it follows the standard pricing for that method: Until the payee chooses, show the payment’s delivery preference as Pending, along with the possible fees ($0.50 for standard ACH or $1.50 for standard paper check). The payee’s choice decides which fee applies. Delivery may take 3 to 7 business days, depending on how the payee chooses to receive the payment. Once the payee chooses, the payment object shows the final deliveryPreference, deliveryDate and fees for the chosen rail. When you receive api.payment.updated, fetch the payment (GET /payments/{id}) to read them.

Invitation emails

Melio emails the payee an invitation to choose how to get paid twice:
  1. When you create the counterparty choice account.
  2. When you send a payment to that account.
So a payee who hasn’t responded gets a second invitation when you pay them. You can’t trigger the invitation email through the API.