> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masterid.co.ug/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /collections/{reference}

> GET /collections/{reference}: read the status of a payment collection request.

Read the status and details of a payment collection request. Use the `reference` returned by [POST /collections](https://docs.masterid.co.ug/api-reference/collections/create-collection.md).

```text theme={null}
GET https://masterid.me/api/public/v1/collections/{reference}
```

## Authentication

**X-API-Key** `string` *required*

Your workspace API key.

**X-API-Secret** `string` *required*

Your workspace API secret.

**Content-Type** `string` *required*

Must be `application/json`.

## Path parameters

**reference** `string` *required*

The collection reference returned by [POST /collections](https://docs.masterid.co.ug/api-reference/collections/create-collection.md).

## Response fields

**id** `string` *required*

API request ID.

**data** `object`

**properties**

**reference** `string`

The collection reference.

**status** `string`

One of: `pending`, `success`, `failed`.

**amount\_ugx** `integer`

Collection amount in UGX.

**completed\_at** `string`

Completion timestamp. Format is not specified in release documentation.

## Status codes

| Status | Meaning |
| - | - |
| 200 | OK. Collection status returned. |
| 401 | Missing, invalid or revoked credentials. |
| 403 | Suspended account. |
| 404 | Unknown operation or resource outside your workspace. |
| 429 | API request limit reached. Check `Retry-After`. |
| 500/503 | Temporary processing error or unavailability. |

> [!NOTE]
>
> Funds become available on the next working day. Withdrawals are managed in the MasterID app.

```bash cURL theme={null}
curl -X GET "https://masterid.me/api/public/v1/collections/<COLLECTION_REFERENCE>" \
  -H "X-API-Key: $MASTERID_API_KEY" \
  -H "X-API-Secret: $MASTERID_API_SECRET" \
  -H "Content-Type: application/json"
```

```javascript Node.js theme={null}
const response = await fetch(
  `https://masterid.me/api/public/v1/collections/${process.env.COLLECTION_REFERENCE}`,
  {
    method: "GET",
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY,
      "X-API-Secret": process.env.MASTERID_API_SECRET,
      "Content-Type": "application/json",
    },
  }
);
const body = await response.json();
console.log(body.data.status);
```

```python Python theme={null}
import os, requests

r = requests.get(
    f"https://masterid.me/api/public/v1/collections/{os.environ['COLLECTION_REFERENCE']}",
    headers={
        "X-API-Key": os.environ["MASTERID_API_KEY"],
        "X-API-Secret": os.environ["MASTERID_API_SECRET"],
        "Content-Type": "application/json",
    },
)
print(r.json()["data"]["status"])
```

```json 200 theme={null}
{
  "id": "<REQUEST_ID>",
  "data": {
    "reference": "<COLLECTION_REFERENCE>",
    "status": "success",
    "amount_ugx": 10000,
    "completed_at": "<COMPLETED_AT>"
  }
}
```

> [!TIP]
>
> The response may include additional fields not documented in this release. Handle unknown fields gracefully in your parser.


## Related topics

- [POST /collections](https://docs.masterid.co.ug/api-reference/collections/create-collection.md)
- [Responses and status codes](https://docs.masterid.co.ug/concepts/responses.md)
- [Collect mobile money payments](https://docs.masterid.co.ug/guides/payment-collection.md)
- [Receive webhooks](https://docs.masterid.co.ug/guides/webhooks.md)
- [Go-live checklist](https://docs.masterid.co.ug/guides/go-live-checklist.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.