چگونه پرداخت API برای ارائه دهندگان کار می کند

API پرداخت یک قرارداد بین برنامه شما و ارائه دهنده است که «ایجاد پرداخت»، «تأیید» 3DS, «بازگشت وجوه»، «پرداخت مشتری» و «دریافت وضعیت» را به تماس های قابل اعتماد و قابل تکرار تبدیل می کند. در زیر کاپوت ده ها تن از قوانین وجود دارد: نشانه گذاری، idempotency، webhooks، ضد تقلب، صف، SLA و حسابرسی. در زیر یک نقشه عملی از چگونگی این کار برای اکثر ارائه دهندگان است.

مدل پایه: چه موجودیتهایی تقریبا همیشه وجود دارند

پرداخت/شارژ - تلاش برای نوشتن (اجازه + ضبط یا بلافاصله خرید).

روش پرداخت - کارت (PAN/token)، حساب بانکی/نام مستعار، کیف پول، روش محلی.

مشتری - نهاد مشتری/پرداخت (گاهی اوقات اختیاری).

پرداخت/انتقال - پرداخت خروجی به مشتری/بازرگان.

بازپرداخت/برگشت - بازگشت به پرداخت اصلی (حلقه بسته).

Webhook Event - اعلان وضعیت ناهمزمان.

اختلاف/بازپرداخت - اختلاف بر سر شبکه پرداخت (برای کارت).

سفارش/فاکتور - زمینه کسب و کار در اطراف پرداخت.

احراز هویت و امنیت

کلیدهای API/OAuth 2. 0/mTLS - برای سرور به سرور.

نشانه های مشتری نشانه های یکبار مصرف برای ظاهر هستند (به طوری که اسرار را درخشان نکنند).

نشانه گذاری کارت - PAN به ارائه دهنده می رود ؛ تو فقط ژتون را نگه ميداري.

PCI DSS - اگر شما یک PAN را مشاهده می کنید، شما در منطقه PCI هستید ؛ بهتر است برای جلوگیری و استفاده از زمینه های میزبان/SDK ها.

وب سایت امضای HMAC - بررسی اینکه رویداد از ارائه دهنده آمده است.

معماری دو منطقه - جبهه عمومی (JS/SDK) و باطن خصوصی (کلید، منطق خطر).

Idempotency، صف و ثبات

Idempotency-Key در هدر: تکرار درخواست (با اتمام وقت) تکراری ایجاد نمی کند.

Outbox/Saga با شما: برای «ارسال پرداخت → نوشتن به دفتر کل → منتظر webhook» موافقت شد.

Retray with backoff - فقط برای خطاهای موقت. ماتریس قابل استرداد/غیر قابل برگشت مورد نیاز است.

نقاط پایانی معمولی (طرح ها و جریان)

1) کارت (ویزا/مسترکارت، و غیره)

POST/payments - ایجاد یک پرداخت («مقدار»، «ارز»، «پرداخت _ روش _ token»، «گرفتن» = نادرست/درست).

POST/payments/{ id }/confirm - шаг 3-D Secure 2 (نتیجه چالش/تغییر مسیر).

POST/پرداخت/{ id }/ضبط - ضبط پس از مجوز (جزئی/کامل).

POST/payments/{ id }/refund - بازگشت (در قطعات، تا مقدار اصلی).

GET/payments/{ id} - статус (مجاز، ضبط شده، خراب، requires_action).

3-D Secure/SCA: ارائه دهنده 'requires _ action' + 'client _ secret '/URL را برای چالش بازگرداند. پس از تایید توسط مشتری، جلو نتیجه را به backend شما باز می گرداند → شما «/confirm »را بکشید.

2) A2A/بانکداری باز (پرداخت توسط بانک)

POST/payments → پاسخ از «redirect _ url» به بانک مشتری.

مشتری توسط بانک مجاز است → پرداخت وب هوک. موفق/شکست خورده "

GET/payments/{ id} - وضعیت نهایی (اغلب فقط ناهمزمان).

3) روش های محلی (PIX، PayID، FPX، iDEAL و غیره)

POST/payments → دریافت 'qr _ code '/' deeplink '/' copy _ code'.

نمایش کاربر، منتظر webhook در مورد ثبت نام.

زمان بندی کد و TTL ها بخشی از قرارداد هستند.

4) پرداخت

POST/payouts («مقدار»، «ارز»، «مقصد _ token» или «کارت _ token »/« bank _ alias»).

