پرداخت‌ها و وضعیت‌هایشان
شیء پرداخت، روش‌های پرداخت و مقصد آن، مبلغ یکتا، اینکه رسیدها و واریزها چطور پرداخت را کامل می‌کنند و همهٔ وضعیت‌هایی که یک پرداخت می‌تواند داشته باشد.
پرداخت یعنی مبلغی که برای یک سفارش می‌خواهید دریافت کنید. مشتری آن را کارت‌به‌کارت یا با انتقال بانکی، مستقیم به کارت یا حساب شما می‌پردازد و یک رسید می‌فرستد. پولی که تیم شما از روی رسید تأیید می‌کند، یا پیامک بانک نشان می‌دهد که رسیده، یک واریز است. پرداخت آن‌قدر واریز جمع می‌کند تا به مبلغش برسد؛ برای همین واریز اشتباه هیچ‌وقت به بن‌بست نمی‌رسد.
ساخت پرداخت
POST /v1/payments این پارامترها را می‌گیرد:
| پارامتر | توضیح |
|---|---|
amount | الزامی. عدد صحیح به ریال، از ۱۰٬۰۰۰ تا ۲٬۰۰۰٬۰۰۰٬۰۰۰. |
reference | شمارهٔ سفارش شما، تا ۱۰۰ نویسه. روی صفحهٔ پرداخت نشان داده می‌شود و در داشبورد قابل جست‌وجوست. |
description | تا ۵۰۰ نویسه. |
customer یا customer_details | شناسهٔ یک مشتری موجود (cus_…)، یا { name, phone, email }. |
return_url، cancel_url | جایی که صفحهٔ پرداخت مشتری را با وضعیت امضاشده برمی‌گرداند. صفحهٔ پرداخت را ببینید. |
expires_in | چند ثانیه صفحهٔ پرداخت باز می‌ماند، از ۳۰۰ تا ۸۶٬۴۰۰. پیش‌فرض همان تنظیم صفحهٔ پرداخت شماست (۳۰ دقیقه). |
allow_partial | چند واریز را برای رسیدن به مبلغ بپذیرد. پیش‌فرض تنظیم پرداخت‌های شماست (روشن). |
card | شناسهٔ مقصد (card_…): کارت یا حسابی که یکی از روش‌های پرداخت روشن شما را بپذیرد. پیش‌فرض، روش تقسیم شماست (مقصد پیش‌فرض، نوبتی یا کم‌مصرف‌ترین). |
metadata | تا ۵۰ کلید متنی تا ۴۰ نویسه، با مقدار تا ۵۰۰ نویسه. |
curl https://a.bezanbecard.com/v1/payments \
-H "Authorization: Bearer sk_test_…" \
-H "Idempotency-Key: order-1042" \
-H "Content-Type: application/json" \
-d '{"amount":12500000,"reference":"1042","customer_details":{"name":"Test Customer","phone":"09900001234"},"metadata":{"order_id":"1042"}}'روش‌ها و مقصد
payment_method_types می‌گوید مشتری چطور می‌تواند بپردازد: card (کارت‌به‌کارت) و transfer (پل، پایا، ساتنا یا انتقال داخلی همان بانک به شبا). این فهرست هنگام ساخت پرداخت ثابت می‌شود، از روش‌هایی که روشن کرده‌اید و مقصدش می‌پذیرد.
destination می‌گوید پول به کجا می‌رود: card (شناسهٔ مقصد)، type (card یا account)، bank، last4 (برای حساب null)، iban_last4 و holder_name. با کلید مخفی pan و iban کامل را هم برای صفحهٔ پرداخت سفارشی دارد. جزئیات در انتقال بانکی است.
مبلغ یکتا
رسید یا پیامک بانک می‌گوید چه مبلغی به کدام کارت یا حساب رسیده و تقریباً هیچ چیز دیگر. برای اینکه واریزها از هم جدا بمانند، هر پرداخت مبلغی می‌خواهد که هیچ پرداخت باز دیگری روی همان مقصد نمی‌خواهد: expected_amount. این مبلغ برابر amount به‌علاوهٔ یک عدد یکتای کوچک است (به‌طور پیش‌فرض بین ۱٬۰۰۰ تا ۹۹٬۹۹۰ ریال، با گام ۱۰؛ در تنظیمات پرداخت می‌توانید به‌جای افزودن، آن را کم کنید).
مشتری دقیقاً expected_amount را می‌پردازد و پرداخت کامل همین مبلغ یعنی پرداخت کامل amount: عدد یکتا هیچ‌وقت بیش‌واریز حساب نمی‌شود. صفحهٔ پرداخت میزبانی‌شده این مبلغ را نشان می‌دهد و با یک لمس کپی می‌کند. اگر صفحهٔ پرداخت خودتان را می‌سازید، expected_amount را (و نه amount را) با رقم دقیق ریالی نشان دهید.
مبلغ یکتا را می‌توانید در تنظیمات پرداخت خاموش کنید. آن وقت expected_amount با amount برابر است: برای مشتری ساده‌تر، ولی پیامک بانک دیگر نمی‌تواند دو پرداخت باز با یک مبلغ را از هم جدا کند. مبلغ یکتا، روشن یا خاموش را ببینید.
پرداخت چطور کامل می‌شود
- مشتری از اپ بانکی‌اش پرداخت می‌کند و روی صفحهٔ پرداخت رسید می‌فرستد. پرداخت در انتظار تأیید
processingمی‌شود. - یکی از اعضای تیم شما رسید را در رسیدها تأیید می‌کند. تأیید، واریزی به همان مبلغ روی پرداخت می‌گذارد.
- پرداخت از روی واریزهایش دوباره حساب می‌شود: وقتی به
amountبرسند موفقsucceeded، وقتی کمتر باشند کم‌واریزpartially_paidبا مبلغ تکمیلی، و وقتی بیشتر باشند بیش‌واریز.
تیم شما می‌تواند رسید را رد هم بکند (پرداخت منتظر رسید دیگری می‌ماند)، پرداخت را مستقیم تأیید کند یا واریزی را دستی وصل کند. رسیدها و بررسی و اصلاح‌ها را ببینید.
واریز بانکی چطور به پرداخت وصل می‌شود
واریز بدون رسید هم می‌رسد: از اپ دریافت پیامک که اختیاری است، وقتی دستی ثبتش می‌کنید، یا وقتی در حالت آزمایشی شبیه‌سازی‌اش می‌کنید. آن وقت بزن به کارت پرداخت‌های باز همان کارت یا حساب را به این ترتیب بررسی می‌کند و با اولین قاعده‌ای که دقیقاً یک پرداخت پیدا کند متوقف می‌شود:
- مبلغ دقیق. پرداختی که
expected_amountفعلی‌اش با واریز برابر است. - مبلغ قبلی. پرداختی که پیش از صدور مبلغ تکمیلی همین مبلغ را خواسته بود.
- کارت پرداخت‌کننده و ادعای واریز. پیامک کارت مبدأ را دارد و در دو ساعت گذشته فقط در یک پرداخت مشتری با همان چهار رقم آخر کارت‌به‌کارت را اعلام کرده است. مبلغ اشتباه این‌طور گرفته می‌شود: کمتر، پرداخت ناقص می‌شود و بیشتر، پرداخت موفق با بیش‌واریز.
- تنها ادعای اخیر. فقط یک پرداخت با ادعای واریز تازه منتظر است و واریز حداکثر نصف مبلغ آن کمتر یا بیشتر است. ادعای پایا یا ساتنا مدت بیشتری تازه می‌ماند. این فقط یک پیشنهاد است: پرداخت به بررسی می‌رود و یک نفر تأییدش می‌کند.
قاعده‌ای که دو پرداخت پیدا کند هیچ‌وقت حدس نمی‌زند. واریزی که به هیچ قاعده‌ای نخورد با پیشنهادها در صندوق بررسی و اصلاح داشبورد می‌ماند تا خودتان وصلش کنید. وقتی رسیدی روی پرداخت با واریز جور باشد، پیامک به‌جای اینکه دوباره حساب شود رسید را تطبیق می‌دهد.
وقتی تأیید خودکار خاموش است (پیش‌فرض)، واریزی که این قاعده‌ها کامل وصلش کنند پرداخت را خودبه‌خود کامل نمی‌کند: پرداخت با auto_disabled به بررسی می‌رود و یک نفر تأییدش می‌کند.
وضعیت‌ها
| وضعیت | معنی |
|---|---|
در انتظار واریزrequires_payment | منتظر اینکه مشتری expected_amount را بپردازد و رسید بفرستد. |
در انتظار تأییدprocessing | مشتری رسید فرستاده یا گفته پرداخت کرده است. منتظر بررسی تیم شما. |
کم‌واریزpartially_paid | واریزهای تا این لحظه کمتر از amount است. amount_remaining هنوز مانده و برایش مبلغ یکتای تازه صادر شده است. |
نیاز به بررسیrequires_review | یک نفر باید تصمیم بگیرد. review.reason دلیلش را می‌گوید. |
موفقsucceeded | واریزها به amount رسیده، یا یکی از اعضای تیم پرداخت را تأیید کرده است. |
لغوشدهcanceled | پیش از موفق شدن لغوش کرده‌اید. |
منقضیexpired | تا بسته شدن صفحهٔ پرداخت نه پولی رسیده و نه رسیدی فرستاده شده است. |
پرداختی که رسید در انتظار دارد تا تصمیم تیم شما processing می‌ماند؛ هیچ زمان‌سنجی آن را جابه‌جا نمی‌کند. پرداخت لغوشده یا منقضی‌شده تا پایان مهلت اضافه بعد از انقضای صفحهٔ پرداختش (به‌طور پیش‌فرض ۶۰ دقیقه، و بعد از ادعای پایا یا ساتنا بیشتر: مهلت انتظار انتقال را ببینید) هنوز واریز دیررسیده را می‌گیرد و دوباره باز می‌شود. بعد از آن فقط وصل کردن دستی به آن می‌رسد.
دلیل‌های بررسی
review.reason | چرا پرداخت منتظر یک نفر است |
|---|---|
no_sms | فقط برای اعلام پرداختی که پیش از رسیدها ثبت شده: در زمانی که چنین انتقالی معمولاً طول می‌کشد، یا تا پایان مهلت اضافه، پیامک بانکی جور نرسیده است. رسید بدون فایل، از صفحهٔ پرداخت یا /claim، در صف رسیدها می‌ماند (پرداخت در انتظار تأییدprocessing می‌ماند) تا یکی از اعضا تصمیم بگیرد. |
expired_partial | بخشی از پول رسیده و صفحهٔ پرداخت پیش از رسیدن بقیه بسته شده است. |
partial_disabled | واریزی کمتر از مبلغ رسیده، در حالی که پرداخت ناقص برای این پرداخت خاموش است. |
payer_mismatch | واریز خودکار وصل شده، ولی کارت پرداخت‌کننده هیچ‌کدام از کارت‌هایی نیست که مشتری اعلام کرده بود. |
amount_mismatch | قاعدهٔ ۴: یک واریز پیشنهادی منتظر تأیید شماست. |
auto_disabled | واریزی که قاعده‌ها وصلش کرده‌اند کل مبلغ را می‌پوشاند؛ وقتی تأیید خودکار خاموش است (پیش‌فرض)، یک نفر تأییدش می‌کند. |
detached | یک اصلاح همهٔ واریزهای پرداختی را که موفق شده بود جدا کرده است. |
کارهایی که برای هر کدام می‌توانید بکنید در اصلاح‌ها آمده است.
فیلدهای مبلغ
| فیلد | توضیح |
|---|---|
amount | مبلغی که خواسته‌اید. هیچ‌وقت عوض نمی‌شود. |
amount_received | پولی که به پرداخت وصل شده (رسیدهای تأییدشده و واریزهای بانکی)، جمع واریزهای آن. |
amount_remaining | مبلغی که هنوز مانده است. |
amount_overpaid | مبلغی که بیشتر از amount رسیده است. بیش‌واریز را ببینید. |
amount_shortfall | مبلغی که با تأیید پرداخت بدون مبلغ کامل بخشیده‌اید. |
expected_amount | مبلغ دقیق واریز (یکتا روی مقصد)؛ وقتی پرداخت بسته شود یا مهلتش بگذرد null است. وقتی رسیدی منتظر بررسی است (processing) یا پرداخت در requires_review است هم پر می‌ماند، پس واریز را بر اساس status بخواهید (requires_payment، partially_paid). |
این فیلدها با هر تغییر از روی واریزهای وصل‌شده دوباره حساب می‌شوند و هیچ‌وقت قدم‌به‌قدم جمع زده نمی‌شوند؛ پس هر اصلاحی آن‌ها را درست نگه می‌دارد.
خواندن، فهرست و ویرایش
GET /v1/payments/:id یک پرداخت را برمی‌گرداند؛ با expand[]=deposits واریزها را کامل، با expand[]=receipts رسیدهایش و با expand[]=customer مشتری را هم می‌گیرید. GET /v1/payments پرداخت‌ها را از جدید به قدیم فهرست می‌کند و بر اساس status، customer، reference و created فیلتر می‌شود (صفحه‌بندی را ببینید).
POST /v1/payments/:id تا وقتی پرداخت باز است description، metadata و customer_details را تغییر می‌دهد. POST /v1/payments/:id/cancel یک پرداخت باز را با reason اختیاری (۳ تا ۵۰۰ نویسه) لغو می‌کند؛ اگر پولی رسیده باشد، پرداخت آن را بدهی شما به مشتری ثبت می‌کند.
رویدادها
هر تغییر وضعیت رویدادی می‌سازد که نقطه‌های دریافت وب‌هوک شما دریافتش می‌کنند: payment.created، payment.processing، payment.partially_paid، payment.requires_review، payment.succeeded، payment.overpaid، payment.overpayment_resolved، payment.canceled، payment.expired و payment.updated. رسیدها رویدادهای خودشان را دارند: receipt.created، receipt.approved و receipt.rejected.