Platform — Харилцагч ба төсөл

Харилцагчдынхаа төлөө төсөл нээдэг platform баг харилцагчаа бүртгэх, баталгаажуулах холбоосыг нь өөрийн системд үзүүлэх, төсөл нээж Live болгох, орлогын дансыг нь тохируулах ажлаа энэ API-гаар автоматжуулна. Удирдлагын булангийн Харилцагчид цэсэнд хийдэг бүх зүйл эндээс хийгдэнэ.

Багийн токен

Эдгээр endpoint төслийн токеноор биш, багийн токеноор ажиллана: Account-ын API токэн цэсээс (багийн эзэнд харагдана) үүсгэнэ. Багийн токен багийн бүх төслийн — өөрийн болон харилцагчдын — төслийн endpoint-уудад ч хүчинтэй тул харилцагчийн төсөлд checkout, нэхэмжлэх үүсгэхэд нэг л токен хангалттай. Дэлгэрэнгүйг API токен хуудаснаас.

Authorization: Bearer <багийн токен>

Төслийн эсвэл хуучин токеноор дуудвал 403 буцна.

Client объект

Талбар	Төрөл	Тайлбар
`id`	Number	Харилцагчийн (бизнесийн) ID. Webhook payload-ын `business_id` энэ.
`client_reference_id`	String	Таны систем дэх харилцагчийн ID.
`name`	String	Бизнесийн нэр. Баталгаажсаны дараа TrustAPI-аас ирнэ; түүнээс өмнө `null`.
`type`	String	Бизнесийн төрөл (`person`, `company` …). Баталгаажсаны дараа.
`contact_email`	String	Баталгаажуулах холбоос очих хаяг.
`phone`	String	Утас. Баталгаажсаны дараа.
`status`	String	Onboarding-ийн төлөв, доорх хүснэгт.
`is_verified`	Boolean	Бүх алхам дууссан: төслөө Live болгож болно.
`verified_at`	Date	Баталгаажсан огноо.
`verification_status`	String	TrustAPI-ийн одоогийн оролдлогын төлөв (`pending`, `submitted`, `under_review`, `verified`, `rejected`, `expired`).
`steps`	Array	`trustapi`, `qpay`, `bank` алхам бүрийн `status` (`pending`, `in_progress`, `done`, `error`) ба `error`.
`qpay_merchant_id`	String	Харилцагчид үүссэн QPay мерчантын ID.
`bank_accounts`	Array	Идэвхтэй банкны дансууд (`id`, `bank_code`, `bank_name`, `account_number`, `account_name`).
`projects`	Array	Харилцагчид нээсэн төслүүд (`id`, `name`, `mode`). Зөвхөн лавлах хүсэлтэд.
`verification`	Object	Дөнгөж эхлүүлсэн баталгаажуулалтын `url`, `expires_at`, `emailed`. Зөвхөн үүсгэх ба холбоос илгээх хүсэлтийн хариунд.
`created_at`	Date	Бүртгэсэн огноо.

Onboarding-ийн төлөв

`status`	Утга
`not_started`	Харилцагч холбоосоо нээж мэдээллээ өгөөгүй.
`in_review`	Мэдээллээ өгч байгаа эсвэл өгсөн, шийдвэр хүлээж байна.
`incomplete`	TrustAPI баталгаажуулсан, QPay мерчант ба данс автоматаар үүсч байна.
`verified`	Бүх алхам дууссан.
`rejected`	Татгалзсан. Холбоосыг дахин илгээвэл шинэ оролдлого эхэлнэ.
`expired`	Холбоосын хугацаа дууссан. Дахин илгээнэ.

Харилцагч бүртгэх

POST /v1/clients

Параметер	Төрөл	Заавал эсэх	Тайлбар
`email`	String	true	Харилцагчийн и-мэйл. Баталгаажуулах холбоос энд очно.
`client_reference_id`	String	false	Таны систем дэх харилцагчийн ID. 48 тэмдэгт хүртэл, багт давтагдахгүй.

Харилцагч үүсч, TrustAPI дээр баталгаажуулалт эхэлж, холбоос нь и-мэйлээр очно. Хариуны verification.url нь тэр холбоос: та өөрийн onboarding хуудсандаа шууд үзүүлж болно. Нэг и-мэйл, нэг client_reference_id-тай харилцагч давхар үүсэхгүй (422).

