مرجع API

همهٔ مسیرهای API عمومی با پارامترها، نمونهٔ درخواست و پاسخ، که زنده از سند OpenAPI خوانده می‌شود.

API عمومی در https://a.bezanbecard.com/v1 است. با JSON روی HTTPS کار می‌کند، مبلغ را عدد صحیح به ریال و زمان را ثانیهٔ یونیکس می‌گیرد و به سبک Stripe پاسخ می‌دهد: فیلدهای snake_case، شیء فهرست با نشانگر و خطاهای نوع‌دار.

قراردادها

قراردادها
موضوع	قرارداد
احراز هویت	`Authorization: Bearer sk_test_…`، یا HTTP Basic با کلید به‌عنوان نام کاربری. حالت از روی کلید معلوم می‌شود. کلیدها را ببینید.
بدنهٔ درخواست	JSON با `Content-Type: application/json`. پارامتر ناشناخته رد می‌شود (`parameter_unknown`). `POST /v1/payments/:id/receipts` بدنهٔ `multipart/form-data` را هم با فایل‌ها در `files` می‌گیرد.
تلاش دوباره	با هر `POST` یک `Idempotency-Key` بفرستید. درخواست تکرارپذیر را ببینید.
نسخه	`Bezanbecard-Version: 2026-10-01`؛ بدون آن، نسخهٔ کلید.
فهرست‌ها	`limit`، `starting_after`، `ending_before`، `created`. صفحه‌بندی را ببینید.
خطاها	`{ "error": { "type", "code", "message", "param", "doc_url", "request_id" } }`. خطاها را ببینید.
شناسهٔ درخواست	هر پاسخ هدر `Request-Id` دارد؛ لاگ درخواست‌ها در داشبورد هر فراخوانی را ۳۰ روز نگه می‌دارد.
سقف درخواست	۱۰۰ درخواست در ثانیه برای هر کلید واقعی و ۲۵ برای هر کلید آزمایشی.

رسیدها

receipt (rcp_…) سند مشتری برای یک پرداخت است. GET /v1/receipts آن‌ها را فهرست می‌کند (status=pending همان صف بررسی شماست)، GET /v1/receipts/:id یکی را می‌خواند، POST /v1/payments/:id/receipts یکی می‌فرستد و POST /v1/receipts/:id/approve و /reject درباره‌اش تصمیم می‌گیرند. پرداخت با expand[]=receipts رسیدهایش را هم همراه دارد. فایل‌ها با شناسه، اندازه و SHA-256 می‌آیند و API هیچ‌وقت خودشان را برنمی‌گرداند. تأییدی که پیش از پیامک بانک انجام شود روی واریزی با منبع receipt می‌ایستد؛ وقتی پیامکِ همان انتقال جایش را بگیرد، واریز پیامکی آن را در replaces نام می‌برد (وگرنه null)، پس آن انتقال یک بار ثبت می‌شود. رسیدها و بررسی را ببینید.

فیلدهای انتقال بانکی

پرداخت در payment_method_types می‌گوید چطور می‌شود پرداختش کرد (card، transfer). destination آن type (card یا account) و iban_last4 دارد و با کلید مخفی iban کامل را هم کنار pan؛ برای حساب، pan و last4 برابر null هستند. شیء card هم type و iban_last4 دارد، deposit فیلد channel را (card، pol، paya، satna، internal) و capabilities.bank_transfer حساب می‌گوید تنظیمات شما انتقال بانکی را می‌پذیرد یا نه. انتقال بانکی را ببینید.

سند OpenAPI

GET https://a.bezanbecard.com/v1/openapi.json توصیف OpenAPI 3.1 همین API است؛ عمومی است و پنج دقیقه کش می‌شود. این سند از همان قاعده‌هایی ساخته می‌شود که API با آن‌ها اعتبارسنجی می‌کند، پس از آن عقب نمی‌ماند. آن را در کلاینت API خود وارد کنید یا برای زبانی که کتابخانهٔ رسمی ندارد کلاینت بسازید. عملیات‌های پایین از روی همین سند نمایش داده می‌شوند.

عملیات‌ها

نشانی پایه: https://a.bezanbecard.com
نسخهٔ API: 2026-10-01
عملیات‌ها: ۴۴ عملیات

متن مرجع API از خود API خوانده می‌شود و انگلیسی است.

پاسخ‌های خطا

400invalid_request_error (a missing, unknown or invalid parameter) or idempotency_error (a reused Idempotency-Key).
401authentication_error: missing, invalid, revoked or expired key.
403permission_error: a restricted key without the permission, a publishable key, a live key on a test-only route, a suspended account.
404invalid_request_error resource_missing.
409invalid_request_error (a state conflict such as payment_already_changed) or idempotency_error idempotency_key_in_use.
429rate_limit_error: 100 requests a second per live key, 25 per test key.
500api_error.

Payments

GET/v1/paymentsبا کلید مخفی

List payments

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
expand[]اختیاری	کوئری	string[]	Expand references: `data.customer`, `data.deposits`, `data.receipts`.enum: customer, data.customer, deposits, data.deposits, receipts, data.receipts · maxItems: 10
statusاختیاری	کوئری	string	enum: requires_payment, processing, partially_paid, requires_review, succeeded, canceled, expired
customerاختیاری	کوئری	string	Object id (`cus_…`).
referenceاختیاری	کوئری	string	maxLength: 100
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/payments",
  "has_more": false,
  "data": [
    {
      "id": "pay_8xkq2LmZr0Pa1Bcd",
      "object": "payment",
      "livemode": false,
      "amount": 31250000,
      "amount_received": 20000000,
      "amount_remaining": 11250000,
      "amount_overpaid": 0,
      "amount_shortfall": 0,
      "currency": "irr",
      "status": "partially_paid",
      "expected_amount": 11250470,
      "payment_method_types": [
        "card",
        "transfer"
      ],
      "destination": {
        "card": "card_Q2wE4rT6yU8iO0pA",
        "type": "card",
        "bank": "mellat",
        "last4": "0000",
        "iban_last4": "0000",
        "holder_name": null
      },
      "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
      "return_url": "https://shop.example/orders/1042/thanks",
      "cancel_url": null,
      "expires_at": 1793001600,
      "customer": "cus_3mN5bV7cX9zL1kJh",
      "customer_details": {
        "name": "Test Customer",
        "phone": "09900001234",
        "email": "[email protected]"
      },
      "reference": "1042",
      "description": "Order 1042",
      "metadata": {
        "order_id": "1042"
      },
      "payment_link": null,
      "source": "api",
      "review": null,
      "overpayment": {
        "status": "none",
        "reference": null
      },
      "deposits": {
        "object": "list",
        "data": [
          {
            "id": "dep_7hG5fD3sA1qW9eR8",
            "amount": 20000000,
            "created": 1792999000
          }
        ],
        "has_more": false
      },
      "succeeded_at": null,
      "canceled_at": null,
      "created": 1792998000
    }
  ]
}

