پرش به مطلب اصلی

SDK نود

از SDK رسمی Node.js اورکاریل استفاده کنید تا با کمترین کد یکپارچه‌سازی پرداخت کریپتو بپذیرید. SDK احراز هویت، قالب‌بندی درخواست‌ها و بررسی امضای وب‌هوک را انجام می‌دهد.

نصب​

پکیج را از npm نصب کنید:

npm install @orcarail/node

پیکربندی​

یک کلاینت OrcaRail با کلید و secret API خود بسازید. به‌طور اختیاری آدرس پایه سفارشی (مثلاً برای توسعه محلی) و مهلت زمانی تعیین کنید.

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!, // e.g., "ak_live_xxx"
  process.env.ORCARAIL_API_SECRET!, // e.g., "sk_live_xxx"
  {
    baseUrl: 'https://api.orcarail.com/api/v1', // optional; default
    timeout: 30000, // optional; ms, default 30000
  }
)

برای توسعه محلی، baseUrl را به API خود اشاره دهید:

const orcarail = new OrcaRail(apiKey, apiSecret, {
  baseUrl: 'http://127.0.0.1:3000/api/v1',
  timeout: 65000, // /complete can take up to ~65s
})

live در برابر sandbox​

کلیدهای یک سازمان sandbox با ak_test_ شروع می‌شوند (شبکه‌های آزمایشی، بدون وجوه واقعی). برای آن‌ها orcarail.livemode برابر false است و await orcarail.paymentIntents.simulate(id) یک پرداخت sandbox را بدون کیف پول تکمیل می‌کند. رویدادهای وب‌هوک livemode دارند: هرگز سفارش واقعی را بر اساس رویدادهای livemode: false تحویل ندهید.

کمیسیون (تقسیم و گرفتن سهم خودتان)​

کلیدهای API می‌توانند درصد کمیسیون اختیاری (۰ تا ۱۰۰) داشته باشند. آن را در داشبورد ← کلیدهای API یا با PATCH /api/v1/api-keys/:id و commissionPercent تنظیم کنید. پرداخت‌هایی که با آن کلید ساخته می‌شوند کمیسیون را در پیش‌فاکتور (قابل مشاهده برای پرداخت‌کننده) دارند و هنگام برداشت وجوه، مبلغ کمیسیون به آدرس تنظیمات برداشت شما فرستاده می‌شود.

Payment Intentها​

ساخت Payment Intent​

یک payment intent با مبلغ، ارز، توکن، شبکه و آدرس‌های بازگشت/لغو بسازید.

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: 1, // e.g., USDC
  networkId: 1, // e.g., Ethereum
  return_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  description: 'Order #12345',
  metadata: { order_id: '12345' },
  withdrawal_address: '0x...', // optional: override where funds are withdrawn; omit to use your account default
})

console.log(intent.id) // e.g., "550e8400-e29b-41d4-a716-446655440000"
console.log(intent.client_secret)
console.log(intent.payment_link?.link)

تأیید و انتقال به پرداخت​

intent را تأیید کنید تا آدرس صفحه پرداخت میزبانی‌شده را بگیرید، سپس مشتری را منتقل کنید:

const confirmed = await orcarail.paymentIntents.confirm(intent.id, {
  client_secret: intent.client_secret!,
  return_url: 'https://yourapp.com/success',
})

// Redirect user to confirmed.pay_url or nextAction.redirectToUrl.url

دریافت Payment Intent​

وضعیت فعلی یک payment intent را بگیرید:

const intent = await orcarail.paymentIntents.retrieve(
  '550e8400-e29b-41d4-a716-446655440000'
)
console.log(intent.status)

ویرایش Payment Intent​

پیش از پرداخت مشتری، مبلغ، فراداده، آدرس‌ها یا آدرس برداشت را تغییر دهید:

const updated = await orcarail.paymentIntents.update(
  '550e8400-e29b-41d4-a716-446655440000',
  {
    amount: '150.00',
    metadata: { order_id: '12345' },
    withdrawal_address: '0x...', // optional: override withdrawal address for this payment
  }
)

لغو Payment Intent​

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

const canceled = await orcarail.paymentIntents.cancel(
  '550e8400-e29b-41d4-a716-446655440000'
)

تکمیل Payment Intent​

وقتی کاربر به آدرس موفقیت/بازگشت شما رسید، intent را در حال پردازش علامت بزنید (این کار وب‌هوک payment_intent.processing را فعال می‌کند):

