شروع سریع
این صفحه برای کسانی است که میخواهند در کوتاهترین زمان ممکن اولین تراکنش را بزنند. در پایان این پنج دقیقه، یک بکاند ساده دارید که URL پرداخت را تولید و تراکنش را Verify میکند. برای پیادهسازی کامل (دیتابیس، Route ها و …) به نمونه کد بکاند بروید.
مرحله ۱ — دریافت کلید درگاه
- در باسلام ثبتنام کنید.
- احراز هویت توسعهدهنده را در پنل تکمیل کنید.
- از بخش هسته مالی، درگاه پرداخت اینترنتی کلید امنیتی درگاه خود را دریافت کنید. (
X-Gateway-Secret)
مرحله ۲ — دریافت APIها
با استفاده از API های درگاه اپاستور میتوانید پروسه ساخت لینک پرداخت، هدایت کاربر به صفحه روشهای پرداخت و تایید یک تراکنش (Verify) را پیادهسازی کنید.
نمونه کد
Node.js
npm install axios uuid dotenvمرحله ۳ — تنظیم متغیرهای محیطی
# .env
PAYMENT_GATEWAY_API=https://openapi.basalam.com/v1/pay
PAYMENT_GATEWAY_SECRET=your_secret_key_here
PAYMENT_CALLBACK_URL=https://your-ngrok-url.ngrok.io/payment/callbackدرگاه پرداخت فقط با HTTPS کار میکند. برای تست در محیط local از ngrok http 3000 استفاده کنید و URL تولیدشده را در PAYMENT_CALLBACK_URL قرار دهید.
مرحله ۴ — اولین درخواست پرداخت
Node.js
import axios from 'axios'
async function initiatePayment(userId: number, amountRial: number) {
const referenceId = `PAY-${userId}-${Date.now()}`
const { data } = await axios.post(
`${process.env.PAYMENT_GATEWAY_API}/pay/transactions`,
{
reference_id: referenceId,
amount: amountRial,
description: 'خرید اشتراک',
callback_url: process.env.PAYMENT_CALLBACK_URL,
},
{
headers: { 'X-Gateway-Secret': process.env.PAYMENT_GATEWAY_SECRET },
}
)
return { url: data.pay_url, referenceId, hashId: data.hash_id }
}
const result = await initiatePayment(123, 500_000)
console.log('Redirect user to:', result.url)مبلغ به ریال ارسال میشود؛ نه تومان. ۵۰٬۰۰۰ تومان = ۵۰۰٬۰۰۰ ریال.
مرحله ۵ — Verify بعد از Callback
پس از پرداخت، باسلام کاربر را به callback_url شما برمیگرداند با پارامترهای hash_id، reference_id و status. حتماً تراکنش را Verify کنید — تا قبل از Verify، پرداخت در سیستم باسلام نهایی نیست.
Node.js
import express from 'express'
import axios from 'axios'
const app = express()
app.get('/payment/callback', async (req, res) => {
const { hash_id, status } = req.query
if (status !== 'success') {
return res.redirect('/payment/failed')
}
try {
await axios.post(
`${process.env.PAYMENT_GATEWAY_API}/pay/transactions/${hash_id}/verify`,
{},
{ headers: { 'X-Gateway-Secret': process.env.PAYMENT_GATEWAY_SECRET } }
)
res.redirect('/payment/success')
} catch {
res.redirect('/payment/failed')
}
})
app.listen(3000)قدم بعدی
این مثال برای امتحان کردن سریع کافی است، اما برای پروداکشن باید موارد زیر را اضافه کنید:
- استعلام (
inquiry) برای تراکنشهای معلق و reconciliation job - صفحات Checkout و Callback در فرانت (نمونه کد فرانتاند)
برای دیدن کد کامل با مدیریت دیتابیس و خطا، به نمونه کد بکاند بروید.