شروع سریع

بزن به کارت نرم‌افزار تطبیق و سند پرداخت برای پول‌هایی است که مستقیم به حساب خودتان می‌گیرید: کارت‌به‌کارت، انتقال با شبا (پل، پایا، ساتنا) یا هر انتقال بانکی دیگر. مشتری از اپ بانکی خودش مستقیم به کارت یا حساب شما واریز می‌کند و رسید بانک را بارگذاری می‌کند. تیم شما همهٔ رسیدها را در یک صف بررسی می‌کند و تأیید یا رد می‌کند، و هر قدم به‌عنوان سند نگه داشته می‌شود. پول هیچ‌وقت از حساب ما نمی‌گذرد.

همهٔ این راهنما در حالت آزمایشی انجام می‌شود: هیچ پولی جابه‌جا نمی‌شود و به اپ دریافت پیامک هم نیازی ندارید.

۱. ساخت حساب

با شمارهٔ موبایلتان ثبت‌نام کنید. یک حساب کسب‌وکار می‌گیرید که در حالت آزمایشی شروع می‌شود؛ کلید بالای داشبورد نشان می‌دهد در کدام حالت هستید.

۲. افزودن کارت یا حساب

پرداخت‌ها به یک مقصد واریز می‌شوند: یک کارت بانکی، یا حسابی که فقط شبایش را دارید، مثل حساب شرکت. در داشبورد به بخش کارت‌ها و حساب‌ها بروید و در حالت آزمایشی یکی اضافه کنید.

• شمارهٔ کارت باید بررسی‌های بانکی را بگذراند (رقم کنترل درست و پیش‌شمارهٔ یک بانک ایرانی). اگر مشتری می‌تواند با انتقال بانکی هم به این کارت پول بفرستد، شبای حساب پشت کارت را هم وارد کنید.
• حساب به شبایش نیاز دارد؛ شبا باید رقم‌های کنترلش درست باشد و به یک بانک شناخته‌شده برسد.
• نام دارنده روی صفحهٔ پرداخت به مشتری نشان داده می‌شود، همان‌طور که اپ بانکی‌اش نشان می‌دهد.

در حالت آزمایشی هیچ پولی به این کارت یا حساب فرستاده نمی‌شود. انتقال بانکی کارت‌ها، حساب‌ها و روش‌های پرداخت را توضیح می‌دهد.

۳. ساخت پرداخت

هر کدام که به کارتان می‌آید:

• در داشبورد: پرداخت‌ها ← پرداخت جدید، بعد صفحهٔ پرداختش را برای مشتری بفرستید.
• بدون کد، برای مشتری‌های زیاد: یک لینک پرداخت.
• از سرور خودتان: با API، مثل پایین.

برای API به توسعه‌دهندگان ← کلیدهای API بروید و یک کلید مخفی بسازید. این کلید با sk_test_ شروع می‌شود و فقط یک بار نمایش داده می‌شود؛ پس آن را در متغیرهای محیطی سرورتان نگه دارید و هرگز در کد مرورگر یا اپ موبایل نگذارید.

export BEZANBECARD_SECRET_KEY=sk_test_…

مبلغ‌ها عدد صحیح و به ریال هستند. 12500000 ریال یعنی یک میلیون و دویست و پنجاه هزار تومان.

curl https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer $BEZANBECARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount":12500000,"reference":"1042","return_url":"https://shop.example/orders/1042/thanks"}'

پاسخ یک شیء payment با وضعیت در انتظار واریزrequires_payment است. فعلاً سه فیلد مهم است:

• checkout_url: صفحهٔ پرداخت میزبانی‌شده که مشتری را به آن می‌فرستید.
• expected_amount: مبلغ دقیقی که مشتری باید بفرستد. این مبلغ با یک عدد یکتای کوچک (به‌طور پیش‌فرض بین ۱٬۰۰۰ تا ۹۹٬۹۹۰ ریال، اضافه بر مبلغ) با amount فرق دارد تا هر پرداخت باز روی یک مقصد رقم متفاوتی بخواهد و هر واریز در صورت‌حساب بانکی‌تان راحت از بقیه جدا شود. مبلغ یکتا را می‌توانید در تنظیمات پرداخت خاموش کنید.
• payment_method_types: card، transfer یا هر دو، بسته به تنظیمات شما و اینکه مقصد کدام را می‌پذیرد.

