API کارت‌به‌کارت

این فایل جزئیات فنی کامل API رو داره (برای کسانی که مستقیم با API کار می‌کنن، نه از طریق SDK). اگه فقط می‌خواید سریع وصل بشید، به‌جاش generic-integration-guide.md رو ببینید.

🚀 شروع سریع (تماس مستقیم با API)

برای استفاده از API نیاز به یک توکن دسترسی (API Token) دارید. این توکن رو از ربات مدیریت فروشندگان (@cubepy_bot) بعد از ثبت‌نام و تایید حساب دریافت می‌کنید.

توکن باید در هدر هر درخواست به این شکل ارسال بشه:

Authorization: Bearer YOUR_API_TOKEN

⚠️ نکته‌ی مهم: برخلاف بعضی درگاه‌ها، آدرس‌های زیر با پسوند .php هستن — حتماً دقیقاً همون‌طور که تو پنل فروشنده‌تون نوشته کپی کنید.

🛒 ایجاد تراکنش (Create Payment)

Endpoint:

POST https://cubevps.ir/smspay/api/create-payment.php

📋 پارامترها

⚠️ order_id نباید با topup- شروع شود — این پیشوند برای شارژ کیف‌پول پلتفرم رزرو شده و 422 می‌گیرید.

✅ نمونه پاسخ موفق

{
  "success": true,
  "authority": "bdc9e0497c121d6187750d53798dae81",
  "payment_link": "https://cubevps.ir/smspay/pay.php?authority=bdc9e0497c121d6187750d53798dae81",
  "pay_amount": 200720,
  "pay_amount_toman": 20072,
  "is_test": false,
  "card": {
    "number": "6219861900412221",
    "holder": "نام صاحب کارت",
    "sheba": null
  },
  "expires_at": "2026-09-11T18:27:00+03:30",
  "expires_in_minutes": 30,
  "show_card_in_bot": false
}

🤖 card برای چیه؟ اگه فروش‌تون از طریق رباته و نمی‌خواید مشتری رو به صفحه‌ی وب بفرستید، با همین فیلدها می‌تونید پرداخت رو مستقیم داخل ربات خودتون نشون بدید (شماره کارت، نام صاحب کارت، مبلغ دقیق، مهلت) — نمونه‌ی آماده در راهنمای اتصال عمومی.

🎛 show_card_in_bot یعنی چی؟ خواسته‌ی خودتونه که تو ربات تنظیم کردید — «🏪 فروشگاه من → 💳 روش‌های پرداخت → 🤖 نمایش کارت در ربات». ما کاری نمی‌کنیم، فقط این خواسته رو به کدِ شما اعلام می‌کنیم: اگه true بود یعنی «کارت رو تو ربات هم نشون بده». واسطِ آماده‌ی میرزابات خودش ازش پیروی می‌کنه؛ اگه کدِ خودتون رو نوشتید، هرطور خواستید ازش استفاده کنید (یا کلاً نادیده بگیرید). 👉 اینکه بسته به نوعِ اتصال‌تون دقیقاً باید چی‌کار کنید: نمایش کارت داخل ربات.

⚠️ کارت رو از قبل ذخیره و تکرار نکنید: اگر «چرخش کارت» را روشن کرده باشید، هر فاکتور ممکن است کارتِ متفاوتی بگیرد. همیشه همان کارتی را نشان دهید که در پاسخِ همین فاکتور آمده است.

📌 pay_amount_toman را جدی بگیرید: این مبلغ دقیق قابل‌پرداخت است، نه لزوماً همون عددی که خودتون فرستادید. سیستم برای اینکه بتونه پیامک‌های بانکی رو دقیق تشخیص بده، چند تومان تصادفی به مبلغ اضافه می‌کنه (مثلاً ۲۰,۰۰۰ می‌شه ۲۰,۰۷۲). اگر «سهم مشتری از کارمزد» را هم تنظیم کرده باشید، آن هم به همین مبلغ اضافه می‌شود. لینک payment_link رو مستقیم به مشتری بدید — خود صفحه‌ی پرداخت این مبلغ دقیق رو به‌وضوح نشون می‌ده، نیازی نیست خودتون چیزی محاسبه کنید.

❌ نمونه پاسخ خطا

{
  "success": false,
  "message": "مبلغ نامعتبر است (ریال، حداقل ۱۰۰۰)."
}

🔍 تایید تراکنش (Verify Payment)

Endpoint:

POST https://cubevps.ir/smspay/api/verify-payment.php

📋 پارامترها

✅ نمونه پاسخ (اولین تایید موفق)

{
  "success": true,
  "message": "پرداخت تایید شد.",
  "order_id": "ORD123",
  "amount": 200000,
  "status": "verified",
  "match_confidence": 100,
  "match_flags": []
}

📌 پاسخ‌های دیگر (بسته به وضعیت فعلی تراکنش)

