> ## 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.

# Navio Integration Overview

> Complete guide to integrating OneClick Payment system into your application

## Welcome to Navio

OneClick Payment (Navio) enables you to accept secure online payments in Algeria with minimal integration effort. Create payment links, track transactions, and manage your funds - all through our simple API.

<CardGroup cols={2}>
  <Card title="Quick Setup" icon="rocket" color="#0D9373">
    Get started in minutes with our straightforward API
  </Card>

  <Card title="Secure Payments" icon="shield-check" color="#0D9373">
    Bank-grade security powered by SATIM
  </Card>

  <Card title="Real-time Tracking" icon="chart-line" color="#0D9373">
    Monitor payment status in real-time
  </Card>

  <Card title="Flexible Fees" icon="money-bill-wave" color="#0D9373">
    Choose who pays transaction fees
  </Card>
</CardGroup>

## What You'll Build

By following this guide, you'll implement a complete payment flow:

1. **Customer creates an order** in your application
2. **Your system generates a payment link** via Navio API
3. **Customer completes payment** on secure payment page
4. **Your system tracks payment status** and fulfills the order

## Prerequisites

<Steps>
  <Step title="OneClick Account">
    Create an account at [app.oneclickdz.com](https://enterprise.oneclickdz.com/)
  </Step>

  <Step title="Merchant Validation">
    Complete merchant validation at [Navio Merchant
    Info](https://enterprise.oneclickdz.com/profile)

    <Warning>
      This step is **required** before you can create payment links
    </Warning>
  </Step>

  <Step title="API Key">
    Get your API key from the dashboard (use Sandbox key for testing)
  </Step>

  <Step title="Technical Requirements">
    * Backend server to handle API calls - Database to store order and payment
      references - Basic understanding of REST APIs
  </Step>
</Steps>

## How It Works

1. Customer places order → You save it as `PENDING`
2. You call `/v3/ocpay/createLink` → Get `paymentUrl` and `paymentRef`
3. **Save `paymentRef` with your order** (important!)
4. Redirect customer to `paymentUrl`
5. Customer pays → Returns to your site
6. You check status with `/v3/ocpay/checkPayment/:ref`
7. Update order and fulfill if `CONFIRMED`

## Key Concepts

<AccordionGroup>
  <Accordion title="Payment Reference (paymentRef)" icon="hashtag">
    Unique identifier for each payment (format: `OCPL-XXXXXX-YYYY`). Save this with your order to check status later.
  </Accordion>

  {" "}

  <Accordion title="Payment Link Expiration" icon="clock">
    Links expire after 20 minutes. Create a new link if customer needs to retry.
  </Accordion>

  <Accordion title="Status Checking" icon="rotate">
    Check payment status when customer returns to your site or when your cron job runs every 20 minutes.
  </Accordion>
</AccordionGroup>

## Fee Structure

<Info>
  **Low Fees:** 0% when keeping balance in OneClick, only 1% on withdrawal
</Info>

You can choose who pays the withdrawal fee:

| Fee Mode       | Description            | Use Case                 |
| -------------- | ---------------------- | ------------------------ |
| `NO_FEE`       | You absorb all fees    | Best customer experience |
| `SPLIT_FEE`    | 50/50 split            | Shared responsibility    |
| `CUSTOMER_FEE` | Customer pays all fees | Maximize your profit     |

## Integration Steps

Follow these guides in order:

<CardGroup cols={2}>
  <Card title="1. Merchant Setup" icon="user-check" href="/en/ocpay-guides/1-merchant-setup">
    Complete merchant validation and get your API key
  </Card>

  {" "}

  <Card title="2. Payment Flow" icon="diagram-project" href="/en/ocpay-guides/2-payment-flow">
    Implement the complete payment integration
  </Card>

  {" "}

  <Card title="3. Status Polling" icon="clock-rotate-left" href="/en/ocpay-guides/3-status-polling">
    Track payments and update order status
  </Card>

  <Card title="4. Best Practices" icon="star" href="/en/ocpay-guides/4-best-practices">
    Production-ready tips and error handling
  </Card>
</CardGroup>

## Quick Start

<CodeGroup>
  ```javascript Node.js theme={null}
  const fetch = require("node-fetch");

  // Create payment link
  async function createPayment(orderId, amount, title) {
    const response = await fetch(
      "https://api.oneclickdz.com/v3/ocpay/createLink",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Access-Token": process.env.ONECLICK_API_KEY,
        },
        body: JSON.stringify({
          productInfo: { title, amount },
          redirectUrl: `https://yoursite.com/orders/${orderId}`,
        }),
      }
    );

    const data = await response.json();

    // Save paymentRef with your order!
    await db.orders.update(orderId, {
      paymentRef: data.data.paymentRef,
    });

    return data.data.paymentUrl; // Redirect customer here
  }

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

    const data = await response.json();
    return data.data.status; // PENDING, CONFIRMED, or FAILED
  }
  ```

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

  # Create payment link
  def create_payment(order_id, amount, title):
      response = requests.post(
          'https://api.oneclickdz.com/v3/ocpay/createLink',
          headers={
              'Content-Type': 'application/json',
              'X-Access-Token': os.getenv('ONECLICK_API_KEY')
          },
          json={
              'productInfo': {'title': title, 'amount': amount},
              'redirectUrl': f'https://yoursite.com/orders/{order_id}'
          }
      )

      data = response.json()

      # Save paymentRef with your order!
      db.orders.update(order_id, {
          'paymentRef': data['data']['paymentRef']
      })

      return data['data']['paymentUrl']  # Redirect customer here

  # Check payment status
  def check_payment(payment_ref):
      response = requests.get(
          f'https://api.oneclickdz.com/v3/ocpay/checkPayment/{payment_ref}',
          headers={'X-Access-Token': os.getenv('ONECLICK_API_KEY')}
      )

      data = response.json()
      return data['data']['status']  # PENDING, CONFIRMED, or FAILED
  ```

  ```php PHP theme={null}
  <?php

  // Create payment link
  function createPayment($orderId, $amount, $title) {
      $ch = curl_init('https://api.oneclickdz.com/v3/ocpay/createLink');
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Content-Type: application/json',
          'X-Access-Token: ' . getenv('ONECLICK_API_KEY')
      ]);
      curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
          'productInfo' => ['title' => $title, 'amount' => $amount],
          'redirectUrl' => "https://yoursite.com/orders/$orderId"
      ]));

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

      // Save paymentRef with your order!
      $db->orders->update($orderId, [
          'paymentRef' => $data['data']['paymentRef']
      ]);

      return $data['data']['paymentUrl']; // Redirect customer here
  }

  // Check payment status
  function checkPayment($paymentRef) {
      $ch = curl_init("https://api.oneclickdz.com/v3/ocpay/checkPayment/$paymentRef");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'X-Access-Token: ' . getenv('ONECLICK_API_KEY')
      ]);

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

      return $data['data']['status']; // PENDING, CONFIRMED, or FAILED
  }
  ?>
  ```
</CodeGroup>

## Support & Resources

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/en/api-reference/ocpay/create-link">
    Detailed API documentation
  </Card>

  {" "}

  <Card title="Contact Support" icon="headset" href="/en/contact">
    Get help from our team
  </Card>

  {" "}

  <Card title="Dashboard" icon="gauge" href="https://enterprise.oneclickdz.com/">
    Manage your account
  </Card>

  <Card title="Security Guide" icon="lock" href="/en/security-best-practices">
    Keep your integration secure
  </Card>
</CardGroup>

## Next: Merchant Setup

Ready to start? Begin with merchant validation:

<Card title="Start Integration" icon="arrow-right" href="/en/ocpay-guides/1-merchant-setup">
  Complete merchant setup and validation
</Card>