اتصال درگاه پرداخت به سایت و اپلیکیشن در ۱۰ دقیقه
اتصال درگاه پرداخت سایت یا اپلیکیشن شما را به سرویسی وصل می‌کند که پرداخت را می‌گیرد و وقتی تمام شد به بک‌اند شما خبر می‌دهد. ساده‌ترین روش، صفحه پرداخت آماده (hosted checkout) است: سرور شما یک پرداخت می‌سازد، مشتری در صفحه درگاه پرداخت می‌کند و یک وب‌هوک امضاشده سفارش را پرداخت‌شده علامت می‌زند.
این راهنما همین روند را با API و SDKهای OrcaRail، برای اپلیکیشن وب و موبایل، در محیط آزمایشی بدون پول واقعی نشان می‌دهد. مشتری با ارز دیجیتال پرداخت می‌کند و شما استیبل‌کوین دلخواه، مثل USDC یا تتر (USDT)، را دریافت می‌کنید.
اتصال با صفحه پرداخت آماده چطور کار می‌کند
| مرحله | چه کسی | چه اتفاقی می‌افتد |
|---|---|---|
| ۱. ساخت | بک‌اند شما | یک payment intent با مبلغ، توکن و شبکه دریافتی و آدرس‌های بازگشت/لغو می‌سازد |
| ۲. انتقال | اپلیکیشن شما | مشتری را به صفحه پرداخت آماده می‌فرستد |
| ۳. پرداخت | مشتری | در pay.orcarail.com با کیف پول خود پرداخت می‌کند |
| ۴. بازگشت | بک‌اند شما | وقتی مشتری به آدرس بازگشت رسید، intent را تکمیل می‌کند |
| ۵. وب‌هوک | OrcaRail ← بک‌اند شما | رویداد امضاشده payment_intent.completed را می‌فرستد؛ شما سفارش را تحویل می‌دهید |
سرورهای شما هرگز با کیف پول، کلید خصوصی یا پایش بلاکچین سروکار ندارند. بازگشت مرورگر به‌تنهایی هیچ‌وقت سفارش را پرداخت‌شده نمی‌کند: بک‌اند شما با API بررسی می‌کند و فقط به وب‌هوک امضاشده اعتماد دارد.
پیش از شروع
- در app.orcarail.com ثبت‌نام کنید و راه‌اندازی راهنما را تمام کنید.
- روی Go to sandbox بزنید و یک کلید API (
ak_test_…) بسازید. کلید، secret و secret امضای وب‌هوک را کپی کنید. secret فقط یک بار نمایش داده می‌شود. ساخت sandbox را ببینید. - آدرس وب‌هوک کلید را تنظیم کنید، مثلاً
https://yourapp.com/webhooks/orcarail. - توکن و شبکه دریافتی را انتخاب کنید. شناسه‌ها از
GET /payments/networksوGET /payments/networks/:id/tokensمی‌آیند. شبکه‌ها و توکن‌ها را ببینید.
اتصال با SDK نود جی‌اس
SDK نود جی‌اس را نصب کنید:
npm install @orcarail/node
۱. پرداخت را بسازید و مشتری را منتقل کنید
import OrcaRail from '@orcarail/node'
const orcarail = new OrcaRail(
process.env.ORCARAIL_API_KEY!, // ak_test_… in the sandbox
process.env.ORCARAIL_API_SECRET!
)
const intent = await orcarail.paymentIntents.create({
amount: '100.00',
currency: 'usd',
payment_method_types: ['crypto'],
tokenId: '<token-id>', // e.g. USDC
networkId: '<network-id>', // e.g. Base
return_url: 'https://yourapp.com/success',
cancel_url: 'https://yourapp.com/cancel',
description: 'Order #12345',
metadata: { order_id: '12345' },
})
const confirmed = await orcarail.paymentIntents.confirm(intent.id, {
client_secret: intent.client_secret!,
return_url: 'https://yourapp.com/success',
})
// Redirect the customer to confirmed.pay_url
۲. پرداخت را هنگام بازگشت تکمیل کنید
وقتی مشتری به آدرس بازگشت رسید، intent را از بک‌اند تکمیل کنید. این کار پرداخت را نهایی و قابل برداشت می‌کند. اگر هنوز روی بلاکچین تأیید نشده باشد، intent در وضعیت processing می‌ماند؛ بعداً دوباره complete را صدا بزنید.
const completed = await orcarail.paymentIntents.complete(intent.id)
۳. وب‌هوک را تأیید کنید
از بدنه خام درخواست و هدر x-webhook-signature استفاده کنید:
app.post(
'/webhooks/orcarail',
express.raw({ type: 'application/json' }),
(req, res) => {
try {
const event = orcarail.webhooks.constructEvent(
req.body,
req.headers['x-webhook-signature'],
process.env.ORCARAIL_WEBHOOK_SECRET
)
if (event.type === 'payment_intent.completed') {
// mark the order paid (idempotently)
}
res.status(200).json({ received: true })
} catch (err) {
res.status(400).send('Invalid signature')
}
}
)
رویدادها فیلد livemode دارند. هرگز سفارش واقعی را از رویداد با livemode: false تحویل ندهید. امضای وب‌هوک و رویدادهای وب‌هوک را ببینید.
اتصال با پی‌اچ‌پی یا لاراول
همین روند با SDK پی‌اچ‌پی کار می‌کند، و پکیج Laravel Cashier اشتراک ارز دیجیتال را به اپلیکیشن‌های لاراول اضافه می‌کند. SDK ندارید؟ مستقیم REST API را صدا بزنید: مرجع API را ببینید.
درگاه پرداخت برای اپلیکیشن موبایل
اپلیکیشن موبایل هرگز نباید secret API شما را نگه دارد. اتصال را در بک‌اند نگه دارید:
- اپلیکیشن از بک‌اند می‌خواهد پرداخت را بسازد.
- بک‌اند intent را می‌سازد و تأیید می‌کند و
pay_urlرا برمی‌گرداند. - اپلیکیشن
pay_urlرا در مرورگر داخلی یا مرورگر سیستم باز می‌کند. - مشتری به
return_urlشما برمی‌گردد و بک‌اند intent را تکمیل می‌کند. - بک‌اند وب‌هوک را دریافت می‌کند و اپلیکیشن را به‌روز می‌کند، مثلاً با نوتیفیکیشن یا در بارگذاری بعدی.
آزمایش اتصال در محیط آزمایشی
- کلیدهای sandbox (
ak_test_) فقط از تست‌نت استفاده می‌کنند.orcarail.livemodeبرابرfalseاست. - با
await orcarail.paymentIntents.simulate(id)یا دکمه Simulate payment در صفحه پرداخت sandbox، پرداخت را بدون کیف پول تمام کنید. شبیه‌سازی پرداخت را ببینید. - وقتی همه چیز درست کار کرد، در سازمان live کلید live بسازید و توکن و شبکه را به مین‌نت تغییر دهید. ورود به حالت واقعی را ببینید.
اتصال را به یک دستیار هوش مصنوعی بسپارید
سرور MCP OrcaRail به Claude Code، Cursor یا Codex اجازه می‌دهد برای شما payment intent، محصول و اشتراک بسازند، و مستندات به صورت متن ساده برای LLMها در دسترس است. ساخت با هوش مصنوعی را ببینید.
پرسش‌های متداول
اتصال درگاه پرداخت چقدر طول می‌کشد؟
با صفحه پرداخت آماده و SDK، یک اتصال ساده سه فراخوانی در بک‌اند و یک مسیر وب‌هوک است. بیشتر زمان صرف آزمایش در sandbox می‌شود.
به صفحه پرداخت اختصاصی نیاز دارم؟
نه. مشتری در صفحه پرداخت آماده پرداخت می‌کند. اگر اصلاً کد نمی‌خواهید، یک ویجت قیمت قرار دهید؛ درگاه پرداخت برای سایت را ببینید.
از کجا بدانم پرداخت واقعاً انجام شده؟
فقط به وب‌هوک امضاشده اعتماد کنید، یا intent را از بک‌اند با API بررسی کنید. هرگز فقط به بازگشت مرورگر اعتماد نکنید.
هزینه چقدر است؟
نسخه میزبانی‌شده OrcaRail بعد از ۱۰۰ تراکنش رایگان اول، ۰٫۵٪ از هر تراکنش تکمیل‌شده می‌گیرد. کارمزد شبکه جداست. تعرفه را ببینید.
می‌توانم پرداخت دوره‌ای بگیرم؟
بله، با API اشتراک. پرداخت دوره‌ای ارز دیجیتال و اشتراک‌های OrcaRail را ببینید.