پاسخ‌های خطا:400401403429500

POST/v1/paymentsبا کلید مخفی

Create a payment

The customer is asked for a unique expected_amount on the destination; send them to checkout_url, where they pay card-to-card or by bank transfer as payment_method_types allows. A live payment of a restricted account is refused (account_restricted).

پارامترها

پارامترها
نام	محل	نوع	توضیح
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
amountالزامی	integer	Target amount. Integer rial.min: 10000 · max: 2000000000
referenceاختیاری	string	Your order id.maxLength: 100
descriptionاختیاری	string	maxLength: 500
customerاختیاری	string	Object id (`cus_…`).
customer_detailsاختیاری	object
customer_details[name]اختیاری	string	maxLength: 120
customer_details[phone]اختیاری	string	Any typed form; normalized to `09xxxxxxxxx`.
customer_details[email]اختیاری	string	format: email
return_urlاختیاری	string	format: uri
cancel_urlاختیاری	string	format: uri
expires_inاختیاری	integer	Seconds the checkout stays open.min: 300 · max: 86400
allow_partialاختیاری	boolean	Accept and track several deposits toward the target; defaults to the merchant setting.
cardاختیاری	string	Destination, a card or an account taking one of the enabled payment methods (else `payment_card_invalid`); defaults to the merchant's routing.
metadataاختیاری	Metadata	Strings only: up to 50 keys, key at most 40 characters (no `.`, not starting with `$`), value at most 500. On an update an empty value removes its key.
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":31250000,"reference":"1042","description":"Order 1042","customer_details":{"name":"Test Customer","phone":"09900001234"},"return_url":"https://shop.example/orders/1042/thanks","expires_in":1800,"metadata":{"order_id":"1042"}}'

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 0,
  "amount_remaining": 31250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "requires_payment",
  "expected_amount": 31250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

GET/v1/payments/{id}با کلید مخفی

Retrieve a payment

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
expand[]اختیاری	کوئری	string[]	Expand references: `customer`, `deposits`, `receipts`.enum: customer, deposits, receipts · maxItems: 10
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404429500

POST/v1/payments/{id}با کلید مخفی

Update an open payment

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
descriptionاختیاری	string	"" clears it.maxLength: 500
metadataاختیاری	Metadata	Strings only: up to 50 keys, key at most 40 characters (no `.`, not starting with `$`), value at most 500. On an update an empty value removes its key.
customer_detailsاختیاری	object
customer_details[name]اختیاری	string	maxLength: 120
customer_details[phone]اختیاری	string	Any typed form; normalized to `09xxxxxxxxx`.
customer_details[email]اختیاری	string	format: email
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/payments/{id}/cancelبا کلید مخفی

Cancel a payment

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
reasonاختیاری	string	minLength: 3 · maxLength: 500
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd/cancel \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/payments/{id}/topupبا کلید مخفی

Ask for the remaining amount again

Issues a fresh unique expected_amount for amount_remaining and extends the checkout.

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
expires_inاختیاری	integer	Seconds the checkout stays open.min: 300 · max: 86400
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd/topup \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/payments/{id}/attach_depositبا کلید مخفی

Attach an unmatched deposit

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
depositالزامی	string	Object id (`dep_…`).
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd/attach_deposit \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/payments/{id}/detach_depositبا کلید مخفی

Detach a matched deposit

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
depositالزامی	string	Object id (`dep_…`).
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd/detach_deposit \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/payments/{id}/approveبا کلید مخفی

Succeed a payment with a shortfall

Records amount_shortfall = amount_remaining.

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
reasonالزامی	string	minLength: 3 · maxLength: 500
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd/approve \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/payments/{id}/resolve_overpaymentبا کلید مخفی

Resolve an overpayment

credited adds the overpaid amount to the customer's credit.

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
statusالزامی	string	enum: refunded, credited, kept
referenceاختیاری	string	Refund transfer trace number.maxLength: 100
expandاختیاری	string[]	enum: customer, deposits, receipts · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd/resolve_overpayment \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "pay_8xkq2LmZr0Pa1Bcd",
  "object": "payment",
  "livemode": false,
  "amount": 31250000,
  "amount_received": 20000000,
  "amount_remaining": 11250000,
  "amount_overpaid": 0,
  "amount_shortfall": 0,
  "currency": "irr",
  "status": "partially_paid",
  "expected_amount": 11250470,
  "payment_method_types": [
    "card",
    "transfer"
  ],
  "destination": {
    "card": "card_Q2wE4rT6yU8iO0pA",
    "type": "card",
    "bank": "mellat",
    "last4": "0000",
    "iban_last4": "0000",
    "holder_name": null
  },
  "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
  "return_url": "https://shop.example/orders/1042/thanks",
  "cancel_url": null,
  "expires_at": 1793001600,
  "customer": "cus_3mN5bV7cX9zL1kJh",
  "customer_details": {
    "name": "Test Customer",
    "phone": "09900001234",
    "email": "[email protected]"
  },
  "reference": "1042",
  "description": "Order 1042",
  "metadata": {
    "order_id": "1042"
  },
  "payment_link": null,
  "source": "api",
  "review": null,
  "overpayment": {
    "status": "none",
    "reference": null
  },
  "deposits": {
    "object": "list",
    "data": [
      {
        "id": "dep_7hG5fD3sA1qW9eR8",
        "amount": 20000000,
        "created": 1792999000
      }
    ],
    "has_more": false
  },
  "succeeded_at": null,
  "canceled_at": null,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

Deposits

GET/v1/depositsبا کلید مخفی

