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

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

Platform горим

Platform горимыг Byl-ийн баг танай багт асаана. Асаагүй багт эдгээр endpoint 404 буцна. Хүсэлтээ [email protected] руу илгээнэ үү.

Багийн токен

Эдгээр 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).

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

Харилцагч үүссэн хэвээр, харин verification нь null ирнэ. Түр хүлээгээд холбоос илгээх хүсэлтээр дахин эхлүүлнэ.

Жишээ хүсэлт

shell

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

Жишээ гаралт

json

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

shell

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	Төслийн холбоо барих и-мэйл.
`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.

shell

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

json

{
  "data": {
    "id": 57,
    "name": "Shop 42",
    "mode": "Test",
    "business_id": 118,
    "email": "[email protected]",
    "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-аас аль харилцагчийнх нь харагдана.

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

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

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

Багийн токен ​

Client объект ​

Onboarding-ийн төлөв ​

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

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

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

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

Project объект ​

Төсөл нээх ​

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

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

Горим солих ​

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

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

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

Багийн токен

Client объект

Onboarding-ийн төлөв

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

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

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

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

Project объект

Төсөл нээх

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

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

Горим солих

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

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