راهنمای استفاده از API افزونه WebDide Card-to-Card (شتاب)

• تایید پرداخت: POST /wp-json/webdide-cv/v1/confirm
• وضعیت تراکنش: GET /wp-json/webdide-cv/v1/status
• آپلود فیش: POST /wp-json/webdide-cv/v1/upload-receipt

آدرس کامل مثلاً این شکلی است:

https://your-site.com/wp-json/webdide-cv/v1/confirm

پیش‌نیازها

1. افزونه نصب و فعال باشد و ووکامرس هم فعال باشد.
2. در تنظیمات پیوندهای یکتا، حالت Plain نباشد (مثلاً Post name).
3. از مسیر شتاب ← API و اپ یک API Secret بسازید و کپی کنید.
4. حداقل یک کارت مقصد فعال داشته باشید و یک سفارش تست با درگاه کارت‌به‌کارت ثبت کنید.

احراز هویت

برای confirm همیشه، و برای status / upload-receipt وقتی با API Secret کار می‌کنید، هدر زیر را بفرستید:

Authorization: YOUR_API_SECRET

یا به صورت Bearer:

Authorization: Bearer YOUR_API_SECRET

هر دو حالت پشتیبانی می‌شود.

۱) تایید پرداخت — POST /confirm

این همان کاری است که اپ اندروید بعد از دیدن پیامک یا اعلان بانکی انجام می‌دهد: مبلغ یکتای در انتظار را پیدا می‌کند و سفارش را پرداخت‌شده می‌کند.

فیلدهای Body (JSON یا form-data):

• amount (الزامی): مبلغ تراکنش به تومان، فقط عدد؛ مثل 10540236
• recipeId (اختیاری): کد مرجع یا شناسه رسید برای یادداشت سفارش

پاسخ موفق:

{
  "success": true,
  "message": "Payment confirmed successfully.",
  "order_id": 5124
}

مثال Python

import requests

BASE = "https://your-site.com/wp-json/webdide-cv/v1"
API_SECRET = "YOUR_API_SECRET"

def confirm_payment(amount: int, recipe_id: str = ""):
    r = requests.post(
        f"{BASE}/confirm",
        headers={
            "Authorization": f"Bearer {API_SECRET}",
            "Content-Type": "application/json",
        },
        json={
            "amount": amount,
            "recipeId": recipe_id,
        },
        timeout=30,
    )
    print(r.status_code, r.text)
    r.raise_for_status()
    return r.json()

# مبلغ باید دقیقاً همان unique amount سفارش pending باشد
confirm_payment(10540236, recipe_id="SMS-REF-123")

مثال PHP

<?php
$base = 'https://your-site.com/wp-json/webdide-cv/v1';
$api_secret = 'YOUR_API_SECRET';

$payload = [
    'amount'   => 10540236,
    'recipeId' => 'SMS-REF-123',
];

$ch = curl_init($base . '/confirm');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $api_secret,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
$code     = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $code . "\n" . $response;

نکته مهم: مبلغ باید دقیقاً همان مبلغ یکتای سفارش در وضعیت pending باشد. اگر سفارش منقضی شده یا قبلاً تایید شده باشد، خطای 404 می‌گیرید.

۲) وضعیت تراکنش — GET /status

برای polling سمت فرانت یا مانیتورینگ سمت سرور مفید است.

پارامترها:

• order_id (الزامی): شناسه سفارش ووکامرس
• order_key: کلید سفارش، برای مشتری بدون API Secret

با API Secret می‌توانید فقط با order_id بخوانید.

نمونه پاسخ:

{
  "order_id": 5124,
  "status": "pending",
  "unique_amount": 10540236,
  "expires_at": "2026-09-09 18:00:00"
}

وضعیت‌های رایج: pending ، confirmed ، expired ، rejected ، یا not_found.

مثال Python

import requests

BASE = "https://your-site.com/wp-json/webdide-cv/v1"
API_SECRET = "YOUR_API_SECRET"