List deposits

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
statusاختیاری	کوئری	string	enum: unmatched, matched, ignored, reversed
paymentاختیاری	کوئری	string	Object id (`pay_…`).
cardاختیاری	کوئری	string	Object id (`card_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/deposits \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/deposits",
  "has_more": false,
  "data": [
    {
      "id": "dep_7hG5fD3sA1qW9eR8",
      "object": "deposit",
      "livemode": false,
      "amount": 20000000,
      "currency": "irr",
      "status": "matched",
      "payment": "pay_8xkq2LmZr0Pa1Bcd",
      "payer_last4": "0000",
      "bank": "mellat",
      "bank_reference": "402911",
      "channel": "card",
      "source": "sms",
      "replaces": null,
      "created": 1792999000
    }
  ]
}

پاسخ‌های خطا:400401403429500

POST/v1/depositsبا کلید مخفی

Record a manual deposit

Matching runs right after, like for a deposit read from a bank SMS.

پارامترها

پارامترها
نام	محل	نوع	توضیح
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
cardالزامی	string	Object id (`card_…`).
amountالزامی	integer	Transfer amount. Integer rial.min: 1
payer_last4اختیاری	string	The last 4 digits of the payer card.
bank_referenceاختیاری	string	The bank's trace number; the same reference on one card is one deposit.minLength: 1 · maxLength: 64
occurred_atاختیاری	integer	When the transfer happened.format: int64
channelاختیاری	string	How the money came; omit when unknown.enum: card, pol, paya, satna, internal
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/deposits \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"card":"card_Q2wE4rT6yU8iO0pA","amount":20000000,"payer_last4":"0000","bank_reference":"402911","channel":"card"}'

پاسخ

{
  "id": "dep_7hG5fD3sA1qW9eR8",
  "object": "deposit",
  "livemode": false,
  "amount": 20000000,
  "currency": "irr",
  "status": "unmatched",
  "payment": null,
  "payer_last4": "0000",
  "bank": "mellat",
  "bank_reference": "402911",
  "channel": "card",
  "source": "manual",
  "replaces": null,
  "created": 1792999000
}

پاسخ‌های خطا:400401403404409429500

GET/v1/deposits/{id}با کلید مخفی

Retrieve a deposit

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`dep_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/deposits/dep_7hG5fD3sA1qW9eR8 \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "dep_7hG5fD3sA1qW9eR8",
  "object": "deposit",
  "livemode": false,
  "amount": 20000000,
  "currency": "irr",
  "status": "matched",
  "payment": "pay_8xkq2LmZr0Pa1Bcd",
  "payer_last4": "0000",
  "bank": "mellat",
  "bank_reference": "402911",
  "channel": "card",
  "source": "sms",
  "replaces": null,
  "created": 1792999000
}

پاسخ‌های خطا:400401403404429500

POST/v1/deposits/{id}/ignoreبا کلید مخفی

Ignore an unmatched deposit

For a transfer that is not a customer payment (a salary, a refund).

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`dep_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/deposits/dep_7hG5fD3sA1qW9eR8/ignore \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "dep_7hG5fD3sA1qW9eR8",
  "object": "deposit",
  "livemode": false,
  "amount": 20000000,
  "currency": "irr",
  "status": "ignored",
  "payment": null,
  "payer_last4": "0000",
  "bank": "mellat",
  "bank_reference": "402911",
  "channel": "card",
  "source": "sms",
  "replaces": null,
  "created": 1792999000
}

پاسخ‌های خطا:400401403404409429500

POST/v1/deposits/{id}/restoreبا کلید مخفی

Restore an ignored deposit

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`dep_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/deposits/dep_7hG5fD3sA1qW9eR8/restore \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "dep_7hG5fD3sA1qW9eR8",
  "object": "deposit",
  "livemode": false,
  "amount": 20000000,
  "currency": "irr",
  "status": "unmatched",
  "payment": null,
  "payer_last4": "0000",
  "bank": "mellat",
  "bank_reference": "402911",
  "channel": "card",
  "source": "sms",
  "replaces": null,
  "created": 1792999000
}

پاسخ‌های خطا:400401403404409429500

Payment links

GET/v1/payment_linksبا کلید مخفی

List payment links

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
expand[]اختیاری	کوئری	string[]	Expand references: `data.card`.enum: card, data.card · maxItems: 10
activeاختیاری	کوئری	boolean
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/payment_links \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/payment_links",
  "has_more": false,
  "data": [
    {
      "id": "plink_K8jH6gF4dS2aP0oI",
      "object": "payment_link",
      "livemode": false,
      "url": "https://bezanbecard.com/l/Xc7Vb9Nm",
      "title": "Donation",
      "description": null,
      "amount": {
        "type": "open",
        "value": null,
        "min": 100000,
        "max": 50000000,
        "presets": [
          500000,
          1000000
        ]
      },
      "active": true,
      "uses": 12,
      "max_uses": null,
      "expires_at": null,
      "collect": {
        "name": "optional",
        "phone": "required",
        "email": "off"
      },
      "after_completion": {
        "type": "message",
        "message": "Thank you!",
        "url": null
      },
      "card": null,
      "metadata": {},
      "created": 1792998000
    }
  ]
}

پاسخ‌های خطا:400401403429500

POST/v1/payment_linksبا کلید مخفی

Create a payment link

پارامترها

پارامترها
نام	محل	نوع	توضیح
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
titleالزامی	string	minLength: 1 · maxLength: 120
descriptionاختیاری	string	maxLength: 1000
amountالزامی	object \| object
collectاختیاری	object
collect[name]اختیاری	string	enum: off, optional, required
collect[phone]اختیاری	string	enum: off, optional, required
collect[email]اختیاری	string	enum: off, optional, required
cardاختیاری	string \| null	Destination override (a card or an account); null or "" removes it.
max_usesاختیاری	integer \| null	Completed payments after which the link stops; null or "" removes the limit.min: 1 · max: 1000000
expires_atاختیاری	integer \| null	A future unix second; null or "" removes the expiry.format: int64
after_completionاختیاری	object
after_completion[type]الزامی	string	enum: message, redirect
after_completion[message]اختیاری	string	maxLength: 500
after_completion[url]اختیاری	string	Required for `redirect`.format: uri
metadataاختیاری	Metadata	Strings only: up to 50 keys, key at most 40 characters (no `.`, not starting with `$`), value at most 500. On an update an empty value removes its key.
expandاختیاری	string[]	enum: card · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payment_links \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Donation","amount":{"type":"open","min":100000,"max":50000000,"presets":[500000,1000000]},"collect":{"phone":"required"}}'

