API reference

Every endpoint of the public API with its parameters, a request and an example answer, read live from the OpenAPI document.

The public API lives at https://a.bezanbecard.com/v1. It speaks JSON over HTTPS, takes amounts as integers in rial and times as unix seconds, and answers in Stripe's style: snake_case fields, list objects with cursors, typed errors.

Conventions

Conventions
Topic	Convention
Authentication	`Authorization: Bearer sk_test_…`, or HTTP basic with the key as the user. The key decides the mode. See keys.
Request bodies	JSON with `Content-Type: application/json`. Unknown parameters are refused (`parameter_unknown`). `POST /v1/payments/:id/receipts` also takes `multipart/form-data`, with the files in `files`.
Retries	Send an `Idempotency-Key` with every `POST`. See idempotency.
Versions	`Bezanbecard-Version: 2026-10-01`; without it, the key's version.
Lists	`limit`, `starting_after`, `ending_before`, `created`. See pagination.
Errors	`{ "error": { "type", "code", "message", "param", "doc_url", "request_id" } }`. See errors.
Request ids	Every answer has a `Request-Id` header; your request logs in the dashboard keep each call for 30 days.
Rate limits	100 requests a second per live key, 25 per test key.

Receipts

A receipt (rcp_…) is the customer's evidence for one payment. GET /v1/receipts lists them (status=pending is your review queue), GET /v1/receipts/:id reads one, POST /v1/payments/:id/receipts submits one, and POST /v1/receipts/:id/approve and /reject decide it. A payment carries its receipts with expand[]=receipts. Files appear by id, size and SHA-256; the API never serves them back. An approval made before the bank SMS stands on a deposit of source receipt; when the SMS of the same transfer takes its place, the SMS deposit names it in replaces (otherwise null), so the transfer is booked once. See receipts and review.

Bank transfer fields

A payment says how it may be paid in payment_method_types (card, transfer). Its destination has a type (card or account) and iban_last4, and with a secret key the full iban beside pan; pan and last4 are null for an account. A card object has type and iban_last4 too, a deposit has channel (card, pol, paya, satna, internal), and the account's capabilities.bank_transfer says whether your settings take transfers. See bank transfers.

The OpenAPI document

GET https://a.bezanbecard.com/v1/openapi.json is the OpenAPI 3.1 description of this API, public and cacheable for five minutes. It is built from the same rules the API validates with, so it cannot drift from it. Import it into your API client, or generate a client in a language without an official library. The operations below are rendered from it.

Operations

Base URL: https://a.bezanbecard.com
API version: 2026-10-01
Operations: 44 operations

Error responses

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/paymentsSecret key

List payments

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
expand[]optional	query	string[]	Expand references: `data.customer`, `data.deposits`, `data.receipts`.enum: customer, data.customer, deposits, data.deposits, receipts, data.receipts · maxItems: 10
statusoptional	query	string	enum: requires_payment, processing, partially_paid, requires_review, succeeded, canceled, expired
customeroptional	query	string	Object id (`cus_…`).
referenceoptional	query	string	maxLength: 100
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

POST/v1/paymentsSecret key

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).

Parameters

Parameters
Name	In	Type	Description
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
amountrequired	integer	Target amount. Integer rial.min: 10000 · max: 2000000000
referenceoptional	string	Your order id.maxLength: 100
descriptionoptional	string	maxLength: 500
customeroptional	string	Object id (`cus_…`).
customer_detailsoptional	object
customer_details[name]optional	string	maxLength: 120
customer_details[phone]optional	string	Any typed form; normalized to `09xxxxxxxxx`.
customer_details[email]optional	string	format: email
return_urloptional	string	format: uri
cancel_urloptional	string	format: uri
expires_inoptional	integer	Seconds the checkout stays open.min: 300 · max: 86400
allow_partialoptional	boolean	Accept and track several deposits toward the target; defaults to the merchant setting.
cardoptional	string	Destination, a card or an account taking one of the enabled payment methods (else `payment_card_invalid`); defaults to the merchant's routing.
metadataoptional	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.
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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"}}'

Response

