راهنمای جامع اتصال به درگاه کارت‌گذر

{
  "status": "success",
  "order_token": "ord_a94f1082cba3e47b",
  "payment_url": "https://payments.cardgozar.ir/pay/ord_a94f1082cba3e47b",
  "base_amount": 12000000,
  "final_amount": 12034500,
  "final_amount_tomans": 1203450,
  "unique_code": 3450,
  "expires_in_seconds": 900
}

{
  "status": "PAID",
  "is_paid": true,
  "is_expired": false,
  "order_token": "ord_a94f1082cba3e47b",
  "merchant_order_id": "INV-84920",
  "base_amount_tomans": 1200000,
  "unique_code": 3450,
  "final_amount_rials": 12034500,
  "final_amount_tomans": 1203450,
  "ref_id": "94821038",
  "payer_card": "****-2841",
  "paid_at": "2026-10-16T13:10:45Z"
}

X-CardGozar-Signature: 8f4a1c6e7b89... (HMAC-SHA256 signature calculated with your API Secret)

کد استاندارد PHP با cURL جهت اتصال وب‌سایت یا افزونه وردپرس/ووکامرس:

<?php
$apiKey = "YOUR_API_KEY";
$apiSecret = "YOUR_API_SECRET";
$baseUrl = "https://cardgozar.ir";

// ۱. ایجاد تراکنش جدید
function createOrder($amountRials, $orderId, $callbackUrl) {
    global $apiKey, $baseUrl;
    
    $payload = json_encode([
        'amount' => $amountRials,
        'order_id' => $orderId,
        'callback_url' => $callbackUrl,
        'description' => 'خرید سفارش ' . $orderId
    ]);

    $ch = curl_init($baseUrl . "/api/v1/payments/create/");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);
    if ($httpCode === 201 && isset($result['payment_url'])) {
        header("Location: " . $result['payment_url']);
        exit;
    } else {
        die("خطا در ایجاد درگاه: " . ($result['error'] ?? 'نامشخص'));
    }
}
?>

نمونه کد پایتون با کتابخانه requests:

import requests

BASE_URL = "https://cardgozar.ir"
API_KEY = "YOUR_API_KEY"

def create_payment(amount_rials, order_id, callback_url):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "amount": amount_rials,
        "order_id": order_id,
        "callback_url": callback_url,
        "description": f"Order {order_id}"
    }
    res = requests.post(f"{BASE_URL}/api/v1/payments/create/", json=payload, headers=headers)
    if res.status_code == 201:
        data = res.json()
        return data['payment_url']
    raise Exception(res.json().get('error'))

نمونه کد Node.js با کتابخانه axios:

const axios = require('axios');

const BASE_URL = 'https://cardgozar.ir';
const API_KEY = 'YOUR_API_KEY';

async function createPayment(amountRials, orderId, callbackUrl) {
    const res = await axios.post(`${BASE_URL}/api/v1/payments/create/`, {
        amount: amountRials,
        order_id: orderId,
        callback_url: callbackUrl,
        description: `Order ${orderId}`
    }, {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    return res.data.payment_url;
}

دستورات خط فرمان جهت تست سریع با cURL از ترمینال:

curl -X POST https://cardgozar.ir/api/v1/payments/create/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000000, "order_id": "TEST-101", "callback_url": "https://myshop.ir/cb"}'