پاسخ

{
  "id": "plink_K8jH6gF4dS2aP0oI",
  "object": "payment_link",
  "livemode": false,
  "url": "https://bezanbecard.com/l/Xc7Vb9Nm",
  "title": "Donation",
  "description": null,
  "amount": {
    "type": "open",
    "value": null,
    "min": 100000,
    "max": 50000000,
    "presets": [
      500000,
      1000000
    ]
  },
  "active": true,
  "uses": 12,
  "max_uses": null,
  "expires_at": null,
  "collect": {
    "name": "optional",
    "phone": "required",
    "email": "off"
  },
  "after_completion": {
    "type": "message",
    "message": "Thank you!",
    "url": null
  },
  "card": null,
  "metadata": {},
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

GET/v1/payment_links/{id}با کلید مخفی

Retrieve a payment link

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`plink_…`).
expand[]اختیاری	کوئری	string[]	Expand references: `card`.enum: card · maxItems: 10
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/payment_links/plink_K8jH6gF4dS2aP0oI \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "plink_K8jH6gF4dS2aP0oI",
  "object": "payment_link",
  "livemode": false,
  "url": "https://bezanbecard.com/l/Xc7Vb9Nm",
  "title": "Donation",
  "description": null,
  "amount": {
    "type": "open",
    "value": null,
    "min": 100000,
    "max": 50000000,
    "presets": [
      500000,
      1000000
    ]
  },
  "active": true,
  "uses": 12,
  "max_uses": null,
  "expires_at": null,
  "collect": {
    "name": "optional",
    "phone": "required",
    "email": "off"
  },
  "after_completion": {
    "type": "message",
    "message": "Thank you!",
    "url": null
  },
  "card": null,
  "metadata": {},
  "created": 1792998000
}

پاسخ‌های خطا:400401403404429500

POST/v1/payment_links/{id}با کلید مخفی

Update a payment link

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`plink_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
titleاختیاری	string	minLength: 1 · maxLength: 120
descriptionاختیاری	string	maxLength: 1000
amountاختیاری	object \| object
collectاختیاری	object
collect[name]اختیاری	string	enum: off, optional, required
collect[phone]اختیاری	string	enum: off, optional, required
collect[email]اختیاری	string	enum: off, optional, required
cardاختیاری	string \| null	Destination override (a card or an account); null or "" removes it.
max_usesاختیاری	integer \| null	Completed payments after which the link stops; null or "" removes the limit.min: 1 · max: 1000000
expires_atاختیاری	integer \| null	A future unix second; null or "" removes the expiry.format: int64
after_completionاختیاری	object
after_completion[type]الزامی	string	enum: message, redirect
after_completion[message]اختیاری	string	maxLength: 500
after_completion[url]اختیاری	string	Required for `redirect`.format: uri
metadataاختیاری	Metadata	Strings only: up to 50 keys, key at most 40 characters (no `.`, not starting with `$`), value at most 500. On an update an empty value removes its key.
activeاختیاری	boolean	`false` archives the link.
expandاختیاری	string[]	enum: card · maxItems: 10

درخواست

curl -X POST https://a.bezanbecard.com/v1/payment_links/plink_K8jH6gF4dS2aP0oI \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "plink_K8jH6gF4dS2aP0oI",
  "object": "payment_link",
  "livemode": false,
  "url": "https://bezanbecard.com/l/Xc7Vb9Nm",
  "title": "Donation",
  "description": null,
  "amount": {
    "type": "open",
    "value": null,
    "min": 100000,
    "max": 50000000,
    "presets": [
      500000,
      1000000
    ]
  },
  "active": true,
  "uses": 12,
  "max_uses": null,
  "expires_at": null,
  "collect": {
    "name": "optional",
    "phone": "required",
    "email": "off"
  },
  "after_completion": {
    "type": "message",
    "message": "Thank you!",
    "url": null
  },
  "card": null,
  "metadata": {},
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

Customers

GET/v1/customersبا کلید مخفی

List customers

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
phoneاختیاری	کوئری	string	Any typed form.
emailاختیاری	کوئری	string	format: email
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/customers \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_3mN5bV7cX9zL1kJh",
      "object": "customer",
      "livemode": false,
      "name": "Test Customer",
      "phone": "09900001234",
      "email": "[email protected]",
      "credit": 0,
      "metadata": {},
      "created": 1792998000
    }
  ]
}

پاسخ‌های خطا:400401403429500

POST/v1/customersبا کلید مخفی

Create a customer

پارامترها

پارامترها
نام	محل	نوع	توضیح
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
nameاختیاری	string	maxLength: 120
phoneاختیاری	string	Any typed form; normalized to `09xxxxxxxxx`; unique per mode.
emailاختیاری	string	format: email
metadataاختیاری	Metadata	Strings only: up to 50 keys, key at most 40 characters (no `.`, not starting with `$`), value at most 500. On an update an empty value removes its key.
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/customers \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Customer","phone":"09900001234","email":"[email protected]"}'

پاسخ

{
  "id": "cus_3mN5bV7cX9zL1kJh",
  "object": "customer",
  "livemode": false,
  "name": "Test Customer",
  "phone": "09900001234",
  "email": "[email protected]",
  "credit": 0,
  "metadata": {},
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

GET/v1/customers/{id}با کلید مخفی

Retrieve a customer

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`cus_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/customers/cus_3mN5bV7cX9zL1kJh \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "cus_3mN5bV7cX9zL1kJh",
  "object": "customer",
  "livemode": false,
  "name": "Test Customer",
  "phone": "09900001234",
  "email": "[email protected]",
  "credit": 0,
  "metadata": {},
  "created": 1792998000
}

پاسخ‌های خطا:400401403404429500

POST/v1/customers/{id}با کلید مخفی

Update a customer

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`cus_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
nameاختیاری	string	maxLength: 120
phoneاختیاری	string	Any typed form; normalized to `09xxxxxxxxx`; unique per mode.
emailاختیاری	string	format: email
metadataاختیاری	Metadata	Strings only: up to 50 keys, key at most 40 characters (no `.`, not starting with `$`), value at most 500. On an update an empty value removes its key.
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/customers/cus_3mN5bV7cX9zL1kJh \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "cus_3mN5bV7cX9zL1kJh",
  "object": "customer",
  "livemode": false,
  "name": "Test Customer",
  "phone": "09900001234",
  "email": "[email protected]",
  "credit": 0,
  "metadata": {},
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

DELETE/v1/customers/{id}با کلید مخفی

Delete a customer

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`cus_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl -X DELETE https://a.bezanbecard.com/v1/customers/cus_3mN5bV7cX9zL1kJh \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "cus_3mN5bV7cX9zL1kJh",
  "object": "customer",
  "deleted": true
}

