Skip to main content
Once a customer’s enrollment is ACTIVE, your integration can begin showing Meridian account information in your UI.

Authentication for account reads

These account-read operations can be performed with a Meridian JWT and, where the API supports direct partner authentication, with HMAC-signed partner credentials. For client-facing account views, prefer JWT bearer authentication so your frontend uses Authorization: Bearer {token} instead of partner credentials. Review Client-server authentication with JWT before implementing frontend-facing account reads. In Meridian Accounts, the account is the customer-facing object to display. It holds the deposit instructions your customer shares with senders, and the funds received.

How to display account information

Use the account and transaction APIs as read models for your UI. At a high level, the display flow is:
1

List the customer's accounts

Call GET /v1/accounts to retrieve the accounts available for the customer in the current program context.
2

Show deposit instructions

Call GET /v1/accounts/{accountId} to retrieve the full account detail and render the deposit instructions your customer can share with a sender. See Deposit instruction labels.
3

Load transaction history

Call GET /v1/transactions to populate the customer’s account activity feed.
4

Show transaction details when needed

Call GET /v1/transactions/{transactionId} when your UI needs the full detail for a selected transaction.

Deposit instruction labels

GET /v1/accounts/{accountId} returns the account’s deposit instructions in depositInstructions. Each one carries the labels to show, so you do not write your own.
Show each deposit instruction as its own block:
  • Heading: rail.label, such as ACH, Fedwire, or SWIFT.
  • Currencies: supportedCurrencies.
  • Rows: every entry in fields, in the order returned, with label beside value. Offer a copy action when copyable is true.
  • Disclosures: the text of every entry in disclosures.
Show the labels as returned. Do not rename, reorder, or drop fields. The fields differ by rail: Fedwire returns “Fedwire routing number” where ACH returns “Routing number”, and SWIFT adds “SWIFT BIC”.

What the account shows

Use the account to show the customer where to send funds, which deposit instructions to share, and the funds held: availableBalance and actualBalance. When a sender uses those deposit instructions, the account receives the incoming funds. The account’s routingPolicy decides what happens next. With RETAIN, the funds stay on the account. With SWEEP, Meridian moves them to the configured credit instrument.

How to interpret transactions

The transaction APIs are designed for display purposes. Treat them as read-only account activity, not as endpoints for creating, editing, or reversing movement. Any funds received into an account result in a DEPOSIT transaction. If the account has a SWEEP routing policy, Meridian also creates a WITHDRAWAL transaction for that same flow. This means your customer may see both:
  • an inbound DEPOSIT into the account
  • a follow-on WITHDRAWAL that moves funds to the configured credit instrument

Telling a sweep from a customer withdrawal

Meridian marks both transactions of a sweep, so you can explain them to your customer:
  • tags includes Auto_sweep on the sweep WITHDRAWAL and on the DEPOSIT that triggered it
  • relatedTransactionId on each one holds the ID of the other
Use type together with tags to show whether the customer is looking at the incoming deposit or at the automatic withdrawal that followed. Your integration should:
  • use the account responses to render shareable deposit instructions and balance amounts
  • present transactions as a ledger or activity feed
  • treat transaction responses as read-only history
  • use transaction type and tags to explain why a movement appears in the account timeline

Next steps

After implementing this flow, review: