WITHDRAWAL.
A payout has four steps:
1
Register the destination
Create a beneficiary with a payout instrument. You do this once per destination.
2
Create a transaction intent
Price the payout and get a preview. No funds move.
3
Commit the intent
Create the transaction and move the funds.
4
Track the payout
Follow the transaction to completion through the API or webhooks.
Prerequisites
Your program must use theRETAIN routing policy. The policy is set during enrollment and decides what happens to funds when they arrive:
RETAIN: deposits stay on the balance until you move them. This is what makes payouts possible.SWEEP: Meridian forwards every deposit to a preconfigured destination. There is nothing to trigger, and this guide does not apply.
- an enrollment in
ACTIVEstatus (see Onboarding your customer) - an access token for the program context with these scopes:
beneficiaries:createandbeneficiaries:listto register destinations,accounts:listto find the balance,transactions:createto create and commit intents, andtransactions:getortransactions:listto track the payout - a funded balance to pay out from
Step 1: Register the destination
Register each destination once withPOST /v1/beneficiaries. One call creates the beneficiary and its first payout instrument. The request is the same for every kind of destination except for instrument:
- Bank account (PHP)
- Bank account (USD)
- Wallet (USDC)
GET /v1/beneficiaries/{beneficiaryId}/instruments and take the instrument id. That is the creditInstrumentId for every payout to this destination.
GET /v1/beneficiaries/{beneficiaryId}/instruments
relationshipToUser is SELF for the customer’s own account or wallet, and THIRD_PARTY for anyone else. Your agreement with Meridian sets which beneficiary types and relationships your program may register. Confirm this before you build, since it decides who your customers can pay.Step 2: Create the intent
POST /v1/transaction-intents prices the payout and returns a preview. No funds move. It needs two instrument IDs:
debitInstrumentIdis the balance the funds leave from. Take itsidfromGET /v1/accounts.creditInstrumentIdis the beneficiary instrument from Step 1.
fixedSide says which side amount applies to: DEBIT for what leaves the balance, CREDIT for what the destination receives. amount is a decimal string. idempotencyKey is your unique key for this payout, and you send it again to commit. creditRail, externalId, purpose, and memo are optional; see the API reference for each.
- USD to PHP
- USD to USDC
- USD to USD (ACH)
Request
CREATED status. creditAmount is debitAmount times exchangeRate, rounded to two decimal places.Response (201)
debitAmount, creditAmount, exchangeRate, and fees, and keep the id for the commit.
Step 3: Commit the intent
POST /v1/transaction-intents/{transactionIntentId}/commit moves the funds. Send the same idempotencyKey you used to create the intent:
Request
Response (200)
relatedTransactionId is the transaction Meridian created. Committing the same intent again with the same key returns the same result and never creates a second transaction.
Step 4: Track the payout
Follow the transaction, not the intent:GET /v1/transactions/{transactionId}withrelatedTransactionIdGET /v1/transactions?externalId=payout-2026-10-12-0001with your own reference- the transaction webhook, which sends
transaction_createdwhen the payout is recorded andtransaction_status_updatedas it moves toCOMPLETEDorFAILED
Quotes expire
An intent holds a quoted exchange rate, so it does not stay valid for long. The API does not return the expiry time, so commit as soon as the customer confirms. If the commit returns400 with the message Quote is expired, create a new intent and commit that one.
Sandbox notes
- Fund the balance with a simulated deposit of less than $1,000. See Fund the account in Sandbox.
- For the full flow from opening an account to this payout, see the End-to-end walkthrough.