پاسخ‌های خطا:400401403404429500

Events

GET/v1/eventsبا کلید مخفی

List events

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
typeاختیاری	کوئری	string	An event type, or every type of one object: `payment.*`.
types[]اختیاری	کوئری	string[]	Any of these types (not with `type`).enum: payment.created, payment.processing, payment.partially_paid, payment.requires_review, payment.succeeded, payment.overpaid, payment.overpayment_resolved, payment.canceled, payment.expired, payment.updated, deposit.created, deposit.matched, deposit.unmatched, deposit.ignored, payment_link.created, payment_link.updated, customer.created, customer.updated, customer.deleted, device.online, device.offline, device.revoked, card.created, card.updated, receipt.created, receipt.approved, receipt.rejected
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/events \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_9oI7uY5tR3eW1qA2",
      "object": "event",
      "livemode": false,
      "type": "payment.succeeded",
      "api_version": "2026-10-01",
      "created": 1793000000,
      "data": {
        "object": {
          "id": "pay_8xkq2LmZr0Pa1Bcd",
          "object": "payment",
          "livemode": false,
          "amount": 31250000,
          "amount_received": 20000000,
          "amount_remaining": 11250000,
          "amount_overpaid": 0,
          "amount_shortfall": 0,
          "currency": "irr",
          "status": "partially_paid",
          "expected_amount": 11250470,
          "payment_method_types": [
            "card",
            "transfer"
          ],
          "destination": {
            "card": "card_Q2wE4rT6yU8iO0pA",
            "type": "card",
            "bank": "mellat",
            "last4": "0000",
            "iban_last4": "0000",
            "holder_name": null
          },
          "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
          "return_url": "https://shop.example/orders/1042/thanks",
          "cancel_url": null,
          "expires_at": 1793001600,
          "customer": "cus_3mN5bV7cX9zL1kJh",
          "customer_details": {
            "name": "Test Customer",
            "phone": "09900001234",
            "email": "[email protected]"
          },
          "reference": "1042",
          "description": "Order 1042",
          "metadata": {
            "order_id": "1042"
          },
          "payment_link": null,
          "source": "api",
          "review": null,
          "overpayment": {
            "status": "none",
            "reference": null
          },
          "deposits": {
            "object": "list",
            "data": [
              {
                "id": "dep_7hG5fD3sA1qW9eR8",
                "amount": 20000000,
                "created": 1792999000
              }
            ],
            "has_more": false
          },
          "succeeded_at": null,
          "canceled_at": null,
          "created": 1792998000
        }
      },
      "request": {
        "id": "req_5tR3eW1qA2sD4fG6",
        "idempotency_key": "1042-create"
      }
    }
  ]
}

پاسخ‌های خطا:400401403429500

GET/v1/events/{id}با کلید مخفی

Retrieve an event

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`evt_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/events/evt_9oI7uY5tR3eW1qA2 \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "evt_9oI7uY5tR3eW1qA2",
  "object": "event",
  "livemode": false,
  "type": "payment.succeeded",
  "api_version": "2026-10-01",
  "created": 1793000000,
  "data": {
    "object": {
      "id": "pay_8xkq2LmZr0Pa1Bcd",
      "object": "payment",
      "livemode": false,
      "amount": 31250000,
      "amount_received": 20000000,
      "amount_remaining": 11250000,
      "amount_overpaid": 0,
      "amount_shortfall": 0,
      "currency": "irr",
      "status": "partially_paid",
      "expected_amount": 11250470,
      "payment_method_types": [
        "card",
        "transfer"
      ],
      "destination": {
        "card": "card_Q2wE4rT6yU8iO0pA",
        "type": "card",
        "bank": "mellat",
        "last4": "0000",
        "iban_last4": "0000",
        "holder_name": null
      },
      "checkout_url": "https://bezanbecard.com/pay/Qm9vT2xlR29vZ2xlR29vZ2xlR29vZ2xl",
      "return_url": "https://shop.example/orders/1042/thanks",
      "cancel_url": null,
      "expires_at": 1793001600,
      "customer": "cus_3mN5bV7cX9zL1kJh",
      "customer_details": {
        "name": "Test Customer",
        "phone": "09900001234",
        "email": "[email protected]"
      },
      "reference": "1042",
      "description": "Order 1042",
      "metadata": {
        "order_id": "1042"
      },
      "payment_link": null,
      "source": "api",
      "review": null,
      "overpayment": {
        "status": "none",
        "reference": null
      },
      "deposits": {
        "object": "list",
        "data": [
          {
            "id": "dep_7hG5fD3sA1qW9eR8",
            "amount": 20000000,
            "created": 1792999000
          }
        ],
        "has_more": false
      },
      "succeeded_at": null,
      "canceled_at": null,
      "created": 1792998000
    }
  },
  "request": {
    "id": "req_5tR3eW1qA2sD4fG6",
    "idempotency_key": "1042-create"
  }
}

پاسخ‌های خطا:400401403404429500

Webhook endpoints

GET/v1/webhook_endpointsبا کلید مخفی

List webhook endpoints

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/webhook_endpoints",
  "has_more": false,
  "data": [
    {
      "id": "we_L4kJ2hG0fD8sA6pO",
      "object": "webhook_endpoint",
      "livemode": false,
      "url": "https://shop.example/bezanbecard/webhook",
      "enabled_events": [
        "payment.succeeded",
        "payment.partially_paid"
      ],
      "status": "enabled",
      "description": "Order sync",
      "api_version": "2026-10-01",
      "created": 1792998000
    }
  ]
}

پاسخ‌های خطا:400401403429500

POST/v1/webhook_endpointsبا کلید مخفی

Create a webhook endpoint

The answer carries secret (whsec_…) once: store it to verify Bezanbecard-Signature.

پارامترها

پارامترها
نام	محل	نوع	توضیح
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
urlالزامی	string	An https URL in live mode (test mode also accepts http). Private, loopback and link-local destinations are refused.maxLength: 2000 · format: uri
enabled_eventsالزامی	string[]	Event types, or `[""]` for every type.enum: payment.created, payment.processing, payment.partially_paid, payment.requires_review, payment.succeeded, payment.overpaid, payment.overpayment_resolved, payment.canceled, payment.expired, payment.updated, deposit.created, deposit.matched, deposit.unmatched, deposit.ignored, payment_link.created, payment_link.updated, customer.created, customer.updated, customer.deleted, device.online, device.offline, device.revoked, card.created, card.updated, receipt.created, receipt.approved, receipt.rejected,
descriptionاختیاری	string	maxLength: 500
api_versionاختیاری	string	enum: 2026-10-01
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example/bezanbecard/webhook","enabled_events":["payment.succeeded","payment.partially_paid"],"description":"Order sync"}'

پاسخ

{
  "id": "we_L4kJ2hG0fD8sA6pO",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://shop.example/bezanbecard/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.partially_paid"
  ],
  "status": "enabled",
  "description": "Order sync",
  "api_version": "2026-10-01",
  "created": 1792998000,
  "secret": "whsec_dGVzdF9zZWNyZXRfZm9yX2V4YW1wbGVzXzAxMjM0NTY"
}

پاسخ‌های خطا:400401403404409429500

GET/v1/webhook_endpoints/{id}با کلید مخفی

Retrieve a webhook endpoint

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`we_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/webhook_endpoints/we_L4kJ2hG0fD8sA6pO \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "we_L4kJ2hG0fD8sA6pO",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://shop.example/bezanbecard/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.partially_paid"
  ],
  "status": "enabled",
  "description": "Order sync",
  "api_version": "2026-10-01",
  "created": 1792998000
}

