Skip to main content
Once a customer’s enrollment is ACTIVE, your integration can begin showing Meridian balance 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 balance is the customer-facing object to display. It represents how your customer receives local payments. Its schema is designed to present deposit instructions that can be shared with senders.

​
How to display account information

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

List the customer's balances

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

Show deposit instructions

Call GET /v1/balances/{balanceId} to retrieve the full balance detail and render the deposit instructions your customer can share with a sender.
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.

​
What the balance represents

The balance is meant for display in your UI. Use it to show the customer where to send funds, which deposit instructions to share, and what funds are available versus actual. When a sender uses those deposit instructions, the balance receives the incoming funds. Depending on how that balance is configured, the deposited funds may either remain on the balance or trigger a follow-on sweep 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 a balance result in a deposit transaction. If the balance is configured with a SWEEP routing policy, Meridian may also initiate a subsequent withdrawal transaction for that same flow. This means your customer may see both:
  • an inbound deposit into the balance
  • a follow-on withdrawal that moves funds to the configured credit instrument

​
Using sourceType to explain what happened

The sourceType on a transaction helps explain what caused that transaction. For now, your integration should interpret:
  • DEPOSIT_INSTRUCTION as activity directly associated with a balance deposit instruction
  • ROUTING_POLICY as follow-on movement that Meridian initiated automatically from the balance routing policy
Use type together with sourceType to help the customer understand whether they are looking at the incoming deposit or at a subsequent automatic withdrawal. Your integration should:
  • use the balance 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 sourceType to explain why a movement appears in the account timeline

​
Next steps

After implementing this flow, review: