Bank transfers — Банкны шилжүүлэг баталгаажуулах

Банкны шилжүүлэг-ээр төлсөн гүйлгээг дансны хуулгаа шалгаад баталгаажуулах буюу татгалзах үйлдлийг удирдлагын булангаас гадна API-аар хийж болно. Ялангуяа platform багт хэрэгтэй: харилцагчийн төслийн мөнгө харилцагчийн дансанд ордог тул payment.awaiting_verification event-ийг өөрийн системд харилцагчдаа үзүүлж, түүний хариуг энэ API-аар буцаана.

Төслийн токен ба багийн токен хоёулаа ажиллана; write эрх шаардлагатай (read токен 403). Шийдвэрийг токены эзэн хэрэглэгчийн нэрээр бүртгэнэ.

Урсгал

Худалдан авагч «Шилжүүлсэн» дарна
  │ payment.awaiting_verification webhook (data.object = төлбөр)
  ▼
Таны систем харилцагчид гүйлгээний код, дүнг үзүүлнэ
  │ харилцагч дансны хуулгаа шалгана
  ▼
POST .../bank-transfer/confirm  эсвэл  .../bank-transfer/reject
  │
  ▼
checkout.completed / invoice.paid  (баталгаажвал)

Харилцагчийн төсөлд Byl өөрөө ч харилцагчийн холбоо барих имэйл рүү нэвтрэлтгүй, хугацаатай холбоос илгээдэг: харилцагч тэндээс «Мөнгө ирсэн» / «Ирээгүй» гэж хариулж болно. API нь үүнийг өөрийн UI-д хийх хүсэлтэй багт зориулагдсан; аль замаар түрүүлж шийдсэн нь хүчинтэй, дараагийнх нь 409.

Payment объект

Хариу нь payment.awaiting_verification webhook-ийн data.object-тэй ижил хэлбэртэй: id, status (pending, paid, failed), amount, reference, bank_name, account_number, claimed_at, expires_at, payable (type, id, url, status, нэхэмжлэхэд number), customer_email, phone_number, is_test, created_at.

Баталгаажуулах

POST /v1/projects/:project_id/payments/:payment_id/bank-transfer/confirm

Параметер	Төрөл	Заавал эсэх	Тайлбар
`received_amount`	Number	true	Дансанд бодитоор ирсэн дүн.
`acknowledge_mismatch`	Boolean	false	Ирсэн дүн төлбөрийн дүнгээс зөрүүтэй ч төлөгдсөнд тооцох бол `true`.

Баталгаажмагц төлбөр paid болж, ердийн checkout.completed / invoice.paid webhook, мэдэгдэл, баримт илгээгдэнэ.

Жишээ хүсэлт

BYL_PROJECT_ID="таны төслийн ID"
BYL_TOKEN="таны API token"

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/payments/9d2f6c1e-1b1c-4a2e-9c7d-2d1f4a8b9e10/bank-transfer/confirm \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "received_amount": 45000 }'

Жишээ гаралт

{
  "data": {
    "id": "9d2f6c1e-1b1c-4a2e-9c7d-2d1f4a8b9e10",
    "project_id": 1,
    "status": "paid",
    "driver": "bank_transfer",
    "amount": 45000,
    "description": "Checkout - 231",
    "reference": "482913",
    "bank_name": "Хаан банк",
    "account_number": "5012345678",
    "claimed_at": "2026-08-27T09:30:00.000000Z",
    "expires_at": "2026-08-30T09:30:00.000000Z",
    "payable": {
      "type": "checkout",
      "id": 231,
      "url": "https://byl.mn/h/checkout/231/…",
      "status": "complete"
    },
    "customer_email": "[email protected]",
    "phone_number": "99112233",
    "is_test": false,
    "created_at": "2026-08-27T09:20:00.000000Z"
  }
}

Татгалзах

POST /v1/projects/:project_id/payments/:payment_id/bank-transfer/reject

Параметер	Төрөл	Заавал эсэх	Тайлбар
`reason`	String	true	Шалтгаан, 255 тэмдэгт хүртэл. Худалдан авагчид харагдана.

Төлбөр failed болж, checkout дахин нээгдэнэ — худалдан авагч шинэ кодтой дахин шилжүүлэх эсвэл өөр аргаар төлж болно. Имэйл нь мэдэгдэж байвал худалдан авагчид шалтгаантай имэйл очно.

Алдаа

Статус	`error`	Утга
`409`	`already_settled`	Шилжүүлэг аль хэдийн баталгаажсан, татгалзсан эсвэл хугацаа нь дууссан.
`422`	`not_bank_transfer`	Төлбөр банкны шилжүүлэг биш.
`422`	—	Validation: ирсэн дүн зөрүүтэй ба `acknowledge_mismatch` өгөөгүй бол `errors.acknowledge_mismatch`.
`403`	—	`read` эрхтэй токен, эсвэл өөр баг/төслийн токен.
`404`	—	Төлбөр энэ төсөлд байхгүй.