Skip to main content
This walkthrough joins the guides into one flow. You open an account for a customer, read its deposit instructions, fund it in USD with a simulated deposit, and pay a contractor in the Philippines in PHP. Each step shows the calls to make and links to the guide with the detail.
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. With SINGLE_USER, skip the user creation in step 1 and omit X-Meridian-User-Id. See Choose your integration model.
  • A program with the RETAIN routing policy. With SWEEP, 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 403 with INSUFFICIENT_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.
  1. Create the user. Call POST /v1/auth/users with your own externalId:
    Store the userId it returns. externalId must be unique, so reuse the stored userId for this customer and do not create the user again. type must be the one your program accepts, PERSON or BUSINESS. Meridian rejects the other with 400 and INVALID_USER_TYPE.
  2. Mint a token. Call POST /v1/auth/token with the userId in the X-Meridian-User-Id header:
Send the returned 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 reaches ACTIVE.
  1. Check the enrollment. Call GET /v1/enrollment. The first call creates the enrollment if none exists.
  2. Activate it. If the status is INACTIVE, call POST /v1/enrollment/activate. The response includes latestInformationRequest.
  3. Complete the Information Request. Load it with GET /v1/information-requests/{informationRequestId}. Write values with POST …/data and upload files with POST …/documents. Read it again after each write, and continue until validationStatus is VALID.
  4. Submit it. Call POST /v1/information-requests/{informationRequestId}/submit.
  5. Wait for ACTIVE. Listen for the enrollment_status_updated webhook, or call GET /v1/enrollment again. Meridian reviews the Information Request first. If the enrollment stays INACTIVE in Sandbox, ask your Solutions Engineer to approve the review.
See Onboarding your customer for each call, and Information we collect for what to gather.
In Sandbox, use a new legal name and tax number for each test business. Meridian rejects a duplicate when you submit and reports it in validationErrors. A duplicate that reaches activation leaves the enrollment INACTIVE with the status reason ACTIVATION_REJECTED, even when the Information Request is approved.

Step 3: Read the account

Mint a new access token before this step. A token carries the scopes your customer had when you minted it. One minted before the enrollment was ACTIVE can complete onboarding, but it returns 403 on the account, beneficiary, and transaction calls.
  1. Call POST /v1/auth/token again, as in step 1, and use the new token from here on.
  2. Call GET /v1/accounts and take the account id.
  3. Call GET /v1/accounts/{accountId} for the full detail: depositInstructions, availableBalance, actualBalance, and routingPolicy.
Keep two IDs for the steps that follow:
  • the account id, which is the debitInstrumentId for payouts
  • the id of one entry in depositInstructions, which you need to simulate a deposit
See Displaying account information for how to show the deposit instructions to your customer.

Step 4: Fund the account in Sandbox

Call POST /v1/accounts/{accountId}/simulate-deposit with a deposit instruction id and an amount:
The call returns 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:
  • amount must be less than 1000.00. A larger amount returns 400.
  • depositInstructionId is the id of a deposit instruction, not a rail name such as ACH. An unknown ID returns 404.
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

Call POST /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.
  1. Create the intent. Call POST /v1/transaction-intents:
    The response is a preview in CREATED status. It shows the exchangeRate, the creditAmount in PHP, and any fees. Check them before you continue.
  2. Commit the intent. Call POST /v1/transaction-intents/{transactionIntentId}/commit with the same idempotencyKey:
    The response has the status COMMITTED and a relatedTransactionId. 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 returns 400 with the message Quote is expired, create a new intent and commit that one.
  3. Track the payout. Follow the transaction with GET /v1/transactions/{transactionId}, or with the transaction webhook, until it reaches COMPLETED or FAILED.
See Making a payout for the full responses, and for a USD payout by ACH or a stablecoin payout.

Moving to production

The calls are the same in production, except that you cannot simulate a deposit. See Go live for the steps to get production credentials.