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

# Check Status by Reference

> Check mobile top-up status using your custom reference

## Overview

Track mobile top-up status using the `ref` parameter you provided when sending the top-up. This is useful when you want to check status using your own order IDs.

This endpoint allows you to track orders using the reference you provided when creating the top-up. If you didn't provide a reference, use the auto-generated one returned in the send response.

<Info>
  See [Check by ID](/en/api-reference/mobile/check-by-id) documentation for detailed status descriptions and handling guidelines.
</Info>

## Path Parameters

<ParamField path="ref" type="string" required>
  Your custom reference from `/mobile/send` request
</ParamField>

## Response

Response format is identical to [Check by ID](/en/api-reference/mobile/check-by-id).

<ResponseField name="success" type="boolean" required>
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object" required>
  Top-up object with status, details, and refund information (if applicable). See [Check by ID](/en/api-reference/mobile/check-by-id#response) for complete field descriptions.
</ResponseField>

<ResponseField name="meta" type="object" required>
  Metadata with timestamp in ISO 8601 format
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/mobile/check-ref/order-12345 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const orderRef = "order-12345";
  const response = await fetch(
    `https://api.oneclickdz.com/v3/mobile/check-ref/${orderRef}`,
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const { data } = await response.json();
  ```

  ```python Python theme={null}
  order_ref = 'order-12345'
  response = requests.get(
      f'https://api.oneclickdz.com/v3/mobile/check-ref/{order_ref}',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  status = response.json()['data']['status']
  ```

  ```php PHP theme={null}
  <?php
  $orderRef = 'order-12345';
  $url = "https://api.oneclickdz.com/v3/mobile/check-ref/{$orderRef}";
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Access-Token: YOUR_API_KEY']);
  $response = json_decode(curl_exec($ch), true);
  ?>
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "FULFILLED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z"
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_xyz789"
}
```

## When to Use This Endpoint

<CardGroup cols={2}>
  <Card title="User Queries" icon="user">
    When users ask about their order using your order ID
  </Card>

  <Card title="Order Management" icon="list-check">
    Integrate with your existing order tracking system
  </Card>

  <Card title="Status Pages" icon="display">
    Display order status using customer-facing references
  </Card>

  <Card title="Customer Support" icon="headset">
    Look up orders by customer reference numbers
  </Card>
</CardGroup>

## Status Values & Handling

See [Check by ID](/en/api-reference/mobile/check-by-id#status-values) for detailed status descriptions and handling instructions.

## Error Response

**404 - Not Found:**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Top-up with reference 'order-12345' not found"
  },
  "requestId": "req_1730160975_abc123"
}
```

This means no top-up exists with that reference. Possible reasons:

* Reference was never submitted
* Typo in reference
* Reference belongs to different account

## Best Practices

<AccordionGroup>
  <Accordion title="Use Meaningful References">
    Create references that are:

    * Unique across your system
    * Easy to identify (e.g., `order-{timestamp}-{userId}`)
    * URL-safe (no special characters)
    * Searchable in your database
  </Accordion>

  <Accordion title="Store Both IDs">
    Save both your reference and the API's topupId:

    ```javascript theme={null}
    await db.orders.update({
      orderId: 'order-12345',
      apiTopupId: response.data.topupId,
      apiTopupRef: response.data.topupRef
    });
    ```

    This allows you to track using either identifier.
  </Accordion>

  <Accordion title="Handle Missing References">
    If you forget to provide a `ref`, the API generates one. Save it:

    ```javascript theme={null}
    const response = await sendTopup({ 
      plan_code: 'PREPAID_DJEZZY',
      MSSIDN: '0778037340',
      amount: 500
      // No ref provided
    });

    // API returns: { topupRef: "auto-gen-1730160975" }
    await db.orders.update({
      orderId: order.id,
      apiRef: response.data.topupRef
    });
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Check by ID" icon="id-card" href="/en/api-reference/mobile/check-by-id">
    Track using internal top-up ID
  </Card>

  <Card title="Send Top-Up" icon="paper-plane" href="/en/api-reference/mobile/send-topup">
    Create a new top-up
  </Card>

  <Card title="List Top-Ups" icon="list" href="/en/api-reference/mobile/list-topups">
    View all top-ups
  </Card>
</CardGroup>