رفتن به محتوا
ورود / ثبت‌نام

توسعه‌دهندگان

API PAYNYX بر پایه قرارداد OpenAPI 3.1 است. همه مبالغ عدد صحیح به ریال هستند و نام فیلدها با Rial تمام می‌شود.

قرارداد OpenAPI (JSON)

شروع سریع

مقادیر داخل <…> جای‌گذار هستند.

  1. در داشبورد یک کلید API بسازید و آن را در متغیر محیطی سرور خود نگه دارید.
  2. از سمت سرور، فاکتور بسازید. هدر Idempotency-Key را برای هر سفارش یکتا بفرستید.
  3. خریدار را به checkoutUrl بفرستید یا کارت و مبلغ دقیق (payableAmountRial) را خودتان نمایش دهید.
  4. رویداد invoice.paid را از وب‌هوک دریافت و امضای PAYNYX-Signature را بررسی کنید.
POST <PAYNYX_API_BASE>/v1/merchants/<MERCHANT_ID>/invoicesAuthorization: Bearer $PAYNYX_API_KEYIdempotency-Key: <UNIQUE_ORDER_KEY>Content-Type: application/json{  "baseAmountRial": 1500000,  "orderRef": "<ORDER_ID>",  "returnUrl": "https://<YOUR_SHOP>/thanks"}

مقادیر داخل <…> جای‌گذار هستند.

قرارداد و اصول

  • همه مبالغ عدد صحیح به ریال هستند (payableAmountRial).
  • برای هر سفارش یک Idempotency-Key یکتا بفرستید تا فاکتور تکراری ساخته نشود.
  • صفحه موفقیت مرورگر یا ربات به‌تنهایی سفارش را نهایی نمی‌کند؛ وب‌هوک امضاشده یا خواندن وضعیت از سرور را مبنا قرار دهید.
  • حالت مستقیم: کارت مقصد، مبلغ دقیق، مهلت و شناسه فاکتور را از پاسخ API نمایش دهید.
  • اتصال وب‌هوک را از داشبورد با «آزمایش اتصال» امتحان کنید: یک رویداد امضاشدهٔ webhook.test می‌رسد و هیچ فاکتوری پشت آن نیست. پس از بررسی امضا به آن پاسخ ۲xx بدهید و آن را رویداد کسب‌وکار حساب نکنید.

وب‌هوک

امضای وب‌هوک: HMAC-SHA256 روی «timestamp.rawBody» با رمز امضای endpoint، در هدر PAYNYX-Signature به شکل t=…,v1=….

// Node.js, server side. <WEBHOOK_SECRET> is a placeholder.import { createHmac, timingSafeEqual } from 'node:crypto';function verify(rawBody, header, secret = process.env.PAYNYX_WEBHOOK_SECRET) {  // During secret rotation the header carries several v1 signatures.  const pairs = header.split(',').map((p) => p.trim().split('='));  const t = pairs.find(([k]) => k === 't')?.[1];  const signatures = pairs.filter(([k]) => k === 'v1').map(([, v]) => v);  if (!t || signatures.length === 0) return false;  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;  const expected = Buffer.from(    createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'),  );  return signatures.some(    (v) => v.length === expected.length && timingSafeEqual(expected, Buffer.from(v)),  );}

مقادیر داخل <…> جای‌گذار هستند.

دو روش پرداخت

  • صفحه پرداخت میزبانی‌شده

    میزبانی‌شده: خریدار را به صفحه پرداخت PAYNYX می‌فرستید که کارت، مبلغ دقیق، شمارش معکوس و وضعیت زنده را نشان می‌دهد.

  • پرداخت مستقیم کارت‌به‌کارت

    مستقیم: سایت یا ربات شما شماره کارت و مبلغ دقیق را از API می‌گیرد و خودش نمایش می‌دهد.