GET/payouts/{ id} - статусы («صف»، «ارسال شده»، «پرداخت شده»، «شکست خورده»).

صفحه وب سایت. پرداخت/شکست خورده "منبع حقیقت است.

حلقه بسته: بهتر است قبل از گزینه های دیگر به منبع (معکوس) پرداخت شود.

بایگانی برچسب: «منبع حقیقت»

رویدادها: "پرداخت. در انتظار/مجاز/اسیر/شکست خورده «،» پرداخت. requires_action'، پس بده موفق شد، پرداخت کند. پرداخت، مشاجره. ایجاد شده و غیره

تحویل: با بازپرداخت امضا شده توسط HMAC، اغلب «حداقل یک بار» → نگه داشتن کنترل کننده idempootent.

بهترین عمل: پردازش webhook → به روز رسانی دفتر → پاسخ 2xx. هر منطق تجاری بعد از آن ناهمگام است.

خطا و پردازش وضعیت

کدهای HTTP: موفقیت «2xx» ؛ خطای مشتری «4xx» (اعتبارسنجی، تقلب/ورشکستگی بانکی، توکن نادرست) ؛ «5xx» - ارائه دهنده.

Причины отказов: «ناکافی _ بودجه»، «آیا _ نه _ افتخار»، «سرقت رفته _ کارت»، «حد _ بیش از»، «خطر _ کاهش»، «بانک _ در دسترس نیست».

پنجره های Redo: برای 3DS - شما نمی توانید بی وقفه عقب نشینی کنید ؛ برای A2A - TTL های تغییر مسیر/کد معتبر هستند ؛ برای پرداخت - عقب نشینی.

ضد ریزش و خطر

اثر انگشت دستگاه و داده های رفتاری - از طریق JS/SDK ارائه دهنده یا لایه خود.

لیستها: خطر BIN، لیستهای سیاه/سفید روشها/ASN/کشورها.

دروازه های قابل تنظیم: محدودیت در ابزار جدید، خنک کردن، سرعت، چک آستانه RG/AML.

سیاست ها: «پاس/گام به بالا/نگه دارید/بلوک» بر اساس به ثمر رساند + قوانین.

ویژگی های ریل

کارت ها: مجوز در مقابل پاکسازی (مقدار را می توان تغییر داد)، 3DS2، بازده معامله اصلی، اختلافات/بازپرداخت.

بانکداری A2A/Open: تغییر مسیر/رضایت جریان، apruv بالا، کم هزینه ؛ همه چیز ناهمزمان و بسیار وابسته به بانک است.

سریع محلی: QR/نام مستعار، وب سایت فوری، TTL و کامپایل دقیق.

OCT/Push-to-Card (پرداخت کارت): شما نیاز به نشانه های کارت، پشتیبانی سریع از صادر کننده، بدون 3DS دارید.

نسخه و سازگاری

نسخه های API: '/v1 '، «نسخه های داده» در هدر یا phicheflags.

تغییرات سازگار با عقب: فقط زمینه های غیر مخرب.

مستهلک: برنامه برای خروج از نسخه های قدیمی، راهنماهای مهاجرت، webhooks تکراری در طول مهاجرت.

قابلیت مشاهده و SLA

معیارها: مجوز p95/زمان پرداخت، نرخ تایید توسط BIN/بانک/روش، سهم retrays، webhooks-lag.

سیاهههای مربوط: همبستگی با 'request _ id'، 'idempotency _ key'، 'payment _ id'.

هشدارها: افزایش امتناع برای یک بانک/کشور خاص، افزایش مدت زمان، رویدادهای تکراری.

رفت و برگشت و امور مالی

لجر: ورود دو، سیاهههای مربوط غیر قابل تغییر، مجاز/دستگیر/مسترد 'statuses.

کامپایل سه طرفه: دفتر کل ↔ وب سایت شما ↔ گزارش های ارائه دهنده/بانک.

منابع: «provider _ reference»، «network _ reference»، «payout _ reference» را نگه دارید - این موجب صرفه جویی در پشتیبانی می شود.

جعبه شن و ماسه، صدور گواهینامه و تولید

Sandbox: تست نشانه ها/کارت ها/بانک ها، شبیه سازی 3DS/redirects، «دکمه ها» برای وضعیت های webhook.

موارد تست: موفقیت/شکست، چالش 3DS، وقفه ارائه دهنده، webhook تکراری، ضبط/بازپرداخت جزئی، لغو تغییر مسیر، عدم پرداخت.

