Receivables

A receivable is an invoice you register with Multigate. Each one gets its own virtual account, and every payment into that account is matched to the invoice automatically, including partial payments and overpayments.

When to use it

Use receivables when you issue invoices and want to stop reconciling payments by hand: a payment is matched by the account it was paid into, not by its narration or amount. For general collections, use a regular virtual account.

In short: create the receivable, wait until it has an account, give that account to the payer, and receive a webhook for each payment.

Before you start

• MG_BASE_URL and MG_API_KEY are set, as in the Quickstart.
• Set-up by Multigate, per currency: a receivable pool account (where collected money is credited) and a receiving bank that supports receivables. Without them, creating a receivable fails with 400.
• An active business. Receivables are for your own business; there is no onBehalfOf.
• An API user with the create receivables permission (can_create_receivables, to create) and view receivables (can_view_receivables, to read and report).
• A webhook URL, to receive receivables / inflow. See Webhooks.

How it works

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant Payer
    You->>MG: POST /receivables (invoiceRef, amount, dueDate, uniqueRequestId)
    MG-->>You: 200, status processing, fundingDetails empty
    Note over MG: Account opened in the background
    loop Until status is unpaid or failed
        You->>MG: GET /receivables/{entityId}
        MG-->>You: status, fundingDetails
    end
    You->>Payer: Invoice with the account in fundingDetails
    Payer->>MG: Pays (one or several transfers)
    MG-)You: receivables / inflow (invoice status, amountPaid)
    MG-)You: account / inflow and a Payment Received email

export MG_REQUEST_ID=$(uuidgen | tr 'A-Z' 'a-z')
curl -s -X POST "$MG_BASE_URL/client-service/api/v1/receivables" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "invoiceRef": "INV-2026-0042",
  "amount": 500000,
  "currencyIso3Code": "NGN",
  "payer": "Kola Stores Ltd",
  "issueDate": "2026-10-01",
  "dueDate": "2026-10-31",
  "uniqueRequestId": "$MG_REQUEST_ID"
}
EOF

{
  "message": "Receivable created successfully",
  "entityId": "Rc7mT2qL9xV4nB8kD1sFa",
  "invoiceRef": "INV-2026-0042",
  "amount": 500000,
  "amountPaid": 0,
  "currencyIso3Code": "NGN",
  "payer": "Kola Stores Ltd",
  "issueDate": "2026-10-01T00:00:00.000Z",
  "dueDate": "2026-10-31T00:00:00.000Z",
  "paidDate": null,
  "uniqueRequestId": "4f6a0e1c-2b3d-4e5f-8a9b-0c1d2e3f4a5b",
  "status": "processing",
  "fundingDetails": []
}

for i in $(seq 1 30); do
  STATUS=$(curl -s "$MG_BASE_URL/client-service/api/v1/receivables/$MG_RECEIVABLE_ID" \
    -H "mp-api-key: $MG_API_KEY" | jq -r .status)
  echo "$STATUS"
  [ "$STATUS" != "processing" ] && break
  sleep 10
done

{
  "header": { "notification_type": "receivables", "notification": "inflow", "hash": "5a6b7c8d…" },
  "body": {
    "receivableDetails": {
      "entityId": "Rc7mT2qL9xV4nB8kD1sFa",
      "invoiceRef": "INV-2026-0042",
      "amount": 500000,
      "amountPaid": 200000,
      "currencyIso3Code": "NGN",
      "uniqueRequestId": "4f6a0e1c-2b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "status": "partially_paid",
      "paidDate": null
    },
    "transactionDetails": {
      "transactionId": "IN-261012-0930151234",
      "amount": 200000,
      "senderAccountName": "KOLA STORES LTD",
      "narration": "INV-2026-0042 part",
      "transactionDate": "2026-10-12T09:30:15.000Z"
    }
  }
}

How payments are matched

• By account. Any payment into the receivable's account counts towards that invoice, whatever its narration, sender or amount.
• Running total. Each payment adds to amountPaid. paid means the total equals amount; overpaid means it's more.
• Once per inflow. A payment is recorded once, even if Multigate receives the bank's notification twice.
• Where the money goes. Payments are credited to your receivable pool account for that currency. Collection fees apply as for any other inflow.
• After paid or overpaid, Multigate closes the account with the bank. A payment that still arrives before the closure takes effect is added to the total and the status becomes overpaid, but that money stays in the receivable's own account instead of your pool account. Contact Multigate to have it moved.

Receivable statuses

stateDiagram-v2
    direction LR
    [*] --> processing: created
    processing --> unpaid: account ready
    processing --> failed: account couldn't be opened
    unpaid --> partially_paid: part paid
    partially_paid --> partially_paid: more paid
    unpaid --> paid: paid in full
    partially_paid --> paid: paid in full
    unpaid --> overpaid: paid more
    partially_paid --> overpaid: paid more
    paid --> overpaid: late extra payment
    paid --> [*]
    overpaid --> [*]
    failed --> [*]

Webhooks and emails

Receivables aren't reported to any third party.

Reporting

• List receivables: newest first, filtered by status and currencies. The response has count (items on this page) and totalCount, not the usual paging fields.
• Get a receivables summary: totals invoiced (by creation date) and collected (by payment date) per currency, for all time or a date range.
• Get receivables history: the same totals per month, for the current month and the 5 before it.

Errors and recovery

Next steps

• Invoice collections: an end-to-end example.
• Event catalogue: the receivables / inflow payload.
• Balances and statements: see collected money in your pool account.