{
  "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
}

Error responses:400401403404409429500

GET/v1/payments/{id}Secret key

Retrieve a payment

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
expand[]optional	query	string[]	Expand references: `customer`, `deposits`, `receipts`.enum: customer, deposits, receipts · maxItems: 10
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403404429500

POST/v1/payments/{id}Secret key

Update an open payment

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
descriptionoptional	string	"" clears it.maxLength: 500
metadataoptional	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_detailsoptional	object
customer_details[name]optional	string	maxLength: 120
customer_details[phone]optional	string	Any typed form; normalized to `09xxxxxxxxx`.
customer_details[email]optional	string	format: email
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/payments/{id}/cancelSecret key

Cancel a payment

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
reasonoptional	string	minLength: 3 · maxLength: 500
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/payments/{id}/topupSecret key

Ask for the remaining amount again

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

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
expires_inoptional	integer	Seconds the checkout stays open.min: 300 · max: 86400
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/payments/{id}/attach_depositSecret key

Attach an unmatched deposit

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
depositrequired	string	Object id (`dep_…`).
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/payments/{id}/detach_depositSecret key

Detach a matched deposit

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
depositrequired	string	Object id (`dep_…`).
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/payments/{id}/approveSecret key

Succeed a payment with a shortfall

Records amount_shortfall = amount_remaining.

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
reasonrequired	string	minLength: 3 · maxLength: 500
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/payments/{id}/resolve_overpaymentSecret key

Resolve an overpayment

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

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
statusrequired	string	enum: refunded, credited, kept
referenceoptional	string	Refund transfer trace number.maxLength: 100
expandoptional	string[]	enum: customer, deposits, receipts · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

Deposits

GET/v1/depositsSecret key

List deposits

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
statusoptional	query	string	enum: unmatched, matched, ignored, reversed
paymentoptional	query	string	Object id (`pay_…`).
cardoptional	query	string	Object id (`card_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

POST/v1/depositsSecret key

Record a manual deposit

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

Parameters

Parameters
Name	In	Type	Description
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
cardrequired	string	Object id (`card_…`).
amountrequired	integer	Transfer amount. Integer rial.min: 1
payer_last4optional	string	The last 4 digits of the payer card.
bank_referenceoptional	string	The bank's trace number; the same reference on one card is one deposit.minLength: 1 · maxLength: 64
occurred_atoptional	integer	When the transfer happened.format: int64
channeloptional	string	How the money came; omit when unknown.enum: card, pol, paya, satna, internal
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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"}'

Response

{
  "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
}

Error responses:400401403404409429500

GET/v1/deposits/{id}Secret key

Retrieve a deposit

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`dep_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403404429500

POST/v1/deposits/{id}/ignoreSecret key

Ignore an unmatched deposit

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

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`dep_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/deposits/{id}/restoreSecret key

Restore an ignored deposit

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`dep_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

Payment links

GET/v1/payment_linksSecret key

List payment links

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
expand[]optional	query	string[]	Expand references: `data.card`.enum: card, data.card · maxItems: 10
activeoptional	query	boolean
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

POST/v1/payment_linksSecret key

Create a payment link

Parameters

Parameters
Name	In	Type	Description
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
titlerequired	string	minLength: 1 · maxLength: 120
descriptionoptional	string	maxLength: 1000
amountrequired	object \| object
collectoptional	object
collect[name]optional	string	enum: off, optional, required
collect[phone]optional	string	enum: off, optional, required
collect[email]optional	string	enum: off, optional, required
cardoptional	string \| null	Destination override (a card or an account); null or "" removes it.
max_usesoptional	integer \| null	Completed payments after which the link stops; null or "" removes the limit.min: 1 · max: 1000000
expires_atoptional	integer \| null	A future unix second; null or "" removes the expiry.format: int64
after_completionoptional	object
after_completion[type]required	string	enum: message, redirect
after_completion[message]optional	string	maxLength: 500
after_completion[url]optional	string	Required for `redirect`.format: uri
metadataoptional	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.
expandoptional	string[]	enum: card · maxItems: 10

Request

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"}}'

Response

{
  "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
}

Error responses:400401403404409429500

GET/v1/payment_links/{id}Secret key

Retrieve a payment link

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`plink_…`).
expand[]optional	query	string[]	Expand references: `card`.enum: card · maxItems: 10
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403404429500