پاسخ‌های خطا:400401403404429500

POST/v1/webhook_endpoints/{id}با کلید مخفی

Update a webhook endpoint

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`we_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
urlاختیاری	string	An https URL in live mode (test mode also accepts http). Private, loopback and link-local destinations are refused.maxLength: 2000 · format: uri
enabled_eventsاختیاری	string[]	Event types, or `[""]` for every type.enum: payment.created, payment.processing, payment.partially_paid, payment.requires_review, payment.succeeded, payment.overpaid, payment.overpayment_resolved, payment.canceled, payment.expired, payment.updated, deposit.created, deposit.matched, deposit.unmatched, deposit.ignored, payment_link.created, payment_link.updated, customer.created, customer.updated, customer.deleted, device.online, device.offline, device.revoked, card.created, card.updated, receipt.created, receipt.approved, receipt.rejected,
descriptionاختیاری	string	"" clears it.maxLength: 500
statusاختیاری	string	`enabled` also starts the failure count afresh.enum: enabled, disabled
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/webhook_endpoints/we_L4kJ2hG0fD8sA6pO \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "we_L4kJ2hG0fD8sA6pO",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://shop.example/bezanbecard/webhook",
  "enabled_events": [
    "payment.succeeded",
    "payment.partially_paid"
  ],
  "status": "enabled",
  "description": "Order sync",
  "api_version": "2026-10-01",
  "created": 1792998000
}

پاسخ‌های خطا:400401403404409429500

DELETE/v1/webhook_endpoints/{id}با کلید مخفی

Delete a webhook endpoint

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`we_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl -X DELETE https://a.bezanbecard.com/v1/webhook_endpoints/we_L4kJ2hG0fD8sA6pO \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "we_L4kJ2hG0fD8sA6pO",
  "object": "webhook_endpoint",
  "deleted": true
}

پاسخ‌های خطا:400401403404429500

Cards

GET/v1/cardsبا کلید مخفی

List cards

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
statusاختیاری	کوئری	string	enum: active, disabled, archived
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/cards \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_Q2wE4rT6yU8iO0pA",
      "object": "card",
      "type": "card",
      "bank": "mellat",
      "last4": "0000",
      "iban_last4": "0000",
      "holder_name": null,
      "label": "Shop card",
      "status": "active",
      "default": true,
      "created": 1792998000
    }
  ]
}

پاسخ‌های خطا:400401403429500

GET/v1/cards/{id}با کلید مخفی

Retrieve a card

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`card_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/cards/card_Q2wE4rT6yU8iO0pA \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "card_Q2wE4rT6yU8iO0pA",
  "object": "card",
  "type": "card",
  "bank": "mellat",
  "last4": "0000",
  "iban_last4": "0000",
  "holder_name": null,
  "label": "Shop card",
  "status": "active",
  "default": true,
  "created": 1792998000
}

پاسخ‌های خطا:400401403404429500

Devices

GET/v1/devicesبا کلید مخفی

List devices

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
healthاختیاری	کوئری	string	enum: online, stale, offline
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/devices \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/devices",
  "has_more": false,
  "data": [
    {
      "id": "dev_Z1xC3vB5nM7aS9dF",
      "object": "device",
      "name": "Shop phone",
      "platform": "android",
      "health": "online",
      "seen_at": 1792999900
    }
  ]
}

پاسخ‌های خطا:400401403429500

GET/v1/devices/{id}با کلید مخفی

Retrieve a device

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`dev_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/devices/dev_Z1xC3vB5nM7aS9dF \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "dev_Z1xC3vB5nM7aS9dF",
  "object": "device",
  "name": "Shop phone",
  "platform": "android",
  "health": "online",
  "seen_at": 1792999900
}

پاسخ‌های خطا:400401403404429500

Receipts

POST/v1/payments/{id}/receiptsبا کلید مخفی

Submit a receipt for a payment

