مرجع API پرداخت‌ها

مرجع کامل اندپوینت‌های API پرداخت‌ها (لینک‌های پرداخت، تراکنش‌ها، شبکه‌ها و توکن‌ها).

آدرس پایه

https://api.orcarail.com/api/v1

لینک‌های پرداخت

ساخت لینک پرداخت

یک لینک پرداخت جدید بسازید.

POST /payments/links

احراز هویت

• توکن Bearer (JWT) — الزامی

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
title	string	بله	عنوان لینک پرداخت
amount	string	بله	مبلغ (مثلاً "0.1")
tokenId	string	بله	شناسه توکن (UUID)
networkId	string	بله	شناسه شبکه (UUID)
expiresAt	string	خیر	زمان انقضا به قالب ISO 8601
metadata	object	خیر	فراداده سفارشی

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

فهرست لینک‌های پرداخت کاربر

همه لینک‌های پرداخت کاربر احراز هویت‌شده را فهرست کنید.

GET /payments/links

احراز هویت

• توکن Bearer (JWT) — الزامی

پاسخ

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Payment for services",
    "slug": "pl_abc123",
    "amount": "0.1",
    "tokenId": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

دریافت لینک پرداخت با slug

یک لینک پرداخت را با slug آن بگیرید (عمومی، بدون احراز هویت).

GET /payments/links/:slug

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
slug	string	بله	slug لینک پرداخت (مثلاً pl_abc123)

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

ویرایش لینک پرداخت

یک لینک پرداخت موجود را ویرایش کنید.

PATCH /payments/links/:id

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه لینک پرداخت (UUID)

بدنه درخواست

همه فیلدها اختیاری‌اند.

پارامتر	نوع	الزامی	توضیح
title	string	خیر	عنوان جدید
amount	string	خیر	مبلغ جدید
tokenId	string	خیر	شناسه توکن جدید (UUID)
networkId	string	خیر	شناسه شبکه جدید (UUID)
status	string	خیر	وضعیت: active، inactive و غیره
expiresAt	string	خیر	زمان انقضای جدید (ISO 8601)
metadata	object	خیر	فراداده جدید

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Updated title",
  "slug": "pl_abc123",
  "amount": "0.2",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

حذف لینک پرداخت

یک لینک پرداخت را حذف کنید.

DELETE /payments/links/:id

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه لینک پرداخت (UUID)

پاسخ

204 No Content

پیش‌فاکتور

دریافت پیش‌فاکتور

برای یک لینک پرداخت، با توکن/شبکه پرداخت‌کننده و کارمزد پشتیبانی اختیاری، پیش‌فاکتور بگیرید. برای تعرفه پلتفرم میزبانی‌شده (هر تراکنش و سطح رایگان) نمای کلی کارمزدها و محدودیت‌ها را ببینید. برای نحوه اعمال و برگرداندن اقلام پیش‌فاکتور (پشتیبانی، کمیسیون، پل) و حداقل‌ها، کارمزدها و محدودیت‌ها را ببینید.

POST /payments/links/:slug/quote

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
slug	string	بله	slug لینک پرداخت

بدنه درخواست

همه فیلدها اختیاری‌اند.

پارامتر	نوع	الزامی	توضیح
payerTokenId	string	خیر	شناسه توکن (UUID) که پرداخت‌کننده می‌خواهد با آن بپردازد
payerNetworkId	string	خیر	شناسه شبکه (UUID) که پرداخت‌کننده می‌خواهد روی آن بپردازد
supportPercent	number	خیر	درصد کارمزد پشتیبانی (مثلاً 0.1 برای ۰٫۱٪)

پاسخ

{
  "originalAmount": "100.00",
  "supportPercent": "0.1",
  "supportAmount": "0.1",
  "originalTokenSymbol": "USDC",
  "payerTokenSymbol": "USDT",
  "bridgeFee": "0.001",
  "bridgeFeeUsd": "0.25",
  "bridgeFeeInPayerToken": "0.0001",
  "originalAmountInPayerToken": "1.0",
  "totalAmount": "100.0001",
  "requiresBridge": true,
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerNetworkName": "Ethereum",
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  },
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDT",
    "name": "Tether USD",
    "contractAddress": "0x...",
    "decimals": 6,
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
}

