Account Integration Manual

The Account product manual is used by merchant engineering, operations, and reconciliation teams that need to confirm account identity, inspect available balances, and investigate money movement. The Account APIs are primarily read-oriented and should normally be integrated before payout or pay-in workflows go live.

Overview

Use the Account APIs for four operational goals:

1. Confirm which merchant account is being authenticated.
2. Read currently available balances by currency.
3. Investigate deposit and withdrawal activity within a time window.
4. Reconcile final balance movement through ledger records.

If your team only needs one source of truth for financial reconciliation, start with GET /payment/ledger and use deposits or withdrawals as supporting evidence when investigating a specific movement.

Prerequisites

Before integrating the Account APIs, make sure the merchant team has completed the following:

1. Signed in to the Merchant Portal and obtained a valid API credential.
2. Confirmed the correct baseUrl for the target environment.
3. Implemented Authorization: Bearer <apiKey> on all requests.
4. Agreed internally on how balance snapshots, transaction identifiers, and reconciliation exports will be stored on the merchant side.

Integration Workflow

The recommended integration order is:

1. GET /payment/account Use this first to validate that the credential maps to the expected merchant account.
2. GET /payment/accounts Use this when your merchant can operate multiple accounts or when internal tooling needs an account list view.
3. GET /payment/balances Use this to render available balances by currency before enabling payout or treasury operations.
4. GET /payment/deposits Use this when investigating inbound funding events into the merchant account.
5. GET /payment/withdrawals Use this when investigating outbound treasury withdrawals from the merchant account.
6. GET /payment/ledger Use this as the primary feed for reconciliation, finance review, and historical balance movement analysis.

Step-by-step API Mapping

Step 1: Confirm merchant identity

Endpoint: GET /payment/account

Use this endpoint immediately after credential issuance. The purpose is not just connectivity testing. It confirms that the deployed API key belongs to the expected merchant account before your team begins reading balances or moving funds.

What to verify:

1. The returned account identifier matches the merchant configuration in your internal system.
2. Account status and capability fields look correct for the environment you are connecting to.
3. The credential does not accidentally point to another merchant or another business unit.

Step 2: Load the merchant account list

Endpoint: GET /payment/accounts

Use this endpoint when the merchant can hold multiple accounts or when operations tools need a paginated account directory. The endpoint supports:

Query parameter	Purpose
status	Filter by account state, for example active accounts only
limit	Control page size for list views or exports
offset	Paginate through the full result set

Operational guidance:

1. Persist the account identifier and status in merchant-side configuration data.
2. Do not assume the first account in the list is the default operational account.
3. If internal tools cache account lists, refresh them before reconciliation or before enabling new payout flows.

Step 3: Read available balances

Endpoint: GET /payment/balances

Use this endpoint whenever merchant systems need a current balance view before creating payouts or reviewing funding status. The endpoint accepts the optional currency filter, which is useful when:

1. A payout workflow only supports one settlement currency.
2. Operations dashboards focus on a single treasury currency.
3. Automated alerts compare balance thresholds per currency.

Merchant-side recommendations:

1. Store periodic balance snapshots with timestamp and currency.
2. Treat balances as point-in-time values, not as a substitute for ledger reconciliation.
3. Refresh balances before initiating manual payout review or treasury approval workflows.

Step 4: Investigate deposits

Endpoint: GET /payment/deposits

Use this endpoint to investigate incoming funds. Supported filters include:

Query parameter	Purpose
currency	Narrow investigation to a settlement currency
network	Focus on a specific blockchain or transfer rail
status	Filter by deposit state
start_at / end_at	Limit the investigation window
limit / offset	Page through historical results

Use deposits for:

1. Investigating whether expected inbound funds have arrived.
2. Explaining why balances changed between two checkpoints.
3. Supporting customer support or treasury investigations with transaction-level evidence.

Step 5: Investigate withdrawals

Endpoint: GET /payment/withdrawals

This endpoint mirrors the deposit investigation pattern for outbound treasury activity. Supported filters include currency, network, status, start_at, end_at, limit, and offset.

Use withdrawals for:

1. Confirming whether a treasury withdrawal request was executed.
2. Investigating outbound fund movements that changed the merchant balance.
3. Supporting finance and compliance reviews with a filtered export of outbound activity.

Step 6: Reconcile through the ledger

Endpoint: GET /payment/ledger

This is the most important Account endpoint for finance and operations teams. It supports:

Query parameter	Purpose
currency	Reconcile a single currency ledger
record_type	Focus on a movement class such as payout
start_at / end_at	Reconcile a defined accounting window
limit / offset	Page through large ledgers
sort_by	Currently supports created_at
sort_order	Use asc or desc depending on export logic

Recommended practice:

1. Use ascending time order for deterministic replay jobs.
2. Use descending time order for operations dashboards and recent-activity views.
3. Reconcile totals by currency and record type rather than mixing all movement classes into a single balance check.

Field and Reconciliation Notes

The most important fields to persist or compare are:

Field	Why it matters
Account identifier	Confirms the credential is bound to the right merchant account
currency	Required for per-currency balance and ledger reconciliation
amount	Required for finance reporting and movement validation
record_type	Distinguishes payout, pay-in, and other movement classes in the ledger
created_at	Defines event ordering and accounting windows

Recommended merchant data model:

1. Store raw API timestamps as returned by the platform.
2. Convert timestamps for display only after the raw values are saved.
3. Keep reconciliation snapshots separate from real-time dashboard snapshots.

Failure Handling

The Account endpoints are read-only, but failures still need disciplined handling:

1. If GET /payment/account fails, treat the credential or environment mapping as invalid until confirmed.
2. If list endpoints return partial pages, continue with limit and offset rather than assuming data loss.
3. If a reconciliation run fails midway, restart from the last confirmed timestamp or offset boundary.
4. Do not rebuild financial history from balances alone if historical list endpoints are temporarily unavailable.

Go-live Checklist

Before going live with Account operations, verify:

1. Merchant credentials have been validated with GET /payment/account.
2. Balance reads are available in the currencies required by your treasury workflow.
3. Deposit, withdrawal, and ledger polling windows are defined.
4. Your internal reconciliation job can persist currency, amount, record_type, and created_at.
5. Support and finance teams know which internal screen or export uses ledger data as the source of truth.

Developer Resources

1. API Reference
2. OpenAPI JSON
3. Postman Collection
4. Getting Started
5. Authentication