خطاها

هر پاسخ غیر ۲xx از کوین‌لند پی همین شکل را دارد:

{
  "statusCode": 422,
  "errors": {
    "error": ["PAY_CURRENCY_NOT_ACCEPTED"]
  }
}

errors.error آرایه‌ای از کدهای ماشینیِ پایدار با قالب UPPER_SNAKE است. هیچ پیام خوانا، در هیچ زبانی، در هیچ جای پاسخ وجود ندارد — و این عامدانه است: مشتریان شما متن شما را می‌خوانند، نه متن ما. کد را به جمله‌ای که خودتان نوشته‌اید نگاشت کنید، به زبانی که مشتری شما صحبت می‌کند.

کدها فقط افزوده می‌شوند. کدی که منتشر شود هرگز معنایش تغییر نمی‌کند و هرگز تغییر نام نمی‌دهد، چون ترجمه‌ها و هشدارهای شما بر پایه آن‌ها ساخته شده‌اند. کدهای تازه می‌توانند ظاهر شوند، پس برای کدهایی که مدیریت می‌کنید شاخه بگذارید و بقیه را به یک پیام عمومی بسپارید.

خواندن قالب خطا

const res = await fetch(url, init);
if (!res.ok) {
  const body = await res.json().catch(() => null);
  const code = body?.errors?.error?.[0] ?? "UNKNOWN";
  throw new CoinlandPayError(code, res.status);
}

دو نکته که ارزش دارد بر پایه‌شان بسازید:

• آرایه می‌تواند بیش از یک کد داشته باشد. خطاهای اعتبارسنجی ممکن است چند کد را یک‌جا گزارش کنند. اولی را برای شاخه‌بندی بگیرید و همه را ثبت کنید.
• تنها بر پایه کد وضعیت شاخه نگذارید. چند کد یک وضعیت مشترک دارند؛ کد قرارداد است و وضعیت جزئیات انتقال.

کدهای کوین‌لند پی

جلسه‌های پرداخت و پرداخت‌ها

ارسال دوباره و عیناً یکسانِ POST /sessions خطا نیست: همان reference_id با همان محتوا، جلسه اصلی را با وضعیت موفق برمی‌گرداند. تنها محتوای تغییریافته PAY_DUPLICATE_REFERENCE را ایجاد می‌کند. جلسه‌های پرداخت را ببینید.

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

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

کدهای INSUFFICIENT_BALANCE (۴۲۲) و PAY_RATE_UNAVAILABLE (۵۰۳) هم روی این سطح دیده می‌شوند: اولی وقتی کیف‌پول کسب‌وکارتان amount + fee را پوشش نمی‌دهد، و دومی وقتی ارز نرخ زنده دلاری ندارد و در نتیجه سقف‌ها قابل اعمال نیستند. پرداخت رد می‌شود، نه اینکه بدون سنجش برود.

اتصال هویت مشتری

این‌ها از اتصال هویت پرداخت‌کننده می‌آیند: شیء الزامی customer روی هر جلسه، و پیوند دائمی میان customer.id شما و حساب کوین‌لند پرداخت‌کننده.

مرحله تأیید پرداخت ممکن است TOTP_REQUIRED، TOTP_NOT_ENROLLED یا TOTP_INVALID هم پاسخ بدهد — همان گام دوعاملی که هر پرداختی دارد، هم‌سطح امنیتی یک برداشت. این‌ها داخل ویجت به پرداخت‌کننده نشان داده می‌شوند و هرگز به یکپارچه‌سازی شما نمی‌رسند.

حساب کسب‌وکار شما

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

کدهای عمومی

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

کدام خطاها را دوباره تلاش کنیم

نگاشت کدها به متن خودتان

نگاشت را در یک جا و بر پایه کد نگه دارید، با یک حالت پیش‌فرض:

const MESSAGES = {
  PAY_SESSION_EXPIRED: "این پرداخت منقضی شده است. برای گرفتن یک پرداخت تازه دوباره شروع کنید.",
  PAY_CURRENCY_NOT_ACCEPTED: "در حال حاضر نمی‌توانیم این ارز را بپذیریم.",
  PAY_AMOUNT_INVALID: "مبلغ سفارش مشکلی دارد.",
  MERCHANT_DISABLED: "پرداخت با کوین‌لند در حال حاضر در دسترس نیست.",
  RATE_LIMITED: "تلاش‌های بیش از حد. یک دقیقه دیگر امتحان کنید.",
};

// کدی که هرگز ندیده‌اید هم باید یک جمله تولید کند، چون کدهای تازه بدون تغییر
// نسخه منتشر می‌شوند.
export const messageFor = (code) => MESSAGES[code] ?? "پرداخت انجام نشد.";

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