For a custom checkout, or a customer who sent the receipt another way: the files go in the multipart field files (or send JSON without files). The receipt records the customer's claim, a payment waiting for money becomes processing, and your team reviews it in the receipt queue (or approve it here). The files are stored as uploaded with their SHA-256; the API never serves them back.

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`pay_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
channelاختیاری	string	How the money went; defaults to `card` when the payment takes cards.enum: card, pol, paya, satna, internal
referenceاختیاری	string	The tracking number on the bank receipt: 4-40 letters and digits (Persian digits accepted).maxLength: 80
amountاختیاری	integer	What the customer says they sent; omit for the expected amount. Integer rial.min: 1 · max: 20000000000
paid_atاختیاری	integer	When the customer says they paid.format: int64
payer_nameاختیاری	string	minLength: 1 · maxLength: 120
payer_last4اختیاری	string	The last 4 digits of the paying card.
replaceاختیاری	boolean	Withdraw the pending receipts submitted earlier through the API for this payment (a corrected receipt, not a second transfer).
expandاختیاری	any[]	Nothing to expand.maxItems: 0
filesاختیاری	file[]	Up to 3 files of at most 10 MB: JPEG, PNG, WebP, HEIC or PDF, told by their bytes.maxItems: 3

درخواست

curl -X POST https://a.bezanbecard.com/v1/payments/rcp_4rT6yU8iO0pA2sD4/receipts \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F channel=paya \
  -F reference=140508041234 \
  -F amount=11250470 \
  -F paid_at=1792999600 \
  -F [email protected]

پاسخ

{
  "id": "rcp_4rT6yU8iO0pA2sD4",
  "object": "receipt",
  "livemode": false,
  "payment": "pay_8xkq2LmZr0Pa1Bcd",
  "status": "pending",
  "channel": "paya",
  "reference": "140508041234",
  "amount": 11250470,
  "paid_at": 1792999600,
  "payer_name": "Test Customer",
  "payer_last4": null,
  "files": [
    {
      "id": "file_7uI9oP1aS3dF5gH7",
      "size": 184320,
      "sha256": "9f2c0e5b7a1d3f4c6b8a0e2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a"
    }
  ],
  "duplicate": false,
  "corroborated": false,
  "review": null,
  "created": 1792999700
}

پاسخ‌های خطا:400401403404409429500

GET/v1/receiptsبا کلید مخفی

List receipts

پارامترها

پارامترها
نام	محل	نوع	توضیح
limitاختیاری	کوئری	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afterاختیاری	کوئری	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeاختیاری	کوئری	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdاختیاری	کوئری	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
statusاختیاری	کوئری	string	`pending` is the review queue.enum: pending, approved, rejected, withdrawn
channelاختیاری	کوئری	string	enum: card, pol, paya, satna, internal
paymentاختیاری	کوئری	string	Object id (`pay_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/receipts \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "object": "list",
  "url": "/v1/receipts",
  "has_more": false,
  "data": [
    {
      "id": "rcp_4rT6yU8iO0pA2sD4",
      "object": "receipt",
      "livemode": false,
      "payment": "pay_8xkq2LmZr0Pa1Bcd",
      "status": "pending",
      "channel": "paya",
      "reference": "140508041234",
      "amount": 11250470,
      "paid_at": 1792999600,
      "payer_name": "Test Customer",
      "payer_last4": null,
      "files": [
        {
          "id": "file_7uI9oP1aS3dF5gH7",
          "size": 184320,
          "sha256": "9f2c0e5b7a1d3f4c6b8a0e2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a"
        }
      ],
      "duplicate": false,
      "corroborated": false,
      "review": null,
      "created": 1792999700
    }
  ]
}

پاسخ‌های خطا:400401403429500

GET/v1/receipts/{id}با کلید مخفی

Retrieve a receipt

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`rcp_…`).
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/receipts/rcp_4rT6yU8iO0pA2sD4 \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "rcp_4rT6yU8iO0pA2sD4",
  "object": "receipt",
  "livemode": false,
  "payment": "pay_8xkq2LmZr0Pa1Bcd",
  "status": "pending",
  "channel": "paya",
  "reference": "140508041234",
  "amount": 11250470,
  "paid_at": 1792999600,
  "payer_name": "Test Customer",
  "payer_last4": null,
  "files": [
    {
      "id": "file_7uI9oP1aS3dF5gH7",
      "size": 184320,
      "sha256": "9f2c0e5b7a1d3f4c6b8a0e2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a"
    }
  ],
  "duplicate": false,
  "corroborated": false,
  "review": null,
  "created": 1792999700
}

پاسخ‌های خطا:400401403404429500

POST/v1/receipts/{id}/approveبا کلید مخفی

Approve a receipt