۴. پرداخت به‌جای مشتری

checkout_url را روی گوشی باز کنید. وقتی مقصد هر دو روش را بپذیرد، صفحه دو زبانه دارد، کارت به کارت و انتقال بانکی، با شمارهٔ کارت یا شبا و مبلغ دقیق برای کپی.

در حالت آزمایشی پولی نفرستید. هر عکس یا اسکرین‌شاتی را به‌عنوان رسید بارگذاری کنید و فرستادن رسید را بزنید. صفحه حالا می‌گوید منتظر تأیید فروشنده است و وضعیت پرداخت در انتظار تأییدprocessing است.

سرور شما هم می‌تواند به‌جای مشتری رسید بفرستد، مثلاً وقتی مشتری آن را در پیام‌رسان برایتان فرستاده است:

curl https://a.bezanbecard.com/v1/payments/pay_…/receipts \
  -H "Authorization: Bearer $BEZANBECARD_SECRET_KEY" \
  -H "Idempotency-Key: receipt-1042-1" \
  -F channel=card \
  -F [email protected]

۵. تأیید رسید

در داشبورد به رسیدها بروید. رسید آنجا کنار پرداختش منتظر است، با مبلغی که پرداخت می‌خواهد و هر چیزی که مشتری نوشته است. فایل را نگاه کنید و تأیید رسید را بزنید. پرداخت موفقsucceeded می‌شود و صفحهٔ پرداختِ باز خودبه‌خود پیام موفقیت را نشان می‌دهد.

رد کردن را هم امتحان کنید: پرداخت دیگری بسازید، رسیدی بفرستید و آن را با دلیلی مثل «رسید خوانا نیست» رد کنید. مشتری دلیل را روی صفحهٔ پرداخت می‌بیند و می‌تواند رسید دیگری بفرستد. رسیدها و بررسی تأیید بخشی از مبلغ، هشدار رسید تکراری و بقیهٔ جزئیات را توضیح می‌دهد.

تأیید از کد خودتان هم ممکن است:

curl https://a.bezanbecard.com/v1/receipts/rcp_…/approve \
  -H "Authorization: Bearer $BEZANBECARD_SECRET_KEY" \
  -H "Idempotency-Key: approve-rcp_…" \
  -H "Content-Type: application/json" \
  -d '{}'

۶. خبردار شدن با وب‌هوک

سرور شما نباید مدام وضعیت را بپرسد. در توسعه‌دهندگان ← وب‌هوک‌ها یک نقطهٔ دریافت بسازید، رویدادهای payment.succeeded و payment.partially_paid را انتخاب کنید (برای خبر از هر رسید تازه receipt.created را هم اضافه کنید) و هدر Bezanbecard-Signature را در هر تحویل بررسی کنید. کد کامل در وب‌هوک‌ها است.

۷. رفتن به حالت واقعی

1. داشبورد را به حالت واقعی ببرید و کارت یا حسابی را که مشتری‌ها به آن واریز می‌کنند اضافه کنید.
2. در تنظیمات انتخاب کنید کدام روش‌های پرداخت را می‌پذیرید و آیا فایل رسید الزامی است (به‌طور پیش‌فرض الزامی است).
3. هم‌تیمی‌هایی را که رسیدها را بررسی می‌کنند دعوت کنید. مالک، مدیر و پشتیبان می‌توانند تأیید و رد کنند؛ توسعه‌دهنده و «فقط مشاهده» فقط می‌بینند.
4. اگر از API استفاده می‌کنید، یک کلید مخفی واقعی (sk_live_…) و یک نقطهٔ دریافت وب‌هوک واقعی بسازید؛ نقطهٔ دریافت واقعی کلید امضای جداگانه دارد.
5. یک پرداخت واقعی کوچک را از اول تا آخر انجام دهید: پرداخت، فرستادن رسید و تأیید.

اپ دریافت پیامک اختیاری است. اگر می‌خواهید پیامک واریز بانک کنار هر رسید بنشیند یا تأیید خودکار داشته باشید وصلش کنید؛ همهٔ مراحل بالا بدون آن هم کار می‌کنند.

دادهٔ آزمایشی و واقعی هیچ‌وقت قاطی نمی‌شوند: کلید آزمایشی فقط پرداخت‌های آزمایشی را می‌بیند و کلید واقعی فقط پرداخت‌های واقعی را.