> ## 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 Payment Status

> Check the current status of a payment using its reference code

## Overview

Check payment status in real-time using the payment reference. Essential for order processing, status polling, and payment verification.

<Info>
  **Automatic Environment Detection**: This endpoint automatically checks both
  production (SATIM) and sandbox transactions based on where the payment was
  created.
</Info>

## Path Parameters

<ParamField path="ref" type="string" required>
  Payment reference code (format: `OCPL-XXXXXX-YYYY`) **Examples:** -
  `OCPL-A1B2C3-D4E5` - `OCPL-123456-7890`

  <Note>
    This is the `paymentRef` returned when you created the payment link
  </Note>
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  Payment status information

  <Expandable title="data properties">
    <ResponseField name="status" type="string">
      Current payment status - `PENDING` - Payment not yet initiated or
      processing - `CONFIRMED` - Payment successful - `FAILED` - Payment failed
      or link expired
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable status description **Examples:** - `"Payment confirmed
                  successfully"` - `"Payment not yet initiated"` - `"Payment failed"`
    </ResponseField>

    <ResponseField name="paymentRef" type="string">
      Payment reference code
    </ResponseField>

    <ResponseField name="transactionDetails" type="object">
      Additional transaction information (when available)

      <Expandable title="transactionDetails properties">
        <ResponseField name="amount" type="number">
          Payment amount in DZD
        </ResponseField>

        <ResponseField name="currency" type="string">
          Currency code (always `"DZD"`)
        </ResponseField>

        <ResponseField name="isSandbox" type="boolean">
          Whether this is a sandbox transaction
        </ResponseField>

        <ResponseField name="createdDate" type="string">
          Transaction creation timestamp (ISO 8601)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Response metadata

  <Expandable title="meta properties">
    <ResponseField name="timestamp" type="string">
      Response timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="requestId" type="string">
      Unique request ID for support
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Values Explained

<AccordionGroup>
  <Accordion title="PENDING" icon="clock">
    **When you see this:**

    * Customer hasn't started the payment process yet
    * Payment is currently being processed by the bank
    * Link was just created and not yet used

    **What to do:**

    * Continue polling for status updates
    * Display "Payment pending" to customer
    * Don't fulfill the order yet
  </Accordion>

  {" "}

  <Accordion title="CONFIRMED" icon="circle-check">
    **When you see this:** - Payment completed successfully - Funds will be
    credited to your OneClick balance **What to do:** - Mark order as paid in your
    system - Fulfill the order/provide service - Send confirmation to customer
  </Accordion>

  <Accordion title="FAILED" icon="circle-xmark">
    **When you see this:**

    * Payment was declined or failed
    * Payment link expired (20 minutes)
    * Customer cancelled the payment

    **What to do:**

    * Mark order as failed/cancelled
    * Create a new payment link if customer wants to retry
    * Don't fulfill the order
  </Accordion>
</AccordionGroup>

## Link Expiration

<Warning>
  Payment links expire **20 minutes** after creation if no payment is initiated.
  After expiration, the status will be `FAILED`.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.oneclickdz.com/v3/ocpay/checkPayment/OCPL-A1B2C3-D4E5 \
    --header 'X-Access-Token: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/ocpay/checkPayment/OCPL-A1B2C3-D4E5",
    {
      method: "GET",
      headers: {
        "X-Access-Token": "YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log("Payment Status:", data.data.status);
  console.log("Message:", data.data.message);
  ```

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

  ref = "OCPL-A1B2C3-D4E5"
  url = f"https://api.oneclickdz.com/v3/ocpay/checkPayment/{ref}"
  headers = {
      "X-Access-Token": "YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  data = response.json()

  print(f"Payment Status: {data['data']['status']}")
  print(f"Message: {data['data']['message']}")
  ```

  ```php PHP theme={null}
  <?php
  $ref = 'OCPL-A1B2C3-D4E5';
  $url = "https://api.oneclickdz.com/v3/ocpay/checkPayment/{$ref}";
  $headers = [
      'X-Access-Token: YOUR_API_KEY'
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

  $response = curl_exec($ch);
  $data = json_decode($response, true);

  echo "Payment Status: " . $data['data']['status'] . "\n";
  echo "Message: " . $data['data']['message'] . "\n";
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json Confirmed Payment (200) theme={null}
  {
    "success": true,
    "data": {
      "status": "CONFIRMED",
      "message": "Payment confirmed successfully",
      "paymentRef": "OCPL-A1B2C3-D4E5",
      "transactionDetails": {
        "amount": 5000,
        "currency": "DZD",
        "isSandbox": false,
        "createdDate": "2025-01-15T10:30:00Z"
      }
    },
    "meta": {
      "timestamp": "2025-01-15T10:35:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```

  ```json Pending Payment (200) theme={null}
  {
    "success": true,
    "data": {
      "status": "PENDING",
      "message": "Payment not yet initiated",
      "paymentRef": "OCPL-A1B2C3-D4E5",
      "transactionDetails": {
        "amount": 5000,
        "currency": "DZD",
        "isSandbox": false
      }
    },
    "meta": {
      "timestamp": "2025-01-15T10:32:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```

  ```json Failed Payment (200) theme={null}
  {
    "success": true,
    "data": {
      "status": "FAILED",
      "message": "Payment failed",
      "paymentRef": "OCPL-A1B2C3-D4E5",
      "transactionDetails": {
        "amount": 5000,
        "currency": "DZD",
        "isSandbox": false,
        "createdDate": "2025-01-15T10:30:00Z"
      }
    },
    "meta": {
      "timestamp": "2025-01-15T10:35:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```

  ```json Payment Not Found (404) theme={null}
  {
    "success": false,
    "error": {
      "code": "PAYMENT_NOT_FOUND",
      "message": "Payment link not found"
    },
    "meta": {
      "timestamp": "2025-01-15T10:35:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```

  ```json Payment Expired (410) theme={null}
  {
    "success": false,
    "error": {
      "code": "PAYMENT_EXPIRED",
      "message": "Payment link expired"
    },
    "meta": {
      "timestamp": "2025-01-15T10:55:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```
</ResponseExample>

## Integration Example

Here's how to implement status checking in your order system:

```javascript theme={null}
async function checkOrderPayment(orderId) {
  // Get payment ref from your database
  const order = await db.orders.findOne({ id: orderId });

  if (!order || !order.paymentRef) {
    throw new Error("Order not found or no payment link");
  }

  // Check payment status
  const response = await fetch(
    `https://api.oneclickdz.com/v3/ocpay/checkPayment/${order.paymentRef}`,
    {
      headers: { "X-Access-Token": process.env.ONECLICK_API_KEY },
    }
  );

  const data = await response.json();

  // Update order status based on payment status
  switch (data.data.status) {
    case "CONFIRMED":
      await db.orders.update(orderId, {
        status: "paid",
        paidAt: new Date(),
      });
      // Fulfill order
      await fulfillOrder(orderId);
      break;

    case "FAILED":
      await db.orders.update(orderId, {
        status: "payment_failed",
      });
      break;

    case "PENDING":
      // Keep polling
      break;
  }

  return data.data;
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Payment Link" icon="link" href="/en/api-reference/ocpay/create-link">
    Learn how to create payment links
  </Card>

  <Card title="Integration Guide" icon="book" href="/en/ocpay-guides/overview">
    Complete Navio integration guide
  </Card>
</CardGroup>