1
Create the user and an access token
Create a Meridian user for your customer, then mint a token for them.
2
Enroll the customer
Activate the enrollment and complete the Information Request.
3
Read the account
Get the account, its balances, and its deposit instructions.
4
Fund the account in Sandbox
Simulate a deposit.
5
Register the destination
Create a beneficiary with a PHP bank account to pay out to.
6
Pay out in PHP
Create a transaction intent, commit it, and track the payout.
Before you start
You need:- Sandbox credentials. Your API Key, Secret, and Program ID. See Getting started. For the Sandbox base URL, see Base URLs.
- An integration model. This walkthrough uses
MULTI_USER. WithSINGLE_USER, skip the user creation in step 1 and omitX-Meridian-User-Id. See Choose your integration model. - A program with the
RETAINrouting policy. WithSWEEP, Meridian forwards every deposit to a preset destination, so no funds stay on the account to pay out. Ask your Solutions Engineer which policy your program uses. - A program set up for payouts. Meridian sets what your program can do, and each token carries scopes to match. A call your program does not allow returns
403withINSUFFICIENT_SCOPE, and the message lists the missing scopes. Ask your Solutions Engineer to enable them.
Step 1: Create the user and an access token
Sign both calls with your partner credentials. See Server-to-server authentication with HMAC.-
Create the user. Call
POST /v1/auth/userswith your ownexternalId:Store theuserIdit returns.externalIdmust be unique, so reuse the storeduserIdfor this customer and do not create the user again.typemust be the one your program accepts,PERSONorBUSINESS. Meridian rejects the other with400andINVALID_USER_TYPE. -
Mint a token. Call
POST /v1/auth/tokenwith theuserIdin theX-Meridian-User-Idheader:
access_token as Authorization: Bearer {token} on the calls that follow. See Client-server authentication with JWT.
Step 2: Enroll the customer
The account becomes usable once the customer’s enrollment reachesACTIVE.
- Check the enrollment. Call
GET /v1/enrollment. The first call creates the enrollment if none exists. - Activate it. If the status is
INACTIVE, callPOST /v1/enrollment/activate. The response includeslatestInformationRequest. - Complete the Information Request. Load it with
GET /v1/information-requests/{informationRequestId}. Write values withPOST …/dataand upload files withPOST …/documents. Read it again after each write, and continue untilvalidationStatusisVALID. - Submit it. Call
POST /v1/information-requests/{informationRequestId}/submit. - Wait for
ACTIVE. Listen for theenrollment_status_updatedwebhook, or callGET /v1/enrollmentagain. Meridian reviews the Information Request first. If the enrollment staysINACTIVEin Sandbox, ask your Solutions Engineer to approve the review.
Step 3: Read the account
- Call
POST /v1/auth/tokenagain, as in step 1, and use the new token from here on. - Call
GET /v1/accountsand take the accountid. - Call
GET /v1/accounts/{accountId}for the full detail:depositInstructions,availableBalance,actualBalance, androutingPolicy.
- the account
id, which is thedebitInstrumentIdfor payouts - the
idof one entry indepositInstructions, which you need to simulate a deposit
Step 4: Fund the account in Sandbox
CallPOST /v1/accounts/{accountId}/simulate-deposit with a deposit instruction id and an amount:
202 with an empty body, and the deposit settles shortly after. Confirm it with GET /v1/accounts/{accountId}, with GET /v1/transactions, or with the transaction webhook.
Two rules apply:
amountmust be less than1000.00. A larger amount returns400.depositInstructionIdis theidof a deposit instruction, not a rail name such asACH. An unknown ID returns404.
This endpoint exists only in Sandbox. In production, the account is funded when a sender pays to its deposit instructions.
Step 5: Register the destination
CallPOST /v1/beneficiaries. One call creates the beneficiary and its bank account. This example registers a contractor’s PHP bank account:
relationshipToUser is THIRD_PARTY because the account belongs to someone other than your customer. Your agreement with Meridian sets which relationships your program may register.
The response returns the beneficiary but not its bank account. Call GET /v1/beneficiaries/{beneficiaryId}/instruments and take the instrument id. That is the creditInstrumentId for payouts.
Step 6: Pay out in PHP
A payout has two calls. The first prices it and moves no funds. The second moves the funds.-
Create the intent. Call
POST /v1/transaction-intents:The response is a preview inCREATEDstatus. It shows theexchangeRate, thecreditAmountin PHP, and anyfees. Check them before you continue. -
Commit the intent. Call
POST /v1/transaction-intents/{transactionIntentId}/commitwith the sameidempotencyKey:The response has the statusCOMMITTEDand arelatedTransactionId. Committing again with the same key returns the same result and never creates a second transaction. The quote does not stay valid for long, so commit soon after the preview. If the commit returns400with the messageQuote is expired, create a new intent and commit that one. -
Track the payout. Follow the transaction with
GET /v1/transactions/{transactionId}, or with the transaction webhook, until it reachesCOMPLETEDorFAILED.