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

# Gift Card Integration Overview

> Learn how to integrate gift card and digital product ordering

## Introduction

Integrate gift card and digital product sales in 5 simple steps. This overview explains the workflow-detailed implementation with code examples are in the step-by-step guides below.

<Info>
  Gift card orders process within seconds and deliver card codes digitally via
  the API.
</Info>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant User
    participant YourApp
    participant API as OneClickDz API

    YourApp->>API: 1. Load product catalog
    API-->>YourApp: Categories & products

    User->>YourApp: Select product
    YourApp->>API: 2. Check product details
    API-->>YourApp: Types, pricing, stock

    User->>YourApp: Choose type & quantity
    YourApp->>API: 3. Place order
    API-->>YourApp: Order ID

    loop Until Complete
        YourApp->>API: 4. Check order status
        API-->>YourApp: Status update
    end

    YourApp->>User: 5. Deliver card codes
```

## 5-Step Integration Process

<Steps>
  <Step title="Load Catalog">
    Fetch available products organized by categories (Gaming, Streaming, etc.).
    → [See Step 1: Loading Catalog](/en/gift-card-guides/1-loading-catalog)
  </Step>

  <Step title="Check Product">
    Get denominations, pricing, and real-time stock for a specific product. →
    [See Step 2: Checking Products](/en/gift-card-guides/2-checking-products)
  </Step>

  <Step title="Place Order">
    Submit order with product ID, type ID (denomination), and quantity. → [See
    Step 3: Placing Orders](/en/gift-card-guides/3-placing-orders)
  </Step>

  <Step title="Track Status">
    Poll order status every 5-10 seconds until complete. → [See Step 4: Status
    Tracking](/en/gift-card-guides/4-status-tracking)
  </Step>

  <Step title="Deliver Cards">
    Retrieve card codes/serials and securely deliver to customer. → [See Step 5:
    Secure Delivery](/en/gift-card-guides/5-secure-delivery)
  </Step>
</Steps>

## What You Need to Know

### Product Structure

* **Catalog** → Categories (Gaming, Streaming, etc.)
* **Products** → Individual items (PUBG, Netflix, etc.)
* **Types** → Denominations (500 DA, 1000 DA, etc.)

→ [Catalog structure in Step 1](/en/gift-card-guides/1-loading-catalog)

### Order Status

* `HANDLING` → Keep polling
* `FULFILLED` → All cards delivered ✅
* `PARTIALLY_FILLED` → Some cards delivered, rest refunded ⚠️
* `REFUNDED` → Order failed, refund issued ❌

→ [Status handling in Step 4](/en/gift-card-guides/4-status-tracking)

### Partial Fulfillment

If you order 5 cards but only 3 are available, you'll receive:

* 3 cards delivered
* Charged only for 3
* Refunded for 2 automatically

Always check `fulfilled_quantity` vs `quantity`.

→ [Handling partials in Step 4](/en/gift-card-guides/4-status-tracking)

### Pricing

Apply your markup to wholesale prices before showing to customers.

Example: 490 DA wholesale → Sell at 515 DA (5% markup) → Profit: 25 DA

→ [Pricing in Step 2](/en/gift-card-guides/2-checking-products)

## Key Points

<CardGroup cols={2}>
  <Card title="Check Stock" icon="warehouse">
    Verify `available: true` before showing products → [Step
    2](/en/gift-card-guides/2-checking-products)
  </Card>

  <Card title="Cache Catalog" icon="database">
    Cache catalog for +24 hours to reduce API calls → [Step
    1](/en/gift-card-guides/1-loading-catalog)
  </Card>

  <Card title="Handle Partials" icon="triangle-exclamation">
    Check fulfilled vs requested quantity → [Step
    4](/en/gift-card-guides/4-status-tracking)
  </Card>

  <Card title="Encrypt Cards" icon="lock">
    Never store card codes in plain text → [Step
    5](/en/gift-card-guides/5-secure-delivery)
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Get Catalog" icon="list" href="/en/api-reference/gift-cards/get-catalog">
    GET /v3/gift-cards/catalog
  </Card>

  <Card title="Check Product" icon="magnifying-glass" href="/en/api-reference/gift-cards/check-product">
    GET /v3/gift-cards/checkProduct/:id
  </Card>

  <Card title="Place Order" icon="cart-shopping" href="/en/api-reference/gift-cards/place-order">
    POST /v3/gift-cards/placeOrder
  </Card>

  <Card title="Check Order" icon="file-circle-check" href="/en/api-reference/gift-cards/check-order">
    GET /v3/gift-cards/checkOrder/:id
  </Card>
</CardGroup>

## Testing

Use **sandbox mode** to test without spending real balance:

* `TEST_REFUND` (type ID) → Simulates failed order
* `TEST_PARTIAL` (type ID) → Simulates 50% fulfillment

Enable sandbox in [dashboard settings](https://app.oneclickdz.com/#/settings).

## Start Integrating

<Card title="Begin with Step 1: Loading Catalog" icon="play" href="/en/gift-card-guides/1-loading-catalog" color="#0D9373">
  Get started by loading the product catalog with code examples
</Card>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/en/quickstart">
    Get up and running in 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/en/authentication">
    Learn how to authenticate requests
  </Card>

  <Card title="Security Best Practices" icon="shield" href="/en/security-best-practices">
    Secure your integration
  </Card>

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