const completed = await orcarail.paymentIntents.complete(
  '550e8400-e29b-41d4-a716-446655440000'
)

پرداخت با slug​

اگر از لینک‌های پرداخت با slug استفاده می‌کنید، می‌توانید جزئیات پرداخت را بگیرید و با slug لغو کنید:

// Get pay details by slug
const pay = await orcarail.pay.get('pl_abc123')

// Cancel by slug
await orcarail.pay.cancel('pl_abc123')

وب‌هوک‌ها​

امضای وب‌هوک‌ها را بررسی کنید و رویدادها را با SDK تجزیه کنید.

بررسی امضا​

از بدنه خام درخواست و هدر x-webhook-signature استفاده کنید. secret همان secret وب‌هوک شماست (از کلید API / داشبورد).

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(apiKey, apiSecret)
const signature = req.headers['x-webhook-signature']
const rawBody = req.rawBody // must be raw string or Buffer, not parsed JSON

if (!orcarail.webhooks.verifySignature(rawBody, signature, webhookSecret)) {
  return res.status(400).send('Invalid signature')
}

ساخت رویداد (بررسی و تجزیه)​

بررسی و تجزیه را در یک گام انجام دهید؛ اگر امضا نامعتبر باشد exception پرتاب می‌شود:

const event = orcarail.webhooks.constructEvent(
  rawBody,
  req.headers['x-webhook-signature'],
  webhookSecret
)

switch (event.type) {
  case 'payment_intent.completed':
    console.log('Payment succeeded:', event.data.object.id)
    break
  case 'payment_intent.processing':
    console.log('Payment processing:', event.data.object.id)
    break
  case 'payment_intent.canceled':
    console.log('Payment canceled:', event.data.object.id)
    break
  case 'payment_intent.requires_payment_method':
    console.log('Payment needs method:', event.data.object.id)
    break
  default:
    console.log('Unhandled event:', event.type)
}

نمونه Express​

const express = require('express')
const OrcaRail = require('@orcarail/node').default

const app = express()
const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY,
  process.env.ORCARAIL_API_SECRET
)

// Use raw body for signature verification
app.post(
  '/webhooks/orcarail',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature']
    const rawBody = req.body // Buffer

    try {
      const event = orcarail.webhooks.constructEvent(
        rawBody,
        signature,
        process.env.ORCARAIL_WEBHOOK_SECRET
      )
      console.log('Event:', event.type, event.data.object.id)
      res.status(200).json({ received: true })
    } catch (err) {
      res.status(400).send('Invalid signature')
    }
  }
)

نمونه Next.js (App Router)​

در یک Route Handler، بدنه خام را بخوانید و بررسی کنید:

import { NextRequest, NextResponse } from 'next/server'
import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!,
  process.env.ORCARAIL_API_SECRET!
)

export async function POST(request: NextRequest) {
  const rawBody = await request.text()
  const signature = request.headers.get('x-webhook-signature') ?? ''

  try {
    const event = orcarail.webhooks.constructEvent(
      rawBody,
      signature,
      process.env.ORCARAIL_WEBHOOK_SECRET!
    )
    // Handle event.type and event.data.object
    return NextResponse.json({ received: true })
  } catch {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }
}

مدیریت خطا​

SDK خطاهای نوع‌دار پرتاب می‌کند که می‌توانید مدیریتشان کنید:

import OrcaRail, {
  OrcaRailError,
  OrcaRailAPIError,
  OrcaRailAuthenticationError,
  OrcaRailSignatureVerificationError,
} from '@orcarail/node';

try {
  const intent = await orcarail.paymentIntents.create({ ... });
} catch (err) {
  if (err instanceof OrcaRailAuthenticationError) {
    console.error('Invalid API key or secret');
  } else if (err instanceof OrcaRailAPIError) {
    console.error('API error:', err.statusCode, err.message);
  } else if (err instanceof OrcaRailSignatureVerificationError) {
    console.error('Webhook signature invalid');
  } else if (err instanceof OrcaRailError) {
    console.error('OrcaRail error:', err.message);
  }
}

اپ دمو​

برای نمونه کامل یکپارچه‌سازی (ساخت intent، انتقال به پرداخت، صفحه موفقیت، تکمیل، وب‌هوک‌ها) دموی متن‌باز را ببینید:

  • مخزن: https://github.com/OrcaRail/demo
  • پشته: Next.js، SDK نود اورکاریل، صفحه پرداخت میزبانی‌شده، اندپوینت وب‌هوک

همچنین ببینید​