Platform overview

How the pieces of the Multigate platform fit together, and the objects you work with through the API. Wallets, virtual accounts, collections, FX conversions and payouts make up Multigate's Cross-border Financial Infrastructure. Linked accounts, with their consolidated balances, statements and payments, bring Automated Treasury Management (the Multi-Bank Connector) to the same API. Trade finance adds letters of credit and bank guarantees, exchanged with banks over SWIFT.

The core objects

Everything you do with the API creates or changes one of these objects.

erDiagram
    CLIENT ||--o{ CUSTOMER : "onboards"
    CLIENT ||--o{ ACCOUNT : "owns"
    CUSTOMER ||--o{ ACCOUNT : "owns"
    ACCOUNT ||--o{ VIRTUAL_ACCOUNT : "is reached through"
    CLIENT ||--o{ LINKED_ACCOUNT : "connects"
    ACCOUNT ||--o{ INFLOW : "receives"
    ACCOUNT ||--o{ TRANSFER : "funds"
    BENEFICIARY ||--o{ TRANSFER : "receives"
    CLIENT ||--o{ BENEFICIARY : "saves"
    ACCOUNT ||--o{ CONVERSION : "source or target of"

Account types

Every account has an accountType: wallet, viban (virtual account), linked or receivable. You may also see corporate, multigate or tsa on special-purpose accounts that Multigate sets up. See Accounts for how to open, link and use each type.

Which ID goes where

Newcomers most often mix up these identifiers. Each one comes from a specific response.

How money moves

flowchart LR
    payer([Payer]) -->|bank transfer| va[Virtual account]
    va -->|inflow, screened| wallet[(Wallet balance)]
    wallet -->|conversion| wallet2[(Wallet in another currency)]
    wallet -->|transfer| rails{{Local rails or SWIFT}}
    wallet2 -->|transfer| rails
    rails --> beneficiary([Beneficiary])

1. Money in. A payer sends money to a virtual account. Multigate screens the inflow, credits the wallet, and sends you an account / inflow webhook.
2. Hold and convert. Balances sit in wallets on the Multigate ledger (Multigate's record of every balance and every movement). You can convert between your wallets with a locked FX rate.
3. Money out. You create a transfer. Multigate checks the balance, screens the payment, applies your approval rules, picks the rail, and pays the beneficiary. You get a transfer / transfer_completed or transfer_failed webhook.

Asynchronous by design

Bank payments don't finish instantly. When you create a transfer, the API answers straight away with the transfer in a non-final status such as pending or processing. The final outcome arrives later:

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate API
    participant Rail as Bank or partner
    You->>MG: POST create transfer (uniqueRequestId)
    MG-->>You: 200 OK, status pending or processing
    MG->>Rail: Send payment
    Rail-->>MG: Payment result (seconds to days)
    MG-)You: Webhook transfer_completed or transfer_failed
    You->>MG: GET transfer (optional check)
    MG-->>You: Final status

Build your integration around this:

• Treat webhooks as the source of truth for final outcomes, and verify their signatures. See Webhooks.
• Poll as a backup, not as the main mechanism. A few outcomes (for example a payment declined by your approver) don't send a webhook, so check the status of anything that hasn't reached a final status within the time you expect.
• A timeout is not a failure. If a request times out, look the object up by your uniqueRequestId before retrying. See Idempotency.

Request and response conventions

• Base URLs: https://api-gateway-uat.mmacs.io/platform (sandbox) and https://api-gateway.mmacs.io/platform (production), followed by the service path, for example /payment-service/api/v1/transfer/single-transfer.
• Requests: JSON bodies up to 1 MB, with Content-Type: application/json and your API key in the mp-api-key header (see Authentication). File uploads use multipart/form-data. Fields an endpoint doesn't define are dropped, not rejected.
• Success: always HTTP 200, with the object at the top level of the body (no data wrapper), except remittances, which nest it under data. Most bodies also carry a message, a human-readable text you can ignore.
• Lists: paged; see Pagination.
• Errors: one of four JSON shapes; see Errors.
• Amounts are in major units; timestamps are ISO 8601 in UTC. See Amounts and currencies.
• Time limit: the gateway stops waiting after 60 seconds and answers 502 or 504. For a money-moving request, that outcome is unknown: look it up before retrying.
• Rate limits: API calls have no request rate limit today. Keep a modest number of requests in flight and back off on 5xx.

Acting for your customers

Most endpoints work for your own business by default. To act for a customer, pass the customer's ID in onBehalfOf (in the body or query, depending on the endpoint). Multigate checks that the customer belongs to you. See Acting for your customers.

Approvals and compliance

Multigate applies controls before any money moves:

• Balance checks. Just before a transfer is debited (after approval and screening), Multigate checks that the source account's available balance covers the amount plus fees. If it doesn't, the transfer ends failed (responseCode 22) with a transfer_failed webhook, and nothing is debited. For a large NGN transfer that is split, or a linked-account source, the balance is checked when you create it instead (400). Validate a transfer checks the balance up front.
• Compliance screening. Payouts from your Multigate wallets, remittances and refunds are screened against Multigate's compliance rules before they are paid out; payouts from linked accounts skip this step. While a payout is screened it stays pending; once it clears, it moves to processing. A payment that needs a closer look is held for Multigate's compliance team: it stays pending until they decide. If compliance declines it, it ends failed with responseCode 43, nothing is debited, and no webhook is sent. Incoming payments are screened before they are credited; the inflow webhook is sent after the credit.
• Customer checks. Customers of type client are screened when you submit them, and reviewed by Multigate compliance if anything needs attention. Countries Multigate can't serve are refused for every customer.
• Approvals (maker-checker). If your API user isn't allowed to approve its own payments, a transfer it creates waits in pending_approval until an approver in your business approves it in the dashboard. Ask us to give your API user both the initiate and approve payment permissions if payments should go straight to processing.

See Payouts for every status and what to do in each.