Жишээ хүсэлт

BYL_TEAM_TOKEN="таны багийн токен"

curl -X POST https://byl.mn/api/v1/clients \
    -H "Authorization: Bearer $BYL_TEAM_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "email": "[email protected]",
          "client_reference_id": "shop_42"
      }'

Жишээ гаралт

{
  "data": {
    "id": 118,
    "client_reference_id": "shop_42",
    "name": null,
    "type": null,
    "contact_email": "[email protected]",
    "phone": null,
    "status": "in_review",
    "is_verified": false,
    "verified_at": null,
    "verification_status": "pending",
    "steps": [
      { "key": "trustapi", "status": "in_progress", "error": null },
      { "key": "qpay", "status": "pending", "error": null },
      { "key": "bank", "status": "pending", "error": null }
    ],
    "qpay_merchant_id": null,
    "bank_accounts": [],
    "verification": {
      "url": "https://trustapi.dotly.mn/verify/tok_8f2a…",
      "expires_at": "2026-11-04T09:00:00+08:00",
      "emailed": true
    },
    "created_at": "2026-10-28T09:00:00.000000Z",
    "updated_at": "2026-10-28T09:00:00.000000Z"
  }
}

Харилцагч лавлах

GET /v1/clients/:client_id
GET /v1/clients/by-client-reference-id/:client_reference_id

Хариунд харилцагчийн төслүүд (projects) хамт ирнэ. Лавлах бүрд TrustAPI-ийн төлөвийг шалгадаг тул webhook алдагдсан ч төлөв зөв гарна. Өөр багийн харилцагч 404.

curl https://byl.mn/api/v1/clients/by-client-reference-id/shop_42 \
    -H "Authorization: Bearer $BYL_TEAM_TOKEN" \
    -H 'Accept: application/json'

Харилцагчдын жагсаалт

GET /v1/clients

Параметер	Төрөл	Тайлбар
`status`	String	Onboarding-ийн төлвөөр шүүх.
`per_page`	Number	Нэг хуудсанд (өгөгдмөл 25, дээд тал нь 100).

Шинээс хуучин руу, хуудаслалттай (meta.total, links.next).

Баталгаажуулах холбоос илгээх

POST /v1/clients/:client_id/verification-link

Харилцагч холбоосоо алдсан, хугацаа нь дууссан эсвэл татгалзагдсан үед дахин (шинээр) холбоос үүсгэж и-мэйлээр илгээнэ; хариунд verification.url ирнэ. Дараах тохиолдолд 409:

`error`	Утга
`already_verified`	Харилцагч аль хэдийн баталгаажсан.
`in_review`	Мэдээллээ өгсөн, шийдвэр хүлээж байна — бөглөх зүйл үлдээгүй.
`onboarding_in_progress`	TrustAPI баталгаажуулсан, үлдсэн алхмууд автоматаар дуусч байна.

Баталгаажуулалтын үйлчилгээ хариу өгөхгүй бол 503 verification_unavailable.

Project объект

Талбар	Төрөл	Тайлбар
`id`	Number	Төслийн ID — төслийн endpoint-уудад хэрэглэнэ.
`name`	String	Нэр.
`mode`	String	`Test` эсвэл `Live`.
`business_id`	Number	Аль харилцагчийн төсөл болох. Багийн өөрийн төсөлд `null`.
`email`	String	Мерчантад мэдэгдэл хүлээн авах и-мэйл (банкны шилжүүлгийн мэдэгдэл).
`support_email`	String	Харилцагчид харагдах и-мэйл, эсвэл `null` (тэгвэл `email` харагдана).
`support_phone`	String	Харилцагчид харагдах утас, эсвэл `null`.
`qpay_merchant_id`	String	Төсөлд холбогдсон QPay мерчант. Харилцагч баталгаажмагц автоматаар холбогдоно.
`payout_bank_account`	Object	Орлого хүлээн авах данс (`id`, `bank_code`, `bank_name`, `account_number`, `account_name`, `is_active`) эсвэл `null`.
`created_at`	Date	Үүссэн огноо.