⚠️ فقط اولین فراخوانی موفق verify-payment مقدار success: true برمی‌گردونه. این عمداً این‌طوریه تا اگه به‌هر دلیلی (رفرش کاربر، تلاش دوباره‌ی خودتون و…) دوبار صدا زده بشه، سرویس/شارژ رو دوبار به کاربر ندید.

⏳ اعتبار و قوانین تراکنش

• هر فاکتور به‌طور پیش‌فرض ۳۰ دقیقه اعتبار داره؛ بعدش منقضی می‌شه و پرداخت دیگه امکان‌پذیر نیست. برای هر فاکتور می‌تونید با ttl_minutes (بین ۵ تا ۱۴۴۰ دقیقه) این مهلت رو خودتون تعیین کنید.
• اگه با یک order_id تکراری دوباره create-payment بزنید، و فاکتور قبلی هنوز در انتظار پرداخت باشه، همون authority/payment_link قبلی برگردونده می‌شه (فاکتور جدید ساخته نمی‌شه).
• مبلغ‌ها همه‌جا (درخواست و پاسخ) به ریال هستن، مگر جایی که صراحتاً «تومان» نوشته شده باشه (مثل pay_amount_toman).

🔄 اطلاعات ارسالی به callback_url

به‌محض تشخیص واریز (از روی پیامک بانکی)، این درخواست به آدرس callback_url شما ارسال می‌شه:

به‌صورت POST (بدنه‌ی JSON):

{
  "success": true,
  "status": "paid",
  "authority": "bdc9e0497c121d6187750d53798dae81",
  "order_id": "ORD123",
  "amount": 200000
}

و همزمان به‌صورت querystring هم به همون آدرس اضافه می‌شه (برای سازگاری با بک‌اندهایی که فقط GET رو می‌خونن):

?authority=...&order_id=...&status=paid

📌 بعد از دریافت این کال‌بک، حتماً verify-payment رو صدا بزنید تا مطمئن بشید (این کال‌بک صرفاً یه اطلاع‌رسانیه، نه تاییدیه‌ی نهایی).

🔐 این آدرس امضا ندارد. هر کسی که آدرس سرور شما را بداند می‌تواند یک POST جعلی بفرستد. پس کال‌بک را فقط به‌عنوان «بیدارباش» بگیرید و تصمیم نهایی را تنها بر اساس پاسخ verify-payment بگیرید.

⏱ کال‌بک دوباره فرستاده نمی‌شود. تایم‌اوت ۱۰ ثانیه است و حداکثر ۳ ریدایرکت دنبال می‌شود؛ اگر سرور شما آن لحظه در دسترس نباشد، تلاش مجددی در کار نیست. برای همین فاکتورهای pending را خودتان هم گاهی با status.php بررسی کنید تا سفارش مشتری معلق نماند.

💻 نمونه کدها

🐘 PHP

<?php
$accessToken = "YOUR_API_TOKEN";

$data = [
    "amount" => 200000,
    "order_id" => "ORD123",
    "callback_url" => "https://yourbot.example.com/callback.php",
    "type" => "card",
    "description" => "شارژ کیف پول",
    "customer_user_id" => "123456789",
];

$ch = curl_init("https://cubevps.ir/smspay/api/create-payment.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer {$accessToken}",
]);

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

if (!empty($result['success'])) {
    echo "لینک پرداخت: " . $result['payment_link'];
} else {
    echo "خطا: " . $result['message'];
}

🐍 Python

import requests

url = "https://cubevps.ir/smspay/api/create-payment.php"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_TOKEN",
}
data = {
    "amount": 200000,
    "order_id": "ORD123",
    "callback_url": "https://yourbot.example.com/callback",
    "type": "card",
    "description": "شارژ کیف پول",
}

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

🟢 Node.js

const axios = require("axios");

const data = {
  amount: 200000,
  order_id: "ORD123",
  callback_url: "https://yourbot.example.com/callback",
  type: "card",
};

axios.post("https://cubevps.ir/smspay/api/create-payment.php", data, {
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_TOKEN",
  },
})
  .then((res) => console.log(res.data))
  .catch((err) => console.error(err.response?.data));

💻 cURL

curl -X POST https://cubevps.ir/smspay/api/create-payment.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "amount": 200000,
    "order_id": "ORD123",
    "callback_url": "https://yourbot.example.com/callback",
    "type": "card"
  }'

📎 نمونه کد کامل‌تر (Laravel، کلاینت PHP آماده و…) در examples/.

📎 برای اسپک کامل ماشین‌خوان، فایل openapi.yaml رو ببینید، یا مستقیم امتحانش کنید:

• 🧪 باز کردن در Swagger Editor
• 💻 مشاهده در VS Code (وب)

⚠️ کدها و پیام‌های رایج

🔗 لینک‌ها

🤖 ربات مدیریت فروشندگان: @cubepy_bot