آماده انتشار

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

همین باعث می‌شود فهرست پایین ارزش داشته باشد که واقعاً طی شود، نه اینکه از رویش رد شوید.

مراقبت از کلیدها

کلید API شما یک اطلاعات محرمانه از نوع bearer است. هر کسی آن را داشته باشد می‌تواند به نام شما جلسه پرداخت بسازد، هر پرداختی که تا امروز گرفته‌اید را بخواند، و شناسه سفارش‌های مشتریانتان را ببیند.

دو کلاس کلید وجود دارد و دو اعتبارنامه جدا هستند: clpay_live_ برای پرداخت‌گیری و clpay_payout_ برای پرداخت به مشتری و بازپرداخت. هر چه پایین می‌آید برای هر دو صدق می‌کند، و این جدایی یک چیز ارزشمند به شما می‌دهد — کلیدی که در بیشترین جاها کپی می‌شود نمی‌تواند از کیف‌پول شما پول بیرون بفرستد.

• فقط سمت سرور. هرگز در باندل مرورگر، فایل اجرایی اپلیکیشن موبایل، مخزن عمومی، لاگ CI یا تیکت پشتیبانی. اگر کلیدی حتی یک بار در هر یک از این‌ها بوده، لو رفته است، مستقل از آنچه بعد از آن رخ داده.
• فقط یک بار نمایش داده می‌شود. کوین‌لند هش را ذخیره می‌کند نه مقدار را، پس کلید گم‌شده قابل بازیابی نیست. فقط پیشوند نگه داشته می‌شود تا در کنسول کلیدها را از هم تشخیص دهید.
• چرخاندن با هم‌پوشانی. کلید تازه را بسازید، منتشر کنید، مطمئن شوید ترافیک روی آن جاری است، و بعد کلید قدیمی را باطل کنید. باطل کردن اول یعنی یک قطعی بین دو انتشار.
• یک کلید برای هر محیط. کلیدهای جدا برای استیجینگ و تولید یعنی می‌توانید یکی را باطل کنید بدون اینکه دیگری را لمس کنید، و پیشوند در لاگ‌هایتان می‌گوید کدام سیستم آن فراخوانی را انجام داده است.
• بر پایه گمان باطل کنید، نه بر پایه قطعیت. باطل کردن فوری است و ساختن جانشین چند ثانیه طول می‌کشد. هیچ حالتی وجود ندارد که انتظار برای قطعیت انتخاب بهتری باشد.

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

همه جا HTTPS

سه نشانی از شما گرفته می‌شود و هر سه باید https باشند:

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

مدیریت مبالغ

• از نوع اعشاری زبان خودتان استفاده کنید: BigDecimal، decimal.Decimal، Decimal از یک کتابخانه، یا یک عدد صحیح از کوچک‌ترین واحد آن ارز.
• amount، fee_amount و net_amount را به‌صورت رشته یا نوع اعشاری در پایگاه داده‌تان ذخیره کنید. یک ستون float یک باگ مغایرت‌گیری آهسته است.
• مبالغ سفارش را با amount و حساب‌های خودتان را با net_amount مغایرت‌گیری کنید. این دو به اندازه کارمزد کوین‌لند تفاوت دارند، و استفاده از یکی برای هر دو همان چیزی است که دفتر حساب را دچار انحراف می‌کند. پرداخت‌ها را ببینید.
• مبالغ را با مقایسه اعشاری بسنجید، هرگز با == روی عددهای پارس‌شده.

پیش از اولین پرداخت واقعی

پیش از اولین پرداخت به مشتری

فقط اگر پول به بیرون می‌فرستید. پرداخت به مشتری یک مرحله مسلح‌سازی جداگانه است و بخشی از راه‌اندازی پرداخت‌گیری شما نیست.

عادت‌های عملیاتی

فقط به وب‌هوک تکیه نکنید. وب‌هوک مسیر اصلی است، نه تنها مسیر. دو عادت ارزان، یکپارچه‌سازی را در برابر ارسالی که هرگز نمی‌رسد مقاوم می‌کند:

• صفحه return_url شما GET /sessions/{id} را استعلام می‌کند، در حالی که مشتری همان‌جا نگاه می‌کند، پس حالت رایج در یک ثانیه و مستقل از زمان‌بندی وب‌هوک حل می‌شود.
• یک بازبینی روزانه پرداخت‌های اخیر را می‌خواند و با سفارش‌های باز مغایرت‌گیری می‌کند، که هر چیزی را هم که وقتی سرور شما خواب بود پرداخت شده می‌گیرد.

به وب‌هوک سریع پاسخ دهید و کار را بعد انجام دهید. هندلری که پیش از پاسخ دادن کالا را ارسال می‌کند دیر یا زود از مهلت ارسال عبور می‌کند، و تلاش مجدد، بررسی ایدمپوتنسی شما را تنها چیزی می‌یابد که میان یک سفارش و دو سفارش ایستاده است.

کد و شناسه‌ها را ثبت کنید. در هر خطا، کد ماشینی قالب خطا، شناسه جلسه و reference_id خودتان را ثبت کنید. همین سه‌گانه برای پشتیبانی کوین‌لند کافی است تا رویداد دقیق را بدون رفت‌وبرگشت پیدا کند.

روی سکوت هشدار بگذارید. یک روز با صفر رویداد payment.completed در فروشگاهی که معمولاً پرداخت می‌گیرد، نشانه‌ای است که چیزی در سمت شما یا سمت ما شکسته است. هیچ‌کس متوجه اندپوینت وب‌هوکی که بی‌صدا از کار افتاده نمی‌شود، تا وقتی که حساب‌ها کم بیایند.

کاری که این ریل انجام نمی‌دهد

ارزش دارد پیش از طراحی بر پایه آن بدانید:

• بازگشت خودکار ندارد. پرداخت تسویه‌شده نه خودبه‌خود برمی‌گردد و نه با فرایند اعتراض. برگرداندن پول یک بازپرداخت است که خودتان تصمیم به فرستادنش می‌گیرید، و کوین‌لند کارمزدی را که روی پرداخت اصلی گرفته نگه می‌دارد.
• دریافت جزئی و بلوکه کردن اعتبار ندارد. پرداخت به‌صورت کامل تسویه می‌شود یا انجام نمی‌شود.
• تبدیل ارز ندارد. شما در هر ارزی که می‌پذیرید قیمت می‌گذارید و مشتری دقیقاً همان را می‌پردازد. هم‌خوانی بین ارزها و ریسک بازار آن، مال شماست. جلسه‌های پرداخت را ببینید.
• پرداخت دوره‌ای ندارد. در این ریل اشتراک وجود ندارد. هر پرداخت تکرارشونده یک جلسه تازه است که مشتری تأییدش می‌کند.
• فقط مشتریان کوین‌لند می‌توانند پرداخت کنند. پرداخت‌کننده به یک حساب کوین‌لند با موجودی نیاز دارد. این ریلی برای رسیدن به مشتریان کوین‌لند است، نه یک درگاه کارت عمومی.