Go-live: کلیدهای prod، دامنه های webhook، IP-allowlist، ضد تقلب را فعال کنید، محدودیت ها و هشدارها را تنظیم کنید.

نمونه های کوچک (شماتیک)

ایجاد پرداخت (کارت)


پست/v1/پرداخت
{
"مقدار": 9232، "ارز": "EUR"، "payment_method_token": "pm_tok_123,": "ضبط": درست، "ابرداده": {"order _ id": "ORD-1001"}
}
→ 200 {"شناسه": "pay_abc," "وضعیت": "requires_action," "next_action": {"نوع ": "تغییر مسیر"، "url ":"..."}

Webhook در ثبت نام موفق


پست/کتابهای وب
{
"نوع": "پرداخت. captured «», «data»: {«id»: «pay _ abc», «amount»: 9232, «currency»: «EUR», «metadata»: {«order _ id»: «ORD-1001»}
}

پرداخت وجه


پست/v1/پرداخت
{
"مقدار": 5000، "ارز": "EUR"، "destination_token": "dest_tok_456," "ابرداده": {"user _ id":" u _ 77"}
}

چک لیست پیاده سازی

1. معماری کلیدی: اسرار سرور به طور جداگانه، اسرار مشتری - یک بار.

2. Idempotency: در هر تماس نوشتن + دستگیره webhook idemotent.

3. Webhooks: امضای HMAC، retrai، صف کار، نظارت بر تاخیر.

4. 3DS/SCA و تغییر مسیرها: مدیریت لغو/زمان، تلاش دوباره friend-UX.

5. Antifraud/محدودیت: سرعت، جزئیات جدید، لیست سیاه، آستانه RG/AML.

6. لجر و آشتی: ورود دو طرفه، آشتی سه طرفه، هشدار ناهنجاری.

7. ارکستراسیون: ارائه دهنده یدکی، قوانین مسیریابی توسط BIN/کشور/مقدار.

8. نظارت: داشبورد تایید نرخ/p95/retrays، هشدار توسط بانک ها/روش ها.

9. قانونی/PCI: نشانه گذاری، سیاست بازده، حلقه پرداخت بسته.

10. طرح تخریب: کانال kill-switch، صف، حالت دستی برای عملیات بحرانی.

اشتباهات مکرر

ذخیره سازی PAN در کنار آن بدون PCI و tokenization.

بدون idempotency → پرداخت های تکراری/پرداخت با وقفه.

منطق در پاسخ های همزمان بدون در نظر گرفتن webhooks.

یک ارائه دهنده به بازار، بدون عقب نشینی/آبشار.

بدون پردازش 3DS خنثی/تغییر مسیر → سطل بازیافت از دست رفته.

یک بسته نرم افزاری ضعیف → معاملات «یخ زده» و «از دست رفته».

عدم وجود SLA ها و هشدارهای واضح مشکلی که مشتری می بیند، نه شما.

مینی سوالات متداول

کدام قابل اعتماد تر است: وضعیت همزمان یا webhook ؟

Webhook منبع حقیقت است ؛ پاسخ همزمان - تنها «عمل پذیرفته/مورد نیاز».

آیا می توان بدون 3DS کار کرد ؟

بستگی به قانون/ریسک دارد. در EC/UK - SCA اجباری است. برای ریسک بالا، گام به گام بهتر است.

چگونه نرخ بهره را افزایش دهیم ؟

BIN/بانک/روش ارکستراسیون، ریل های محلی، retras هوشمند، توصیفگرهای صحیح، ضد تقلب FPR پایین.

چرا پرداخت «فوری» نیست ؟

بستگی به راه آهن (OST/A2A/محلی)، بانک و محدودیت های گیرنده دارد. بیایید یک پنجره SLA صادقانه و جریان وضعیت داشته باشیم.

پرداخت های API نه تنها "ایجاد پرداخت. "این نظم و انضباط: احراز هویت امن → نشانه گذاری → idempotency → webhooks ناهمزمان → دفتر کل و تاشو → ضد تقلب/AML → ارکستراسیون و نظارت. فرآیند را با توجه به این طرح بسازید، کانال های یدکی و UX شفاف را حفظ کنید - و لایه پرداخت شما سریع، قابل پیش بینی و مقاوم در برابر شکست بانک ها و ارائه دهندگان خواهد بود.