Төсөл нээх

POST /v1/projects

Параметер	Төрөл	Заавал эсэх	Тайлбар
`name`	String	true	Төслийн нэр. 255 тэмдэгт хүртэл.
`business_id`	Number	false	Харилцагчийн `id`. Өгөхгүй бол багийн өөрийн бизнесийн төсөл.

Харилцагч баталгаажсан бол түүний QPay мерчант шинэ төсөлд шууд холбогдоно; баталгаажаагүй бол баталгаажмагц холбогдоно. Багцгүй багт нэг л төсөл байж болно (422 subscription_required); багцын хязгаарт хүрвэл 422 project_limit_reached.

curl -X POST https://byl.mn/api/v1/projects \
    -H "Authorization: Bearer $BYL_TEAM_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "name": "Shop 42", "business_id": 118 }'

{
  "data": {
    "id": 57,
    "name": "Shop 42",
    "mode": "Test",
    "business_id": 118,
    "email": "[email protected]",
    "support_email": null,
    "support_phone": null,
    "qpay_merchant_id": null,
    "payout_bank_account": null,
    "created_at": "2026-10-28T09:05:00.000000Z",
    "updated_at": "2026-10-28T09:05:00.000000Z"
  }
}

Төсөл лавлах, жагсаах

GET /v1/projects/:project_id
GET /v1/projects

Жагсаалт багийн бүх төслийг (өөрийн ба харилцагчдын) шинээс хуучин руу буцаана; business_id параметрээр нэг харилцагчийнхыг шүүнэ. per_page жагсаалтынхтай ижил.

Орлого хүлээн авах данс

GET /v1/projects/:project_id/bank-accounts
PUT /v1/projects/:project_id/bank-account

GET нь төслийн бизнесийн (харилцагчийн) идэвхтэй дансуудыг буцаана — харилцагч баталгаажихад TrustAPI-д өгсөн данс нь энд автоматаар орсон байна. PUT нь bank_account_id-аар тэдгээрийн нэгийг төслийн орлогын данс болгоно; өөр бизнесийн данс 422. Live горимд шилжихийн өмнө данс тохируулсан байх ёстой.

Горим солих

PUT /v1/projects/:project_id/mode

Параметер	Төрөл	Заавал эсэх	Тайлбар
`mode`	String	true	`Test` эсвэл `Live`.

Live болгоход бизнес баталгаажсан, багт идэвхтэй багц, төсөлд орлогын данс байх ёстой; аль нь дутууг 422-ын error хэлнэ: business_not_verified, subscription_required, payout_account_required. Одоогийн горимыг дахин өгвөл өөрчлөлтгүй 200.

Харилцагчийн төсөлд ажиллах

Төсөл нээсний дараа тэр төслийн checkout, нэхэмжлэх, customer endpoint-уудыг ижил багийн токеноор, хариунд ирсэн id-г :project_id-д тавьж дуудна. Төслүүдийн event-ийг нэг газар авахын тулд багийн webhook endpoint бүртгэнэ: payload-ын business_id-аас аль харилцагчийнх нь харагдана.

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

Харилцагчийн төслийн банкны шилжүүлэг харилцагчийн дансанд ордог тул хуулгыг зөвхөн харилцагч харна. Худалдан авагч «Шилжүүлсэн» дармагц Byl харилцагчийн холбоо барих имэйл рүү нэвтрэлтгүй, хугацаатай холбоос илгээнэ: харилцагч тэндээс «Мөнгө ирсэн» / «Ирээгүй» гэж хариулна. Багийн эзэнд мэдээллийн хуулбар очно (төсөлд Telegram/Discord суваг холбосон бол хуулбарын оронд суваг руу).

Өөрийн UI-д хийх бол багийн webhook-ийн payment.awaiting_verification event-ийг харилцагчдаа үзүүлж, хариуг нь Bank transfers API-аар буцаана. Аль замаар түрүүлж шийдсэн нь хүчинтэй.

Дараагийн алхам

API токен — багийн токен үүсгэх
Webhook — багийн endpoint, business_id
Checkout — харилцагчийн төсөлд төлбөр авах
Bank transfers — банкны шилжүүлэг API-аар баталгаажуулах