Ownership types
TheownershipType 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 acounterPartyName. 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/aornew.
# [ ] { } < > | ~ ^ _ 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 withacct_ (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.
Scoped link flow
For Plaid-linked bank accounts and card accounts, you cannot collect credentials directly - those flows require a hosted portal. UsePOST /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.
data:
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 /accountsthemselves.
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 returns400 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
TheisVerified 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:
- Call
POST /accounts/{accountId}/verify/linkto get a short-lived, Melio-hosted link. - 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.
- When verification completes,
isVerifiedflips totrue. Subscribe toapi.account.updatedto learn when this happens.
isVerified is true, payments cannot be originated from the account.
Counterparty choice accounts
Use acounterparty-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) changestypetoach,checkorvirtual-card, and you receiveapi.account.updated. Waiting payments move to that rail’s normal-speed preference (standard-ach,standard-checkorvirtual-card), and you receiveapi.payment.updatedfor 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:api.account.updatedfor the same accountid. The account keeps itsidand itstypechanges to the payee’s choice (for exampleach).api.payment.updatedfor each payment that was waiting. Each payment now reports that rail’s normal-speed preference (for examplestandard-ach).
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:- When you create the counterparty choice account.
- When you send a payment to that account.