Backs the receipt with exactly one deposit (the one you name, its corroborating bank SMS, a deposit of the approved amount already on the payment, or a new deposit of source receipt) and reconciles the payment. A bank SMS deposit you name also makes the receipt corroborated when it fits the amount and paying card the receipt states (a receipt that states no amount claims what the payment expected when it was sent); a deposit another approved receipt stands on is receipt_deposit_unavailable. A deposit whose money this payment gave back (a refund or credit) and that has left the payment since is deposit_given_back. A bank SMS corroborates one receipt at most. Refusals: a canceled or expired payment whose money was given back takes no approval (receipt_payment_refunded); money that would overpay past an overpayment already resolved is receipt_overpayment_resolved; money past what the payment still asks for needs overpay (receipt_payment_settled). Another change to the same payment still running after about 4 seconds is payment_already_changed: nothing ran, so a retry with the same Idempotency-Key runs. A second decision is receipt_action_unavailable.

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`rcp_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
amountاختیاری	integer	The approved amount; defaults to the receipt amount, else the amount of the bank SMS corroborating it (for a copy, its original's), else the amount the payment asked for when the receipt was sent, else the amount it expects now, else the remainder. Another amount on a receipt that states none gives the SMS up for its own receipt. Integer rial.min: 1 · max: 20000000000
depositاختیاری	string	A bank deposit of this transfer on the payment's destination, unmatched or on this payment (its amount is approved).
overpayاختیاری	boolean	Confirms money beyond what the payment still asks for (otherwise `receipt_payment_settled`). Send `amount` with it when nothing remains and the receipt states no amount (otherwise `receipt_amount_required`).
noteاختیاری	string	Internal; never shown to the customer.minLength: 1 · maxLength: 500
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/receipts/rcp_4rT6yU8iO0pA2sD4/approve \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "rcp_4rT6yU8iO0pA2sD4",
  "object": "receipt",
  "livemode": false,
  "payment": "pay_8xkq2LmZr0Pa1Bcd",
  "status": "approved",
  "channel": "paya",
  "reference": "140508041234",
  "amount": 11250470,
  "paid_at": 1792999600,
  "payer_name": "Test Customer",
  "payer_last4": null,
  "files": [
    {
      "id": "file_7uI9oP1aS3dF5gH7",
      "size": 184320,
      "sha256": "9f2c0e5b7a1d3f4c6b8a0e2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a"
    }
  ],
  "duplicate": false,
  "corroborated": false,
  "review": {
    "decision": "approved",
    "amount": 11250470,
    "reason": null,
    "reviewed_at": 1792999900
  },
  "created": 1792999700
}

پاسخ‌های خطا:400401403404409429500

POST/v1/receipts/{id}/rejectبا کلید مخفی

Reject a receipt

Never moves money. A processing payment with no other pending receipt waits for a transfer again, so the customer may submit another receipt.

پارامترها

پارامترها
نام	محل	نوع	توضیح
idالزامی	مسیر	string	Object id (`rcp_…`).
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
reasonالزامی	string	Shown to the customer on the checkout.enum: not_received, amount_mismatch, unreadable, duplicate, other
noteاختیاری	string	Internal; never shown to the customer.minLength: 1 · maxLength: 500
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/receipts/rcp_4rT6yU8iO0pA2sD4/reject \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

پاسخ

{
  "id": "rcp_4rT6yU8iO0pA2sD4",
  "object": "receipt",
  "livemode": false,
  "payment": "pay_8xkq2LmZr0Pa1Bcd",
  "status": "rejected",
  "channel": "paya",
  "reference": "140508041234",
  "amount": 11250470,
  "paid_at": 1792999600,
  "payer_name": "Test Customer",
  "payer_last4": null,
  "files": [
    {
      "id": "file_7uI9oP1aS3dF5gH7",
      "size": 184320,
      "sha256": "9f2c0e5b7a1d3f4c6b8a0e2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a"
    }
  ],
  "duplicate": false,
  "corroborated": false,
  "review": {
    "decision": "rejected",
    "amount": null,
    "reason": "unreadable",
    "reviewed_at": 1792999900
  },
  "created": 1792999700
}

پاسخ‌های خطا:400401403404409429500

Test helpers

POST/v1/test_helpers/depositsبا کلید مخفی

Simulate a deposit (test keys only)

Pass payment alone to simulate the exact expected amount of that payment. A live key is refused (test_mode_only).

پارامترها

پارامترها
نام	محل	نوع	توضیح
Idempotency-Keyاختیاری	هدر	string	Retry a POST safely: the same key and body within 24 hours replays the first answer (`Idempotent-Replayed: true`); another body is an idempotency_error.minLength: 1 · maxLength: 255
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
cardاختیاری	string	Defaults to the payment's destination card.
amountاختیاری	integer	Transfer amount. Integer rial.min: 1
payer_last4اختیاری	string
paymentاختیاری	string	Shortcut: a transfer of exactly its expected amount.
channelاختیاری	string	How the simulated money came; omit for unknown.enum: card, pol, paya, satna, internal
expandاختیاری	any[]	Nothing to expand.maxItems: 0

درخواست

curl -X POST https://a.bezanbecard.com/v1/test_helpers/deposits \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"payment":"pay_8xkq2LmZr0Pa1Bcd"}'

پاسخ

{
  "id": "dep_7hG5fD3sA1qW9eR8",
  "object": "deposit",
  "livemode": false,
  "amount": 11250470,
  "currency": "irr",
  "status": "matched",
  "payment": "pay_8xkq2LmZr0Pa1Bcd",
  "payer_last4": "0000",
  "bank": "mellat",
  "bank_reference": "402911",
  "channel": "card",
  "source": "simulation",
  "replaces": null,
  "created": 1792999000
}

پاسخ‌های خطا:400401403404409429500

Account

GET/v1/accountبا کلید مخفی

Retrieve the account of the key

پارامترها

پارامترها
نام	محل	نوع	توضیح
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

درخواست

curl https://a.bezanbecard.com/v1/account \
  -H "Authorization: Bearer sk_test_…"

پاسخ

{
  "id": "acct_PRQdNXTw05dzWxnx",
  "object": "account",
  "livemode": false,
  "name": "Example Shop",
  "slug": "example-shop",
  "status": "active",
  "website": "https://shop.example",
  "support": {
    "phone": "09900001234",
    "email": "[email protected]",
    "telegram": null,
    "url": null
  },
  "capabilities": {
    "api": true,
    "webhooks": true,
    "telegram": true,
    "team": false,
    "custom_branding": false,
    "priority_support": false,
    "partial_payments": true,
    "auto_confirm": true,
    "live_payments": true,
    "bank_transfer": true
  },
  "created": 1792998000
}

پاسخ‌های خطا:400401403429500

Connect

POST/v1/connect/exchangeبدون کلید

Exchange a plugin connect code for keys

Public: the one-time code from the connect redirect (10 minutes, single use) is the credential. Creates the plugin's restricted key and webhook endpoint and answers both secrets once. An unknown, used or expired code is connect_code_invalid. Limited to 10 calls per 15 minutes per IP.

پارامترها

پارامترها
نام	محل	نوع	توضیح
Bezanbecard-Versionاختیاری	هدر	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

بدنهٔ درخواست

بدنهٔ درخواست
نام	نوع	توضیح
codeالزامی	string	maxLength: 128

درخواست

curl -X POST https://a.bezanbecard.com/v1/connect/exchange \
  -H "Content-Type: application/json" \
  -d '{"code":"mY4kq0cX1n6Lw8Zt3Rb5Vd7Hf9Jg2Ks0Pe4Ua6Yi8Oo"}'

پاسخ

{
  "secret_key": "rk_test_4eC39HqLyjWDarjtT1zdp7dc0000000000000000",
  "webhook_secret": "whsec_dGVzdF9zZWNyZXRfZm9yX2V4YW1wbGVzXzAxMjM0NTY",
  "redirect_secret": "rds_cmVkaXJlY3Rfc2VjcmV0X2Zvcl9leGFtcGxlczAxMjM0",
  "livemode": false,
  "account": {
    "id": "acct_PRQdNXTw05dzWxnx",
    "object": "account",
    "livemode": false,
    "name": "Example Shop",
    "slug": "example-shop",
    "status": "active",
    "website": "https://shop.example",
    "support": {
      "phone": "09900001234",
      "email": "[email protected]",
      "telegram": null,
      "url": null
    },
    "capabilities": {
      "api": true,
      "webhooks": true,
      "telegram": true,
      "team": false,
      "custom_branding": false,
      "priority_support": false,
      "partial_payments": true,
      "auto_confirm": true,
      "live_payments": true,
      "bank_transfer": true
    },
    "created": 1792998000
  }
}

پاسخ‌های خطا:400403429500