# Status lifecycles

Every status you can see, in one place: what it means, whether it's **final** (it will never change again) and whether a webhook tells you about it. Each section links to the product guide with the full details.

:::note[Timings differ in the sandbox]
Statuses and transitions are the same in both environments, but non-final statuses last much longer in the sandbox: payouts can stay `processing` for 15 minutes or more, and customers `processing` for days. See [Sandbox vs production](../01-get-started/05-sandbox-vs-production.md).
:::

:::warning[Some final statuses send no webhook]
Wherever the Webhook column says "—" or "None", poll the object until it's final. Never wait for a webhook alone.
:::

## Transfers (payouts, remittances, bulk rows)

Details: [Payouts](../04-products/05-payouts.md#transfer-statuses).

```mermaid
stateDiagram-v2
    direction LR
    [*] --> pending
    [*] --> pending_approval
    [*] --> processing
    pending --> processing
    pending --> failed
    pending_approval --> processing
    pending_approval --> rejected
    processing --> pending
    processing --> completed
    processing --> failed
    processing --> rejected
    pending_security_review --> pending
    pending_security_review --> pending_approval
    pending_security_review --> processing
    pending_security_review --> cancelled
```

| Status | Final | Webhook | Meaning |
|---|---|---|---|
| `pending` | No | — | Being screened (`responseCode` `null`), retrying after the bank couldn't be reached (`31`), or a manually settled payout being completed. |
| `pending_approval` | No | — | Waiting for an approver in your business (`42`). |
| `processing` | No | — | Sent for payment (`01`; `05` just after approval). USD payouts, and some other currencies, stay `processing` until Multigate's operations team completes them. With some banks, a payout the bank reports as failed also stays `processing` until operations confirms the failure and the money is returned. |
| `completed` | Yes | `transfer_completed` | Paid (`00`). |
| `failed` | Yes | `transfer_failed`, not always | Not paid. Bank and partner failures are normally reversed to your account. A failed balance check just before the debit (`22`) is not debited and sends the webhook. No webhook for: `43` (declined by compliance before any debit), `03` when the debit couldn't be posted, and a Nigerian account number that isn't 10 digits. |
| `rejected` | Yes | — | `04`. Declined by an approver in your business (nothing debited), or in Multigate's compliance or settlement review. |
| `pending_security_review` | No | — (webhooks show `pending`) | Web-app transfers only, never API-created ones, and today only in the sandbox: held by Multigate's security check for its compliance team (`43`). Nothing debited. Released, it continues like a new transfer. |
| `cancelled` | Yes | — | `04`. A held web-app transfer that Multigate declined or didn't review within 24 hours. Nothing debited. |

Common `responseCode` values: `00` paid, `01` processing, `05` approved, `31` bank unreachable (retrying), `42` waiting for approval, `22` balance too low at the pre-debit check, `03` failed, `04` rejected, `43` declined by compliance.

A transfer whose outcome at the bank Multigate can't confirm stays `pending` or `processing`, with `responseMessage` "CBI provider dispatch outcome is unknown", until Multigate reconciles it. No webhook is sent until then; don't pay it again. See [Payouts](../04-products/05-payouts.md#transfer-statuses).

## Bulk batches

Details: [Bulk payouts](../04-products/06-bulk-payouts.md#statuses). Each row is a transfer with the statuses above.

| Status | Final | Meaning |
|---|---|---|
| `pending_approval` | No | At least one row waits for an approver. |
| `processing` | No | Rows are being paid. |
| `completed` | Yes | Every row is final and at least one was paid. Some rows may still have failed. |
| `failed` | Yes | Every row is final and none was paid. |
| `rejected` | Yes | An approver declined every row. |

The batch status is a summary. Always check each row's status.

## Accounts

Details: [Accounts](../04-products/02-accounts.md#when-the-account-isnt-active-yet).

| Status | Webhook | Meaning |
|---|---|---|
| `processing`, `pending` | — | Being opened; waiting for a partner bank. |
| `profiling` | — | Virtual accounts only: waiting for the partner bank to approve your business profile. |
| `active` | `account_opened`, not always | Usable. The webhook can arrive more than once, as each partner bank activates. It's often missing when the account is activated by Multigate's approval of your bank profile, and never sent for linked accounts: poll accounts that stay `processing`. |
| `failed` | None | Couldn't be opened. Open a new account with a new `uniqueRequestId`. |
| `disabled` | None | Closed or blocked, for example a dynamic account after its payment or a suspended business. It can't send or receive money. |
| `inactive` | None | Closed at the bank. |
| `enabled` | None | Re-enabled after being disabled. It can't send money until Multigate sets it back to `active`. |

## Linking requests (linked accounts)

Details: [Accounts](../04-products/02-accounts.md#linked-accounts). No webhooks are sent for linking.

| `ApprovalStatus` | Final | Meaning |
|---|---|---|
| `PENDING` | No | Waiting for a second user to approve. Stays `PENDING` if an approval attempt fails. |
| `APPROVED` | Yes | Approved; the linked account is created and `active`. |
| `DECLINED` | Yes | Declined; the same account can't be requested again. |

## Customers

Details: [Customers](../04-products/01-customers.md#customer-statuses).

| `status` | Webhook | Meaning |
|---|---|---|
| `draft` | — | Created, not submitted. |
| `processing` | — | Submitted. Waiting for your approver, screening, or Multigate compliance. |
| `active` | `subclient_approved` (`client` customers only) | Approved. Only `active` customers can have accounts, payouts and conversions. |
| `rejected` | `subclient_approved` with `status: rejected` | Declined by Multigate compliance. Fix and resubmit. |
| `inactive` | — | Deactivated in your business. Customers declined by your own approver are also set to `inactive` and removed, so you won't see them. |
| `deleted` | — | Deleted in your business. |
| `blocked` | — | Blocked by Multigate compliance. Contact Multigate. |

`approvalStatus` tracks approval inside your business: `pending`, `approved` or `declined`. It stays `approved` when Multigate compliance declines, so use `status`.

## Conversions

Details: [FX conversions](../04-products/09-fx-conversions.md#conversion-statuses).

| Status | Final | Meaning |
|---|---|---|
| `processing` | No | Debited; the credit is waiting for settlement. `trade_completed` follows. |
| `awaiting_balance` | No | Post-funded account (by agreement with Multigate) short of funds; the debit is deferred. |
| `completed` | Yes | Target account credited, at once or after `processing`. `trade_completed` is sent. Today it can also show when the provider failed a `processing` conversion later, so check that the target account was credited. |
| `failed` | Yes | The provider refused the conversion, usually at lock time (the lock call returns `400`). The debit is reversed. |

## Refunds

Details: [Refunds](../04-products/08-refunds.md#refund-statuses).

| Status | Final | Webhook | Meaning |
|---|---|---|---|
| `pending` | No | — | Held for screening. |
| `processing` | No | — | Being paid. Also while Multigate reconciles a refund whose outcome at the bank is unclear, for example one the bank accepted and later reported failed; another refund of the same inflow gets `409` meanwhile. |
| `completed` | Yes | `refund` | The sender was paid and your account debited. |
| `failed` | Yes | `refund`, except when the balance can't be reserved just before payment | Not paid; your account isn't debited. |

## Receivables

Details: [Receivables](../04-products/11-receivables.md#receivable-statuses).

| Status | Webhook | Meaning |
|---|---|---|
| `processing` | — | Account being opened. |
| `unpaid` | None: poll [Get a receivable](api:getReceivable) | Ready: give the payer `fundingDetails`. |
| `partially_paid` | `receivables` / `inflow` and `account` / `inflow` | Some money received; `amountPaid` is less than `amount`. |
| `paid` | `receivables` / `inflow` and `account` / `inflow` | Exactly the invoice amount received. The account is closed and `paidDate` is set. A payment that arrives before the closure completes moves it to `overpaid`. |
| `overpaid` | `receivables` / `inflow` and `account` / `inflow` | More than the invoice amount received. The account is closed. |
| `failed` | None: poll | The account couldn't be opened. |

## Trade finance

Letters of credit and guarantees send **no webhooks**: poll the lists and details, or rely on the [emails](../03-webhooks-and-emails/04-email-notifications.md#trade-finance). Each record has a status and an `approvalStatus` (`pending` while waiting for an approver, then `approved` or `rejected`; empty on records nobody has acted on yet).

### Letters of credit

Details: [Letters of credit](../04-products/13-letters-of-credit.md#statuses). Both types show it in `lcStatus`.

| Status | Export LC | Import LC | Final |
|---|---|---|---|
| `draft` | Manual record being prepared. | Application being prepared. | No |
| `pending` | Received from the bank, not yet advised. | Submitted, waiting for an approver. | No |
| `applied` | | Approved and sent to your bank. | No |
| `issued` | | Issued by the bank. | No |
| `advised` | Accepted into your records. | | No |
| `pending_amendment` | | Amendment sent to the bank. | No |
| `amended` | The bank's amendment is waiting for your response. | The bank accepted the amendment; waiting for the beneficiary. | No |
| `accepted_amendment` | You accepted the amendment. | The beneficiary accepted it. | No |
| `refused_amendment` | You refused the amendment. | The beneficiary refused it. | No |
| `rejected` | Declined by an approver. | Declined by an approver. | Yes |

`processing`, `documents_discrepant`, `documents_rejected`, `documents_accepted`, `partially_settled`, `settled` and `closed` only appear on manual records. An export LC can be amended again after `accepted_amendment` or `refused_amendment`; an import LC in either status can't be amended or updated again through the API.

### Guarantees

Details: [Guarantees](../04-products/14-guarantees.md#statuses). Inward guarantees show it in `guaranteeStatus`, outward guarantees in `status`.

| Status | Inward | Outward | Final |
|---|---|---|---|
| `draft` | Manual record being prepared. | Application being prepared. | No |
| `pending` | Received from the bank, not yet advised. | Submitted, waiting for an approver. | No |
| `applied` | | Approved and sent to your bank. | No |
| `issued` | | Issued by the bank. | No |
| `advised` | Accepted into your records. | | No |
| `pending_amendment` | | Amendment sent to the bank. | No |
| `amended` | The bank's amendment is waiting for your response. | The bank accepted the amendment; waiting for the beneficiary. | No |
| `accepted_amendment`, `refused_amendment` | Your response was sent. | The beneficiary accepted or refused it. | No |
| `rejected` | Declined by an approver. | Declined by an approver. | Yes |

An inward guarantee can be amended again after `accepted_amendment` or `refused_amendment`; an outward guarantee in either status can't be amended or updated again through the API. Expiry, claims and discharges don't change the status automatically: `expired`, `claimed`, `discharged`, `under_claim` and similar values only appear on manual records.