# Bulk payout status API

Read the progress of one batch: counts, amounts and a page of items with each item's state, code, transaction id and receiver name.

## Endpoint
- **Method**: POST
- **URL**: https://api.moolre.com/open/transact/bulk_status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your wallet private API key. A public key is refused. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| accountnumber | string | Yes | Your Moolre wallet account number. |
| batchid | string | No | The batchid returned when the batch was created. Send batchid or batchref. |
| batchref | string | No | Your batchref. Send batchid or batchref. |
| status | string | No | Item filter: queued, submitted, pending, succeeded or failed. |
| after | integer | No | Item index to continue after: send next_after from the previous page. |
| limit | integer | No | Items per page, 1 to 500. Default 100. |

## Response (200 Success)
The batch, its counts and a page of items. Batch status is queued, processing or completed; unresolved is true when the batch completed after 72 hours with some items still pending.

```json
{
  "status": 1,
  "code": "BLK21",
  "message": "Batch found.",
  "data": {
    "batchid": "bat_3f9c2a1d7e5b4c60",
    "batchref": "PAYROLL-2026-11",
    "accountnumber": "1000000000001",
    "currency": "GHS",
    "status": "processing",
    "unresolved": false,
    "total_amount": "150.00",
    "balance_warning": false,
    "counts": {
      "total": 2,
      "queued": 0,
      "submitted": 1,
      "pending": 0,
      "succeeded": 1,
      "failed": 0
    },
    "succeeded_amount": "100.00",
    "failed_amount": "0.00",
    "rejected_items": 1,
    "created": "2026-11-15T09:00:00Z",
    "started": "2026-11-15T09:00:40Z",
    "completed": null,
    "items": [
      {
        "index": 0,
        "externalref": "PAY-1",
        "receiver": "0240000001",
        "channel": "MTN",
        "amount": "100.00",
        "status": "succeeded",
        "code": "OBGH01",
        "message": "Pay out Successful",
        "transactionid": "123456",
        "thirdpartyref": "98765",
        "receivername": "KOFI A",
        "attempts": 1,
        "updated": "2026-11-15T09:01:10Z"
      }
    ],
    "next_after": null
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 (HTTP 404 in strict mode) Batch not found)
No batch with that batchid or batchref on this wallet.

```json
{
  "status": 0,
  "code": "BLK22",
  "message": "Batch not found.",
  "data": "batchid",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## States

| Batch status | Meaning |
| --- | --- |
| queued | Nothing sent yet |
| processing | At least one item has been sent |
| completed | Every item is final (succeeded or failed). unresolved is true when it completed after 72 hours with items still pending: check those by externalref |

| Item status | Meaning |
| --- | --- |
| queued | Waiting to be sent. An item can return here for an automatic retry when the network was unavailable and nothing was charged |
| submitted | Being sent |
| pending | The provider has not confirmed. Resolved later; check the payout by externalref and never resend it |
| succeeded | Paid |
| failed | Not paid. Send it again in a new batch with a new externalref |

## Fields every response can carry

These fields are additive: existing fields keep their names, order and types.

| Field | Meaning |
| :--- | :--- |
| error | On a failure: { code, message, fields: [{ field, code, message }] } listing every failing field. |
| meta | Always present, last in the object. meta.replayed is true only when the response is the stored answer to a repeated Idempotency-Key (absent otherwise). meta.requestid is the unique id of the request (also the X-Request-Id response header): quote it when you contact support. meta.notices is always an array, empty when there is nothing to report; each notice is { code, message, docs? }, for example that a deprecated way of sending credentials was used. See [Deprecations](https://docs.moolre.com/guides/deprecations). |

There is no outcome field. Decide the result from status, code and, on payment and transfer endpoints, data.txstatus (0 pending, 1 succeeded, 2 failed). These codes mean the result is unknown and may still succeed, so treat them as pending and check the status: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, SYS500. Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success; any other status 1 is an accepted, unfinished request.

Send X-Moolre-Http-Status: strict to receive real HTTP status codes (400, 401, 403, 404, 409, 422, 429, 5xx) instead of HTTP 200. See [Responses and request IDs](https://docs.moolre.com/guides/responses).