POST/v1/payment_links/{id}Secret key

Update a payment link

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`plink_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
titleoptional	string	minLength: 1 · maxLength: 120
descriptionoptional	string	maxLength: 1000
amountoptional	object \| object
collectoptional	object
collect[name]optional	string	enum: off, optional, required
collect[phone]optional	string	enum: off, optional, required
collect[email]optional	string	enum: off, optional, required
cardoptional	string \| null	Destination override (a card or an account); null or "" removes it.
max_usesoptional	integer \| null	Completed payments after which the link stops; null or "" removes the limit.min: 1 · max: 1000000
expires_atoptional	integer \| null	A future unix second; null or "" removes the expiry.format: int64
after_completionoptional	object
after_completion[type]required	string	enum: message, redirect
after_completion[message]optional	string	maxLength: 500
after_completion[url]optional	string	Required for `redirect`.format: uri
metadataoptional	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.
activeoptional	boolean	`false` archives the link.
expandoptional	string[]	enum: card · maxItems: 10

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

Customers

GET/v1/customersSecret key

List customers

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
phoneoptional	query	string	Any typed form.
emailoptional	query	string	format: email
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

POST/v1/customersSecret key

Create a customer

Parameters

Parameters
Name	In	Type	Description
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
nameoptional	string	maxLength: 120
phoneoptional	string	Any typed form; normalized to `09xxxxxxxxx`; unique per mode.
emailoptional	string	format: email
metadataoptional	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.
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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]"}'

Response

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

Error responses:400401403404409429500

GET/v1/customers/{id}Secret key

Retrieve a customer

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`cus_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

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

Error responses:400401403404429500

POST/v1/customers/{id}Secret key

Update a customer

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`cus_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
nameoptional	string	maxLength: 120
phoneoptional	string	Any typed form; normalized to `09xxxxxxxxx`; unique per mode.
emailoptional	string	format: email
metadataoptional	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.
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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

Response

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

Error responses:400401403404409429500

DELETE/v1/customers/{id}Secret key

Delete a customer

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`cus_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

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

Error responses:400401403404429500

Events

GET/v1/eventsSecret key

List events

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
typeoptional	query	string	An event type, or every type of one object: `payment.*`.
types[]optional	query	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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"
      }
    }
  ]
}

Error responses:400401403429500

GET/v1/events/{id}Secret key

Retrieve an event

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`evt_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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"
  }
}

Error responses:400401403404429500

Webhook endpoints

GET/v1/webhook_endpointsSecret key

List webhook endpoints

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

POST/v1/webhook_endpointsSecret key

Create a webhook endpoint

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

Parameters

Parameters
Name	In	Type	Description
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
urlrequired	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_eventsrequired	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,
descriptionoptional	string	maxLength: 500
api_versionoptional	string	enum: 2026-10-01
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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"}'

Response

{
  "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"
}

Error responses:400401403404409429500

GET/v1/webhook_endpoints/{id}Secret key

Retrieve a webhook endpoint

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`we_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403404429500

POST/v1/webhook_endpoints/{id}Secret key

Update a webhook endpoint

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`we_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
urloptional	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_eventsoptional	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,
descriptionoptional	string	"" clears it.maxLength: 500
statusoptional	string	`enabled` also starts the failure count afresh.enum: enabled, disabled
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

DELETE/v1/webhook_endpoints/{id}Secret key

Delete a webhook endpoint

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`we_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

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

Error responses:400401403404429500

Cards

GET/v1/cardsSecret key

List cards

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
statusoptional	query	string	enum: active, disabled, archived
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

GET/v1/cards/{id}Secret key

Retrieve a card

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`card_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403404429500

Devices

GET/v1/devicesSecret key

List devices

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
healthoptional	query	string	enum: online, stale, offline
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

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

Error responses:400401403429500

GET/v1/devices/{id}Secret key

Retrieve a device

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`dev_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

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

