Use cases

Treasury with linked accounts

See balances and statements across the bank accounts you already hold, and make centralised payments from any of them, through one API. This is the API side of Multigate's Automated Treasury Management and Multi-Bank Connector.

Who it's for: corporate enterprises (CFOs, treasurers and finance teams), and banks or financial institutions.

A linked account is a bank account your business already holds at another bank, connected to Multigate. The money stays at your bank: Multigate reads its balance and statements and sends payments from it through your bank.

Architecture

flowchart LR
    api[Your treasury system] --> mg[Multigate API]
    mg -->|bank API credentials| z[(Linked local account<br/>Bank A, NGN)]
    mg -->|bank API credentials| s[(Linked local account<br/>Bank B, NGN)]
    mg -->|SWIFT from your BIC| c[(Linked SWIFT account<br/>Bank C, USD)]
    z --> out([Beneficiaries])
    s --> out
    c --> out
    c -.->|MT940 statements| mg

Local linked accounts (for example NGN) need API credentials that your bank issues to you. Multigate uses them to pay out, read the live balance and pull transactions.
SWIFT linked accounts send payments as SWIFT messages from your bank's BIC (its international bank code). Statements arrive as MT940 files (the standard SWIFT statement format).

Before you start

A sandbox API key, and MG_BASE_URL, MG_API_KEY and MG_CLIENT_ID set as in the Quickstart.
Two people. Linking is maker-checker: one user submits (initiate account linking permission) and a different user approves (approve account linking). Your approver can use the dashboard.
Your API user also needs manage account credentials (to upload bank credentials), view accounts and initiate payment.
For each local account: the bank's signed linking documents (such as an account mandate) and the API credentials your bank issued you.
For SWIFT accounts: Multigate has registered your BIC, and the SWIFT relationship (RMA) between your BIC and the bank is active.

Build plan

Submit a linking request per account

Follow Accounts › Linked accounts:

List banks you can link and note the bank's bankId.
Local accounts: List a bank's linking documents, download each template with Download a linking document, sign it, and upload it with Upload a linking document. Keep each blobName with its templateId.
Submit a linking request with clientUUId = your client ID. Store accountLinking.entityId: it identifies the request.

Approve it with a second user

A different user approves the request in the dashboard or with Approve or decline a linking request:

curl -X PATCH "$MG_BASE_URL/client-service/api/v1/account-linking/Lk3mP8qR2sT6vW9x/status" \
  -H "mp-api-key: $APPROVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "APPROVED" }'

APPROVER_API_KEY is an API key that belongs to the approving API user, not to your submitting API user ("You cannot approve a request that you have raised yourself." otherwise). Choose that user when you generate the key. Your business can have only 2 active keys in all, so approving in the dashboard is often simpler.

Linking sends no webhooks. Track requests with Search linking requests (approvalStatus = PENDING, APPROVED or DECLINED), then find the new account with List accounts ?accountTypes=linked. Its accountNumber is your bank account number. If a request is APPROVED but no linked account appears, contact Multigate.

Upload bank credentials (local accounts)

List bank credential slots with your client ID, and find your bank (isProfiled shows whether credentials are in).
Download a bank credentials template and fill one row per account (10-digit account numbers).
Upload bank credentials and check failedUploads.

This works for your own business's accounts only. Without credentials, a local linked account's payouts wait and its balance shows 0.

See your positions

Total per currency, with each account's balance: Get balances across accounts with your client ID. totalBalance is a JSON number: round it to the currency's decimals.
One account's live balance: Get an account balance.

Linked balances are fetched live from your bank. "0" can mean the bank couldn't be reached: retry before you act on it. SWIFT linked accounts always count as 0 in the consolidated view.

Pay out from a linked account

Call Create a transfer (or Bulk payouts) with the linked account number as sourceAccountNumber, a new uniqueRequestId, and the beneficiary. Your approval rules apply (pending_approval while an approver is needed). Linked-account payouts aren't screened, so otherwise they start at processing.

Local: paid through your bank's API.
SWIFT: sent as a SWIFT payment from your BIC; set chargeType (see Payouts › Which rail is used).

A local payout waits in processing, retried about every 5 minutes, while your bank balance is too low or credentials are missing. No webhook tells you why: keep the account funded and alert on payouts that stay processing.

Pull statements

Use Get account transactions (dates in from and to) or Download a statement (dates in startDate and endDate), set to yesterday. Without dates, local linked accounts return today only. See Balances and statements › Linked accounts.

Data to store

Field	From	Used for
`bankId`, `templateId` and `blobName`	linking bank and document endpoints	Submitting the request
Linking request `entityId` and `ApprovalStatus`	Submit a linking request	Approval and tracking
Linked `accountId` and `accountNumber`	List accounts `?accountTypes=linked`	Balances, payouts, statements
Credential slot `entityId` (`credentialId`)	List bank credential slots	Uploading credentials
Payout `uniqueRequestId` (stored before the call) and `transactionId`	your own, then the transfer response	Matching webhooks and statements

Webhooks to handle

Event	What to do
`transfer` / `transfer_completed`	Mark the payout paid.
`transfer` / `transfer_failed`	Mark it failed; show `responseMessage`.

Linking requests, approvals, new linked accounts and inflows into linked accounts send no webhooks. Poll as described above. Approvers receive a "Bank Account Linking Request" email when a request is submitted.

Reconciliation

Local linked accounts: pull yesterday's Get account transactions (the whole day comes back in one list, without paging) and match payouts by amount and reference. Get an account statement also works, but its opening and closing balances are 0: check closing positions against your bank statement.
SWIFT linked accounts: use Download a statement or Get account transactions (one row per MT940 statement received). Get an account statement doesn't support them.
Payouts that stay processing are the usual unmatched items: check the bank balance and credentials.

Things that trip people up

A declined account can't be requested again at the same bank: contact Multigate.
Money paid into a linked account stays at your bank; Multigate processes no inflows for it.
Bank credentials can't be uploaded for customers' linked accounts today.
Get account transactions answers 200 with an empty list when transactions can't be loaded: retry before concluding there were none.

Go-live notes

Re-link and re-upload credentials in production: sandbox links and credentials don't carry over.
For SWIFT, confirm with Multigate that your BIC is registered and each RMA is active before submitting.
Set alerts on linked-account payouts that stay processing, and on balances of 0.
Work through the go-live checklist.