payerNetwork و payerToken اشیای کامل‌اند (برای توضیح فیلدها فهرست شبکه‌ها و فهرست توکن‌ها بر اساس شبکه را ببینید).

تراکنش‌ها

ساخت تراکنش

برای یک لینک پرداخت تراکنش جدید بسازید.

POST /payments/links/:slug/transactions

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
slug	string	بله	slug لینک پرداخت

بدنه درخواست

همه فیلدها اختیاری‌اند.

پارامتر	نوع	الزامی	توضیح
payerTokenId	string	خیر	شناسه توکن (UUID) که پرداخت‌کننده می‌خواهد با آن بپردازد
payerNetworkId	string	خیر	شناسه شبکه (UUID) که پرداخت‌کننده می‌خواهد روی آن بپردازد
supportPercent	number	خیر	درصد کارمزد پشتیبانی (مثلاً 0.1)

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

دریافت تراکنش با شناسه

یک تراکنش را با شناسه‌اش بگیرید.

GET /payments/transactions/:id

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه تراکنش (UUID)

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T01:00:00.000Z"
}

فهرست تراکنش‌های کاربر

همه تراکنش‌های کاربر احراز هویت‌شده را فهرست کنید.

GET /payments/transactions

احراز هویت

• توکن Bearer (JWT) — الزامی

پاسخ

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "0.1",
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

دریافت تراکنش با اطلاعات کامل پرداخت‌کننده

یک تراکنش را با جزئیات کامل شبکه و توکن پرداخت‌کننده بگیرید.

GET /payments/transactions/:id/full

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه تراکنش (UUID)

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "symbol": "USDC",
    "decimals": 6,
    "contractAddress": "0x..."
  },
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "publicRpcUrls": ["https://eth.llamarpc.com"]
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

ویرایش پرداخت‌کننده تراکنش

توکن و شبکه پرداخت‌کننده یک تراکنش را ویرایش کنید.

PATCH /payments/transactions/:id/payer

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه تراکنش (UUID)

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
payerTokenId	string	بله	شناسه توکن (UUID) که پرداخت‌کننده می‌خواهد با آن بپردازد
payerNetworkId	string	بله	شناسه شبکه (UUID) که پرداخت‌کننده می‌خواهد روی آن بپردازد

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440004",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440005",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

ویرایش پشتیبانی تراکنش

درصد کارمزد پشتیبانی یک تراکنش را ویرایش کنید.

PATCH /payments/transactions/:id/support

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه تراکنش (UUID)

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
supportPercent	number	بله	درصد کارمزد پشتیبانی (مثلاً 0.1 برای ۰٫۱٪)

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "supportPercent": 0.2,
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

شبکه‌ها و توکن‌ها

فهرست شبکه‌ها

همه شبکه‌های پشتیبانی‌شده را فهرست کنید.

GET /payments/networks

پارامترهای کوئری

پارامتر	نوع	الزامی	توضیح
active	string	خیر	برای برگرداندن فقط شبکه‌های فعال true بگذارید
testnet	string	خیر	true = فقط شبکه‌های آزمایشی (sandbox)، false = فقط شبکه‌های اصلی (live). برای همه حذفش کنید

پاسخ

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

فهرست توکن‌ها بر اساس شبکه

توکن‌های موجود برای یک شبکه مشخص را فهرست کنید.

GET /payments/networks/:id/tokens

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	string	بله	شناسه شبکه (UUID)

پاسخ

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "contractAddress": "0x...",
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

کدهای وضعیت

کد وضعیت	توضیح
200	موفق
201	ساخته شد
204	بدون محتوا
400	درخواست نامعتبر
401	احراز هویت نشده
404	یافت نشد
500	خطای داخلی سرور

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

• Payment Intentها — API مربوط به Payment Intentها
• پرداخت — پرداخت با slug
• احراز هویت — روش‌های احراز هویت