> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# End-to-end walkthrough

> Follow one customer through the full Meridian Accounts flow in Sandbox: open an account, fund it in USD, and pay out in PHP.

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](https://docs.mnai.com/products/meridian-accounts/guides/getting-started.md). For the Sandbox base URL, see [Base URLs](https://docs.mnai.com/products/meridian-accounts/api-reference.md#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](https://docs.mnai.com/products/meridian-accounts/guides/choose-your-integration-model.md).
* **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](https://docs.mnai.com/products/meridian-accounts/guides/server-to-server-authentication-with-hmac.md).

1. **Create the user.** Call [`POST /v1/auth/users`](https://docs.mnai.com/api-reference/auth/create-a-meridian-user-for-a-partner) with your own `externalId`:

   ```json theme={null}
   {
     "type": "BUSINESS",
     "externalId": "customer-1001",
     "business": {
       "legalName": "Acme Trading LLC",
       "contactPhone": "+15551234567",
       "contactEmail": "ops@acme.example"
     }
   }
   ```

   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`](https://docs.mnai.com/api-reference/auth/issue-a-meridian-accounts-access-token) with the `userId` in the `X-Meridian-User-Id` header:

   ```json theme={null}
   { "grant_type": "client_credentials" }
   ```

Send the returned `access_token` as `Authorization: Bearer {token}` on the calls that follow. See [Client-server authentication with JWT](https://docs.mnai.com/products/meridian-accounts/guides/client-server-authentication-with-jwt.md).

## Step 2: Enroll the customer

The account becomes usable once the customer's enrollment reaches `ACTIVE`.

1. **Check the enrollment.** Call [`GET /v1/enrollment`](https://docs.mnai.com/api-reference/enrollment/get-current-enrollment-status). The first call creates the enrollment if none exists.
2. **Activate it.** If the status is `INACTIVE`, call [`POST /v1/enrollment/activate`](https://docs.mnai.com/api-reference/enrollment/activate-a-pending-enrollment). 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](https://docs.mnai.com/products/meridian-accounts/guides/onboarding-your-customer.md) for each call, and [Information we collect](https://docs.mnai.com/products/meridian-accounts/guides/kyb-information.md) for what to gather.

> [!TIP]
>
> 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

> [!WARNING]
>
> 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`](https://docs.mnai.com/api-reference/auth/issue-a-meridian-accounts-access-token) again, as in step 1, and use the new token from here on.
2. Call [`GET /v1/accounts`](https://docs.mnai.com/api-reference/accounts/list-accounts) and take the account `id`.
3. Call [`GET /v1/accounts/{accountId}`](https://docs.mnai.com/api-reference/accounts/get-account-by-id) 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](https://docs.mnai.com/products/meridian-accounts/guides/displaying-account-information.md) for how to show the deposit instructions to your customer.

## Step 4: Fund the account in Sandbox

Call [`POST /v1/accounts/{accountId}/simulate-deposit`](https://docs.mnai.com/api-reference/sandbox/send-a-mock-deposit) with a deposit instruction `id` and an amount:

```json theme={null}
{
  "depositInstructionId": "uspay-rvrsmt8vngju3kea5mm6fcck",
  "amount": "900.00"
}
```

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`](https://docs.mnai.com/api-reference/transactions/list-transactions), or with the [transaction webhook](https://docs.mnai.com/products/meridian-accounts/webhooks/webhooks-transaction.md).

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`.

> [!NOTE]
>
> 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`](https://docs.mnai.com/api-reference/beneficiaries/create-a-beneficiary). One call creates the beneficiary and its bank account. This example registers a contractor's PHP bank account:

```json theme={null}
{
  "type": "PERSON",
  "firstName": "Maria",
  "lastName": "Santos",
  "email": "maria.santos@example.com",
  "relationshipToUser": "THIRD_PARTY",
  "address": {
    "addressLine1": "12 Mabini Street",
    "city": "Makati",
    "stateProvince": "Metro Manila",
    "postalCode": "1200",
    "countryCode": "PH"
  },
  "instrument": {
    "type": "BANK_ACCOUNT",
    "idempotencyKey": "c3d4e5f6-3333-4444-5555-666677778888",
    "bankAccount": {
      "displayName": "Maria PHP savings",
      "accountHolderName": "Maria Santos",
      "currency": "PHP",
      "country": "PH",
      "accountType": "SAVINGS",
      "accountNumber": "1234567890",
      "bankCode": "010999999",
      "bankName": "Example Bank of the Philippines"
    }
  }
}
```

`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`](https://docs.mnai.com/api-reference/beneficiaries/list-beneficiary-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`](https://docs.mnai.com/api-reference/transaction-intents/create-a-transaction-intent):

   ```json theme={null}
   {
     "debitInstrumentId": "uspay-pyj5tywsw7v0pzuyjirxvso2",
     "creditInstrumentId": "uspay-pzrxbd1856x0tyxmdrkzhhml",
     "fixedSide": "DEBIT",
     "amount": "250.00",
     "purpose": "VENDOR_CONTRACTOR_PAYOUTS",
     "idempotencyKey": "payout-2026-11-12-0001",
     "externalId": "payout-2026-11-12-0001"
   }
   ```

   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`](https://docs.mnai.com/api-reference/transaction-intents/commit-a-transaction-intent) with the same `idempotencyKey`:

   ```json theme={null}
   { "idempotencyKey": "payout-2026-11-12-0001" }
   ```

   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](https://docs.mnai.com/products/meridian-accounts/webhooks/webhooks-transaction.md), until it reaches `COMPLETED` or `FAILED`.

See [Making a payout](https://docs.mnai.com/products/meridian-accounts/guides/making-a-withdrawal.md) 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](https://docs.mnai.com/products/meridian-accounts/guides/go-live.md) for the steps to get production credentials.