def get_status(order_id: int):
    r = requests.get(
        f"{BASE}/status",
        params={"order_id": order_id},
        headers={"Authorization": f"Bearer {API_SECRET}"},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

print(get_status(5124))

مثال PHP

<?php
$base = 'https://your-site.com/wp-json/webdide-cv/v1';
$api_secret = 'YOUR_API_SECRET';
$order_id = 5124;

$url = $base . '/status?' . http_build_query(['order_id' => $order_id]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $api_secret,
    ],
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

اگر مشتری سایت است و Secret ندارید، به‌جای هدر Authorization، order_key را هم بفرستید:

GET /wp-json/webdide-cv/v1/status?order_id=5124&order_key=wc_order_xxxxx

۳) آپلود فیش — POST /upload-receipt

برای ارسال تصویر رسید وقتی تایید خودکار انجام نشده.

احراز هویت یکی از این‌ها:

• کاربر لاگین‌شده مالک سفارش
• یا order_id + order_key
• یا API Secret

Body: multipart/form-data

• order_id: شناسه سفارش
• order_key: در صورت نیاز
• receipts: فایل تصویر (یکی یا چندتا)

بعد از آپلود موفق، سفارش معمولاً on-hold می‌ماند و برای بررسی ادمین (و در صورت فعال بودن، ربات تلگرام یا بله) آماده می‌شود.

مثال Python

import requests

BASE = "https://your-site.com/wp-json/webdide-cv/v1"
API_SECRET = "YOUR_API_SECRET"

def upload_receipt(order_id: int, image_path: str):
    with open(image_path, "rb") as f:
        r = requests.post(
            f"{BASE}/upload-receipt",
            headers={"Authorization": f"Bearer {API_SECRET}"},
            data={"order_id": order_id},
            files={"receipts": f},
            timeout=60,
        )
    print(r.status_code, r.text)
    r.raise_for_status()
    return r.json()

upload_receipt(5124, "receipt.jpg")

مثال PHP

<?php
$base = 'https://your-site.com/wp-json/webdide-cv/v1';
$api_secret = 'YOUR_API_SECRET';
$order_id = 5124;
$file = new CURLFile(__DIR__ . '/receipt.jpg', 'image/jpeg', 'receipt.jpg');

$ch = curl_init($base . '/upload-receipt');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $api_secret,
    ],
    CURLOPT_POSTFIELDS     => [
        'order_id' => $order_id,
        'receipts' => $file,
    ],
    CURLOPT_TIMEOUT        => 60,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

کدهای خطاهای رایج

• 401: API Secret اشتباه یا نبود هدر Authorization
• 400: پارامتر ناقص (مثل نبودن amount یا فایل)
• 404: تراکنش pending با این مبلغ پیدا نشد یا سفارش نیست
• 500: خطای آپلود فایل

سناریوی عملی پیشنهادی

1. مشتری سفارش می‌دهد و مبلغ یکتا می‌گیرد (مثلاً 10540236).
2. سیستم شما از بانک یا پیامک مبلغ واریزی را می‌خواند.
3. همان مبلغ را به POST /confirm می‌فرستید.
4. اگر success: true بود، سفارش در ووکامرس پرداخت شده است.
5. اگر تایید خودکار ممکن نبود، فیش را با upload-receipt بفرستید تا ادمین یا ربات بررسی کند.
6. در این بین می‌توانید با GET /status وضعیت را مانیتور کنید.

نکات امنیتی

• API Secret را مثل رمز عبور نگه دارید؛ داخل فرانت‌اند عمومی نگذارید.
• ترجیحاً فقط از سرور خودتان به confirm درخواست بزنید.
• HTTPS را جدی بگیرید.
• اول روی staging تست کنید، بعد روی سایت اصلی.

دانلود افزونه

https://wordpress.org/plugins/webdide-card-to-card-verification/