Skip to main content
A payout moves funds from a customer’s Meridian balance to a destination you have registered: a bank account, or a wallet address for stablecoin. The API records a payout as a transaction of type 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 the RETAIN 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.
If your program uses SWEEP, funds leave the balance on their own. Contact your Solutions Engineer if you need a RETAIN program.
You also need:
  • an enrollment in ACTIVE status (see Onboarding your customer)
  • an access token for the program context with these scopes: beneficiaries:create and beneficiaries:list to register destinations, accounts:list to find the balance, transactions:create to create and commit intents, and transactions:get or transactions:list to track the payout
  • a funded balance to pay out from

Step 1: Register the destination

Register each destination once with POST /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:
The response returns the beneficiary but not its instrument. Call 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:
  • debitInstrumentId is the balance the funds leave from. Take its id from GET /v1/accounts.
  • creditInstrumentId is 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.
Request
The response is the preview, in CREATED status. creditAmount is debitAmount times exchangeRate, rounded to two decimal places.
Response (201)
No funds have moved. Show the customer 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} with relatedTransactionId
  • GET /v1/transactions?externalId=payout-2026-10-12-0001 with your own reference
  • the transaction webhook, which sends transaction_created when the payout is recorded and transaction_status_updated as it moves to COMPLETED or FAILED

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 returns 400 with the message Quote is expired, create a new intent and commit that one.

Sandbox notes