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

# Create Payment Link

> Creates a new single-use payment link for OneClick Payment (OCPay) system

## Overview

Create a secure, single-use payment link with customizable settings. Perfect for e-commerce orders, service payments, and subscription renewals.

<Warning>
  **Merchant Validation Required**: Complete merchant validation at
  [ https://app.oneclickdz.com/profile](https://app.oneclickdz.com/profile)
  before using this endpoint.
</Warning>

## Request Body

<ParamField body="productInfo" type="object" required>
  Product or service details being paid for

  <Expandable title="productInfo properties">
    <ParamField body="title" type="string" required>
      Product/service name (1-200 characters) **Examples:** - `"Premium
                  Subscription"` - `"Web Design Services"` - `"Online Course Access"`
    </ParamField>

    <ParamField body="description" type="string">
      Detailed description (max 1000 characters). Supports markdown.
      **Example:** `"Monthly access to all premium features including unlimited
                  storage and priority support"`
    </ParamField>

    <ParamField body="amount" type="number" required>
      Payment amount in DZD (500 - 500,000) **Examples:** `5000`, `15000`,
      `50000`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="feeMode" type="string" default="NO_FEE">
  Determines who pays withdrawal fees - `NO_FEE` - Merchant pays all fees
  (default) - `SPLIT_FEE` - Fees split 50/50 - `CUSTOMER_FEE` - Customer pays
  all fees
</ParamField>

<ParamField body="successMessage" type="string">
  Custom success message (max 500 characters) shown after payment **Example:**
  `"Thank you for your purchase! Your order is being processed."`
</ParamField>

<ParamField body="redirectUrl" type="string">
  Redirect URL after successful payment (must be valid HTTP/HTTPS) **Example:**
  `"https://yourstore.com/order-check?orderId=12345"`
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  Payment link details

  <Expandable title="data properties">
    <ResponseField name="paymentLink" type="object">
      Complete payment link information

      <Expandable title="paymentLink properties">
        <ResponseField name="uid" type="string">
          Merchant's unique identifier
        </ResponseField>

        <ResponseField name="ref" type="string">
          Payment reference code (format: `OCPL-XXXXXX-YYYY`)
        </ResponseField>

        <ResponseField name="isSandbox" type="boolean">
          Whether this is a test payment link
        </ResponseField>

        <ResponseField name="productInfo" type="object">
          Product information as submitted
        </ResponseField>

        <ResponseField name="feeMode" type="string">
          Fee configuration mode
        </ResponseField>

        <ResponseField name="successMessage" type="string">
          Custom success message
        </ResponseField>

        <ResponseField name="redirectUrl" type="string">
          Post-payment redirect URL
        </ResponseField>

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

    <ResponseField name="paymentUrl" type="string">
      **Complete URL to share with customers** for payment **Example:**
      `"https://pay.ocdz.link/pay/OCPL-A1B2C3-D4E5"`
    </ResponseField>

    <ResponseField name="paymentRef" type="string">
      Payment reference code - **SAVE THIS** for tracking payments **Example:**
      `"OCPL-A1B2C3-D4E5"`
    </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>

## Key Features

<CardGroup cols={2}>
  <Card title="Fee Flexibility" icon="money-bill">
    Choose who pays transaction fees - merchant, customer, or split
  </Card>

  <Card title="Custom Branding" icon="palette">
    Personalized success messages and redirect URLs
  </Card>

  <Card title="Sandbox Testing" icon="flask">
    Test integration safely before going live
  </Card>

  <Card title="Single-Use Security" icon="shield-check">
    Each link is single-use for enhanced security
  </Card>
</CardGroup>

## Important Notes

<Note>
  **Amount Limits:** - Minimum: 500 DZD - Maximum: 500,000 DZD - Must be whole
  numbers (no decimals)
</Note>

<Note>
  **Fee Structure:** - 0% if using OneClick balance - 1% withdrawal fee only
  (configurable per transaction)
</Note>

<Note>
  **Link Expiration:** Payment links expire 20 minutes after creation if payment
  is not initiated
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.oneclickdz.com/v3/ocpay/createLink \
    --header 'Content-Type: application/json' \
    --header 'X-Access-Token: YOUR_API_KEY' \
    --data '{
    "productInfo": {
      "title": "Premium Subscription",
      "description": "Monthly access to premium features",
      "amount": 5000
    },
    "feeMode": "NO_FEE",
    "successMessage": "Thank you for your purchase!",
    "redirectUrl": "https://yourstore.com/success?orderId=12345"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/ocpay/createLink", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      productInfo: {
        title: "Premium Subscription",
        description: "Monthly access to premium features",
        amount: 5000,
      },
      feeMode: "NO_FEE",
      successMessage: "Thank you for your purchase!",
      redirectUrl: "https://yourstore.com/success?orderId=12345",
    }),
  });

  const data = await response.json();
  console.log("Payment URL:", data.data.paymentUrl);
  console.log("Payment Ref:", data.data.paymentRef);
  ```

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

  url = "https://api.oneclickdz.com/v3/ocpay/createLink"
  headers = {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY"
  }
  payload = {
      "productInfo": {
          "title": "Premium Subscription",
          "description": "Monthly access to premium features",
          "amount": 5000
      },
      "feeMode": "NO_FEE",
      "successMessage": "Thank you for your purchase!",
      "redirectUrl": "https://yourstore.com/success?orderId=12345"
  }

  response = requests.post(url, json=payload, headers=headers)
  data = response.json()

  print(f"Payment URL: {data['data']['paymentUrl']}")
  print(f"Payment Ref: {data['data']['paymentRef']}")
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://api.oneclickdz.com/v3/ocpay/createLink';
  $headers = [
      'Content-Type: application/json',
      'X-Access-Token: YOUR_API_KEY'
  ];
  $payload = [
      'productInfo' => [
          'title' => 'Premium Subscription',
          'description' => 'Monthly access to premium features',
          'amount' => 5000
      ],
      'feeMode' => 'NO_FEE',
      'successMessage' => 'Thank you for your purchase!',
      'redirectUrl' => 'https://yourstore.com/success?orderId=12345'
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

  echo "Payment URL: " . $data['data']['paymentUrl'] . "\n";
  echo "Payment Ref: " . $data['data']['paymentRef'] . "\n";
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (200) theme={null}
  {
    "success": true,
    "data": {
      "paymentLink": {
        "uid": "user_123456789",
        "ref": "OCPL-A1B2C3-D4E5",
        "isSandbox": false,
        "productInfo": {
          "title": "Premium Subscription",
          "description": "Monthly access to premium features",
          "amount": 5000
        },
        "feeMode": "NO_FEE",
        "successMessage": "Thank you for your purchase!",
        "redirectUrl": "https://yourstore.com/success?orderId=12345",
        "time": "2025-01-15T10:30:00Z"
      },
      "paymentUrl": "https://pay.ocdz.link/pay/OCPL-A1B2C3-D4E5",
      "paymentRef": "OCPL-A1B2C3-D4E5"
    },
    "meta": {
      "timestamp": "2025-01-15T10:30:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```

  ```json Validation Error (400) theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request data",
      "details": [
        {
          "field": "productInfo.amount",
          "message": "Amount must be between 500 and 500,000 DZD"
        }
      ]
    },
    "meta": {
      "timestamp": "2025-01-15T10:30:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```

  ```json Merchant Not Validated (403) theme={null}
  {
    "success": false,
    "error": {
      "code": "FORBIDDEN",
      "message": "Complete merchant validation at  https://app.oneclickdz.com/profile"
    },
    "meta": {
      "timestamp": "2025-01-15T10:30:00Z",
      "requestId": "req_abc123xyz"
    }
  }
  ```
</ResponseExample>

## Next Steps

<CardGroup cols={2}>
  <Card title="Check Payment Status" icon="magnifying-glass" href="/en/api-reference/ocpay/check-payment">
    Learn how to check payment status
  </Card>

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