Error responses:400401403404429500

Receipts

POST/v1/payments/{id}/receiptsSecret key

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.

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`pay_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
channeloptional	string	How the money went; defaults to `card` when the payment takes cards.enum: card, pol, paya, satna, internal
referenceoptional	string	The tracking number on the bank receipt: 4-40 letters and digits (Persian digits accepted).maxLength: 80
amountoptional	integer	What the customer says they sent; omit for the expected amount. Integer rial.min: 1 · max: 20000000000
paid_atoptional	integer	When the customer says they paid.format: int64
payer_nameoptional	string	minLength: 1 · maxLength: 120
payer_last4optional	string	The last 4 digits of the paying card.
replaceoptional	boolean	Withdraw the pending receipts submitted earlier through the API for this payment (a corrected receipt, not a second transfer).
expandoptional	any[]	Nothing to expand.maxItems: 0
filesoptional	file[]	Up to 3 files of at most 10 MB: JPEG, PNG, WebP, HEIC or PDF, told by their bytes.maxItems: 3

Request

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]

Response

{
  "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
}

Error responses:400401403404409429500

GET/v1/receiptsSecret key

List receipts

Parameters

Parameters
Name	In	Type	Description
limitoptional	query	integer	Page size, 1-100.min: 1 · max: 100 · default: 10
starting_afteroptional	query	string	Cursor: the id of the last object of the previous page (toward older objects).
ending_beforeoptional	query	string	Cursor: the id of the first object of the previous page (toward newer objects).
createdoptional	query	integer \| object	A unix second, or a range: `created[gte]=…&created[lt]=…`.
statusoptional	query	string	`pending` is the review queue.enum: pending, approved, rejected, withdrawn
channeloptional	query	string	enum: card, pol, paya, satna, internal
paymentoptional	query	string	Object id (`pay_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
    }
  ]
}

Error responses:400401403429500

GET/v1/receipts/{id}Secret key

Retrieve a receipt

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`rcp_…`).
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403404429500

POST/v1/receipts/{id}/approveSecret key

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.

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`rcp_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
amountoptional	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
depositoptional	string	A bank deposit of this transfer on the payment's destination, unmatched or on this payment (its amount is approved).
overpayoptional	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`).
noteoptional	string	Internal; never shown to the customer.minLength: 1 · maxLength: 500
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

POST/v1/receipts/{id}/rejectSecret key

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.

Parameters

Parameters
Name	In	Type	Description
idrequired	path	string	Object id (`rcp_…`).
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
reasonrequired	string	Shown to the customer on the checkout.enum: not_received, amount_mismatch, unreadable, duplicate, other
noteoptional	string	Internal; never shown to the customer.minLength: 1 · maxLength: 500
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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

Response

{
  "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
}

Error responses:400401403404409429500

Test helpers

POST/v1/test_helpers/depositsSecret key

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).

Parameters

Parameters
Name	In	Type	Description
Idempotency-Keyoptional	header	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-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
cardoptional	string	Defaults to the payment's destination card.
amountoptional	integer	Transfer amount. Integer rial.min: 1
payer_last4optional	string
paymentoptional	string	Shortcut: a transfer of exactly its expected amount.
channeloptional	string	How the simulated money came; omit for unknown.enum: card, pol, paya, satna, internal
expandoptional	any[]	Nothing to expand.maxItems: 0

Request

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"}'

Response

{
  "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
}

Error responses:400401403404409429500

Account

GET/v1/accountSecret key

Retrieve the account of the key

Parameters

Parameters
Name	In	Type	Description
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request

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

Response

{
  "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
}

Error responses:400401403429500

Connect

POST/v1/connect/exchangeNo key

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.

Parameters

Parameters
Name	In	Type	Description
Bezanbecard-Versionoptional	header	string	Pin the API version; defaults to the version of the key.enum: 2026-10-01

Request body

Request body
Name	Type	Description
coderequired	string	maxLength: 128

Request

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

Response

{
  "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
  }
}

Error responses:400403429500