Quickstart: send your first payout

In about 10 minutes, you’ll send a test payout from USD to INR in the Meridian sandbox and confirm that it arrived. No real money moves.

Writing sample. I wrote this for my portfolio. “Meridian” is a fictional company, and this is not any employer’s documentation.

What you’ll build

Your server ──(1) token──▶ Meridian
            ──(2) quote──▶ Meridian
            ──(3) payout─▶ Meridian ──▶ recipient's wallet
            ◀─(4) webhook── Meridian   "payout.updated: completed"

Prerequisites

A Meridian sandbox account. Signing up takes about two minutes.
Your sandbox client ID and client secret, from Dashboard → Developers → API keys.
curl, or any HTTP client such as Postman.

Step 1: Get an access token

Exchange your client credentials for an access token:

curl https://sandbox.meridian.example/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=quotes:write payouts:write"

Copy the access_token value from the response. You’ll use it in every request that follows.

export ACCESS_TOKEN="<paste your token>"

Step 2: Create a quote

A quote locks the exchange rate for 60 seconds. Ask for a quote to send $500.00 to India:

curl https://sandbox.meridian.example/v1/quotes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "source_currency": "USD", "source_amount": 50000, "destination_currency": "INR" }'

Note the id in the response, for example qt_8Hk2nQ.

✓

Checkpoint: the response includes "destination_amount". That’s exactly what your recipient will receive.

Step 3: Send the payout

The sandbox includes a test recipient, rcp_test_india_upi. Send the payout within 60 seconds of creating the quote:

curl https://sandbox.meridian.example/v1/payouts \
  -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "quote_id": "qt_8Hk2nQ", "recipient_id": "rcp_test_india_upi", "purpose": "family_support" }'

You get a payout with "status": "pending".

Step 4: Confirm it arrived

In the sandbox, payouts complete after about 10 seconds. Check the status:

curl https://sandbox.meridian.example/v1/payouts/po_7Qe93LmA \
  -H "Authorization: Bearer $ACCESS_TOKEN"

When status is completed, you’re done. 🎉

→

In production, don’t poll. Subscribe to the payout.updated webhook in Dashboard → Developers → Webhooks, and Meridian will notify you when the status changes.

Troubleshooting

You see	Likely cause	Fix
`401 invalid_client`	Wrong client ID or secret, or production keys used in the sandbox	Copy the sandbox keys again from the dashboard.
`400 quote_expired`	More than 60 seconds passed between steps 2 and 3	Run step 2 again, then step 3 straight away.
Status stays `pending`	The sandbox is running compliance simulations	Wait 30 seconds. If it’s still pending, contact support.

Next steps

Read the Create a payout reference for every parameter and error.
Before going live, complete the go-live checklist: production keys, webhook signature checks, and idempotency on every retry.

Was this page helpful?