clinicpro/docs/api/payment-method.md

Payment Methods API

Prefix: /api/v1/my/payment-methods

Per-clinic payment methods managed from the settings screen (/admin/my-financial, tab "مدیریت پرداخت"). Two resources: bank accounts and POS (card reader) devices.

دسترسی منشی: روش‌های پرداخت زیرمجموعهٔ منبع payments هستند. برای ROLE_SECRETARY (SecretaryAccessChecker): GET→payments.view, POST→payments.create, PUT/PATCH→payments.update؛ نبودِ مجوز یا رابطهٔ فعال → 403. جزئیات: secretary.md. Records are stored so a patient invoice can later reference which account/device a service payment was made to.

All endpoints are scoped to the acting user — a clinic never sees another's records.

Permission: authenticated user with one of ROLE_CLINIC, ROLE_DOCTOR, ROLE_SECRETARY, ROLE_ADMIN (otherwise 403 ERR_FORBIDDEN_001).

---

Bank accounts

GET /api/v1/my/payment-methods/bank-accounts

List the current clinic's bank accounts (newest first).

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "b1e0...-...",
      "bank_name": "ملی",
      "card_number": "6037991234567890",
      "account_number": "0101234567890",
      "shaba_number": "IR820540102680020817909002",
      "is_active": true,
      "created_at": 1752566400
    }
  ]
}

Empty list returns "data": [].

---

POST /api/v1/my/payment-methods/bank-accounts

Create a bank account.

Body

Field	Type	Required	Description
bank_name	string	✅	Bank name
account_number	string	✅	Account number
card_number	string	❌	Card number
shaba_number	string	❌	IBAN / SHABA

Response 201

Single created record (same shape as list item).

Errors

• 422 ERR_VALIDATION_001 — bank_name or account_number missing (field set).

---

PUT /api/v1/my/payment-methods/bank-accounts/{uuid}

Update a bank account. Any subset of the create fields may be sent; only provided keys change. Empty bank_name/account_number → 422.

Response 200

Updated record.

Errors

• 404 ERR_NOT_FOUND_001 — uuid unknown or owned by another clinic.
• 422 ERR_VALIDATION_001 — provided bank_name/account_number empty.

---

PATCH /api/v1/my/payment-methods/bank-accounts/{uuid}/status

Toggle is_active (active ⇄ inactive). No body.

Response 200

Record with flipped is_active.

Errors

• 404 ERR_NOT_FOUND_001 — uuid unknown or not owned.

---

POS devices

GET /api/v1/my/payment-methods/pos

List the current clinic's card reader devices (newest first).

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "c2f1...-...",
      "bank_name": "ملت",
      "serial_number": "SN-98765",
      "terminal_number": "123456",
      "account_number": null,
      "is_active": true,
      "created_at": 1752566400
    }
  ]
}

---

POST /api/v1/my/payment-methods/pos

Create a POS device.

Body

Field	Type	Required	Description
bank_name	string	✅	Bank name
terminal_number	string	✅	Terminal number
serial_number	string	❌	Device serial number
account_number	string	❌	Linked account number

Response 201

Single created record.

Errors

• 422 ERR_VALIDATION_001 — bank_name or terminal_number missing (field set).

---

PUT /api/v1/my/payment-methods/pos/{uuid}

Update a POS device. Partial update; empty bank_name/terminal_number → 422.

Response 200

Updated record.

Errors

• 404 ERR_NOT_FOUND_001 — uuid unknown or not owned.
• 422 ERR_VALIDATION_001 — provided bank_name/terminal_number empty.

---

PATCH /api/v1/my/payment-methods/pos/{uuid}/status

Toggle is_active. No body.

Response 200

Record with flipped is_active.

Errors

• 404 ERR_NOT_FOUND_001 — uuid unknown or not owned.