پرداخت دستیار برای توسعه‌دهنده‌ها

اتصال

دو راه دارد. یا صاحب حساب در اپ پی‌فار کلید می‌سازد (دستیارها ← دستیار شما ← کلیدها) و میزبان آن را به‌عنوان توکن bearer می‌فرستد، یا میزبان خودش را ثبت می‌کند و جریان authorization code با PKCE را اجرا می‌کند.

ثبت پویای کلاینت (RFC 7591) باز است. متادیتای منبع محافظت‌شده (RFC 9728) از میزبان MCP و متادیتای سرور مجوز (RFC 8414) از API سرو می‌شود. شناسهٔ منبع (RFC 8707) الزامی است: توکن به همین سرور مقید است و جای دیگری پذیرفته نمی‌شود.

• Streamable HTTP: https://mcp-dev.payfar.org/mcp
• stdio: دستور npx @payfar/mcp با متغیر PAYFAR_AGENT_KEY
• دامنه‌ها: payments:read، payments:create، credentials:read، threeds:read، services:read، topup:request

چرخهٔ پرداخت

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

ابزار create_payment یکی از سه پاسخ را می‌دهد: تأییدشده، نگه‌داشته‌شده یا ردشده. نگه داشته شدن شکست نیست؛ یعنی منتظر صاحب حساب است و wait_for_payment تا پاسخ او منتظر می‌ماند. تنها پس از تأیید، get_payment_credentials کارت را در پنجره‌ای محدود و با تعداد دفعات محدود آزاد می‌کند.

وقتی تراکنش انجام شد، گزارشش کنید. report_payment_outcome است که پرداخت را می‌بندد و اجازه می‌دهد تسویه آن را با تراکنش واقعی جفت کند؛ دستیاری که این کار را نکند بودجهٔ صاحب حساب را رزرو نگه می‌دارد.

خطاها دستورالعمل‌اند

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

• intent.pending_approval؛ صاحب حساب هنوز پاسخ نداده؛ منتظر بمانید، دوباره نفرستید.
• policy.declined؛ یک قانون رد کرده؛ شناسهٔ قانون می‌گوید کدام. همان پرداخت را تکرار نکنید.
• intent.window_closed و intent.reveals_exhausted؛ پنجرهٔ اطلاعات کارت بسته شده. پرداخت تازه شروع کنید.
• pin.required؛ یک انسان باید در اپ تأیید کند. کاری از دستیار برنمی‌آید.
• card.unlock_failed؛ موقتی است؛ یک دقیقه بعد دوباره تلاش کنید.

مهارت (Skill)

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

همراه سرور عرضه می‌شود: دستور npx @payfar/mcp skill install، یا خواندن آن به‌عنوان منبع payfar://skill.

کاری که این سرور نمی‌کند

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

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