Checkout — Худалдан авалт

Checkout нь бүтээгдэхүүн, тоо хэмжээ, хөнгөлөлт бүхий бүтэн худалдан авалтыг зохицуулах Byl-ийн хостлогдсон төлбөрийн хуудас юм.

Харилцагч таны апп эсвэл веб дээр “Худалдан авах” дарахад та checkout үүсгээд хариунд ирэх url руу чиглүүлнэ. Түүнээс хойш төлбөрийн хэлбэр сонгох, хөнгөлөлтийн код хэрэглэх, хүргэлтийн хаяг, утасны дугаар авах, баримтыг и-мэйлээр илгээх бүх зүйлийг Byl зохицуулна.

Checkout төлөгдмөгц webhook-оор checkout.completed event илгээгдэнэ.

Нэхэмжлэх vs Checkout

Зөвхөн тодорхой дүн төлүүлэх бол нэхэмжлэх хялбар. Бүтээгдэхүүн, тоо хэмжээ, хөнгөлөлтийн код, хүргэлтийн хаяг зэрэг шаардлагатай бол checkout.

Ажиллах урсгал

Харилцагч "Худалдан авах" дарна
  │
  ▼
Таны сервер POST /checkouts дуудна
  │ хариунд id, url ирнэ
  ▼
Харилцагчийг url руу чиглүүлнэ
  │ Byl-ийн хуудсан дээр төлбөр төлнө
  ▼
success_url руу буцна  +  танд checkout.completed webhook ирнэ

Багцыг эцэслэх (бараа хүргэх, эрх нээх) логикоо success_url дээр бус, webhook дээр бичихийг зөвлөж байна — харилцагч буцах хуудсыг хааж болзошгүй.

Төлөвүүд

Төлөв	Тайлбар
open	Төлбөр хүлээж байна.
pending	Худалдан авагч банкны шилжүүлэг хийснээ мэдэгдсэн; мерчант баталгаажуулахыг хүлээж байна. Checkout түгжигдсэн.
complete	Төлөгдсөн. checkout.completed webhook илгээгдсэн байна.
expired	Хугацаа дууссан. Дахин төлөх боломжгүй.

Checkout өгөгдмөлөөр 2 сарын дараа хүчингүй болно (expires_at). Багц солих checkout нь онцгой тохиолдол — 24 цагийн дараа хүчингүй болно (шалтгааныг үзэх).

Checkout объект

Талбар	Төрөл	Тайлбар
id	Number	Checkout ID.
url	String	Харилцагчид үзүүлэх төлбөрийн хуудас.
status	String	Төлөв: open, pending, complete, expired.
mode	String	Худалдан авалтын горим: payment, subscription.
amount_subtotal	Number	Бүтээгдэхүүнүүдийн нийт дүн (хямдрал хасахаас өмнө).
amount_total	Number	Харилцагч төлөх нийт дүн (хямдрал хассаны дараа).
client_reference_id	String	Таны систем дэх захиалгын дугаар.
customer_id	Number	Холбогдсон харилцагчийн ID.
customer_email	String	Харилцагчийн и-мэйл хаяг.
is_guest	Boolean	Зочин харилцагч эсэх (харилцагч холбогдоогүй).
allow_promotion_codes	Boolean	Хөнгөлөлтийн кодын талбар идэвхтэй эсэх.
custom_fields	Array	Нэмэлт талбарууд худалдан авагчийн хариулттай (value).
expires_at	Date	Хүчинтэй байх эцсийн хугацаа.
created_at	Date	Анх үүссэн огноо.
updated_at	Date	Өөрчлөлт орсон огноо.

Checkout үүсгэх

POST /v1/projects/:project_id/checkouts

Параметер	Төрөл	Заавал эсэх	Тайлбар
items[]	Array	true	Бүтээгдэхүүний жагсаалт. Хамгийн багадаа 1.
success_url	String	false	Төлбөр амжилттай төлөгдсөний дараа буцах хаяг.
cancel_url	String	false	Худалдан авалт цуцлах үед буцах хаяг.
customer_id	Number	false	Харилцагчийн ID. Давтагдах үнэтэй checkout-д заавал.
customer_email	String	false	Харилцагчийн и-мэйл хаяг. Байвал харилцагч автоматаар үүсч холбогдоно.
client_reference_id	String	false	Таны систем дэх дугаар. 48 тэмдэгт хүртэл.
phone_number_collection	Boolean	false	Утасны дугаар авах талбар идэвхжүүлэх.
email_collection	Boolean	false	И-мэйл авах талбар. Өгөгдмөл true — false бол төлбөрийн хуудсанд и-мэйл шаардахгүй. И-мэйлгүй бол баримт илгээгдэхгүй.
delivery_address_collection	Boolean	false	Хүргэлтийн хаяг авах талбар идэвхжүүлэх.
allow_promotion_codes	Boolean	false	Хөнгөлөлтийн код оруулах талбар идэвхжүүлэх.
custom_fields[]	Array	false	Худалдан авагчаас асуух нэмэлт талбарууд. 3 хүртэл.
discounts[]	Array	false	Шууд хямдрал.
subscription_id	Number	false	Сунгах/солих багцын ID.

Хариунд зөвхөн id болон url буцна:

{
  "data": {
    "id": 13338,
    "url": "https://byl.mn/h/checkout/13338/Yi7smBuk"
  }
}

Бүтээгдэхүүн заах

items[] дотор бүтээгдэхүүн заах гурван арга байна. Нэг item-д зөвхөн нэгийг л хэрэглэнэ.

Арга	Хэзээ хэрэглэх
price	Хамгийн зөвлөмжтэй. Byl-д бүртгэлтэй үнийг санахад хялбар нэрээр (lookup key) заана.
price_id	Byl-д бүртгэлтэй үнийг ID-гаар заана. price-тай ижил боловч ID санах шаардлагатай.
price_data	Byl-д бүртгэлгүй бүтээгдэхүүний үнэ, нэрийг хүсэлт дотроо шууд дамжуулна (динамик үнэ, сагс гэх мэт).

Анхааруулга

Бүтээгдэхүүний хямдралтай хөнгөлөлтийн код болон багц (subscription) хэрэглэхийн тулд бүтээгдэхүүн Byl-д бүртгэлтэй байх шаардлагатай — price эсвэл price_id ашиглана. price_data-д эдгээр боломж ажиллахгүй.

price (lookup key)

Lookup key нь тухайн үнэд өгсөн, төсөл дотроо давтагдашгүй нэр юм (жишээ нь starter_monthly). Удирдлагын буланд бүтээгдэхүүний засах хуудасны үнэ хэсэгт тохируулна.

Параметер	Төрөл	Заавал эсэх	Тайлбар
items[0][price]	String	true	Үнийн lookup key. Жш: starter_monthly.
items[0][quantity]	Number	true	Тоо хэмжээ. Хамгийн багадаа 1.

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

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "success_url": "https://example.mn/purchase/success",
          "items": [
              { "price": "starter_monthly", "quantity": 1 }
          ]
      }'

Тухайн төсөлд байхгүй lookup key дамжуулбал валидацын алдаа буцна.

price_id

Byl-д бүртгэлтэй үнийн ID. Удирдлагын буланд бүтээгдэхүүний дэлгэрэнгүй хуудсанд үнэ тус бүрийн ID харагдана.

Параметер	Төрөл	Заавал эсэх	Тайлбар
items[0][price_id]	Number	true	Byl-д бүртгэлтэй үнийн ID.
items[0][quantity]	Number	true	Тоо хэмжээ.

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "success_url": "https://example.mn/purchase/success",
          "items": [
              { "price_id": 3, "quantity": 1 }
          ]
      }'

price_data

Byl-д бүртгэлгүй бүтээгдэхүүнийг хүсэлт дотроо тодорхойлно. Динамик үнэ (жишээ нь сагсны агуулга, хэмжээгээр тооцох үйлчилгээ) хэрэгтэй үед тохиромжтой.

Параметер	Төрөл	Заавал эсэх	Тайлбар
items[0][price_data][unit_amount]	Number	true	Нэгж үнэ.
items[0][price_data][product_data][name]	String	true	Бүтээгдэхүүний нэр. 255 тэмдэгт хүртэл.
items[0][price_data][product_data][client_reference_id]	String	false	Таны систем дэх бүтээгдэхүүний ID.
items[0][quantity]	Number	true	Тоо хэмжээ.

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "success_url": "https://example.mn/purchase/success",
          "items": [
              {
                  "price_data": {
                      "unit_amount": 1000,
                      "product_data": { "name": "Product 1" }
                  },
                  "quantity": 1
              }
          ]
      }'

Тоо хэмжээг харилцагчид засах эрх

Дээрх гурван аргад ижилхэн ажиллах нэмэлт тохиргоо. Идэвхжүүлбэл харилцагч checkout хуудсан дээр тоо хэмжээгээ өөрөө өөрчилж болно.

Параметер	Төрөл	Заавал эсэх	Тайлбар
items[0][adjustable_quantity][enabled]	Boolean	true	Засах боломжийг идэвхжүүлэх.
items[0][adjustable_quantity][min]	Number	false	Оруулж болох хамгийн бага тоо.
items[0][adjustable_quantity][max]	Number	false	Оруулж болох хамгийн их тоо.

{
  "items": [
    {
      "price": "tshirt",
      "quantity": 1,
      "adjustable_quantity": { "enabled": true, "min": 1, "max": 10 }
    }
  ]
}

Хямдрал

discounts[]-ээр нийт дүнгээс тодорхой хэмжээний хямдрал шууд хасна. Хямдралын шалтгааныг та өөрөө шийдэж, тайлбарыг харилцагчид харагдахаар бичнэ.

Параметер	Төрөл	Заавал эсэх	Тайлбар
discounts[0][amount]	Number	true	Хямдралын дүн.
discounts[0][description]	String	true	Харилцагчид харагдах тайлбар. 255 тэмдэгт хүртэл.

Хямдралын нийт дүн бүтээгдэхүүнүүдийн нийт дүнгээс их байж болохгүй.

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "items": [
              { "price_id": 3, "quantity": 1 }
          ],
          "discounts": [
              { "amount": 5400, "description": "Хямдрал" }
          ]
      }'

Энэ жишээнд 5400 төгрөгийн хямдрал “Хямдрал” тайлбартайгаар харагдана:

Хямдрал vs Хөнгөлөлтийн код

discounts[] нь та тооцоолсон хямдралыг шууд хасна. Хөнгөлөлтийн код нь харилцагч өөрөө код оруулж хөнгөлөлт авах боломж. Хоёуланг зэрэг хэрэглэж болно.

Нэмэлт талбар

custom_fields[]-ээр төлбөрийн хуудсанд өөрийн асуулт нэмнэ — байгууллагын нэр, НӨАТ дугаар, суудлын төрөл гэх мэт. Нэг checkout-д 3 хүртэл талбар байж болно; худалдан авагч имэйл, утасны дараа бөглөнө.

Параметер	Төрөл	Заавал эсэх	Тайлбар
custom_fields[0][label]	String	true	Худалдан авагчид харагдах асуулт. 100 тэмдэгт хүртэл.
custom_fields[0][type]	String	true	text (255 тэмдэгт хүртэл), numeric (зөвхөн цифр), dropdown.
custom_fields[0][key]	String	false	Хариултыг таних түлхүүр: a-z, 0-9, _, 50 тэмдэгт хүртэл. Өгөхгүй бол label-аас үүснэ.
custom_fields[0][optional]	Boolean	false	true бол хоосон орхиж болно. Өгөгдмөл false.
custom_fields[0][dropdown][options][]	Array	dropdown-д	Сонголтууд, 1–50. Мөр бүр label (заавал) ба value (өгөхгүй бол label-аас үүснэ).

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "items": [
              { "price_id": 3, "quantity": 1 }
          ],
          "custom_fields": [
              { "key": "company", "label": "Байгууллагын нэр", "type": "text" },
              { "key": "vat", "label": "НӨАТ дугаар", "type": "numeric", "optional": true },
              {
                  "key": "seat",
                  "label": "Суудал",
                  "type": "dropdown",
                  "dropdown": { "options": [{ "label": "VIP" }, { "label": "Ердийн" }] }
              }
          ]
      }'

Хариултууд checkout лавлах хариу болон checkout.completed webhook-ийн custom_fields массивт талбар бүрийн value-д ирнэ. dropdown-ийн value нь сонголтын value (жишээ нь «VIP» → vip); бөглөгдөөгүй талбарын value нь null.

Хөнгөлөлтийн код

allow_promotion_codes: true дамжуулбал checkout хуудсан дээр хөнгөлөлтийн код оруулах талбар гарна. Харилцагч кодоо оруулахад хөнгөлөлт автоматаар тооцогдоно.

Хөнгөлөлтийн кодыг удирдлагын буланд үүсгэнэ. Хоёр төрөлтэй бөгөөд checkout-д тавих шаардлага нь өөр:

Кодын төрөл	Бүтээгдэхүүн заах арга
Багцын нийт дүнгээс хөнгөлөх	Ямар ч арга — price, price_id, price_data бүгд ажиллана.
Бүтээгдэхүүний хямдрал	Бүх item-д price эсвэл price_id заавал.

Бүтээгдэхүүний хямдралтай код нь Byl-д бүртгэлтэй тодорхой бүтээгдэхүүнтэй холбогдож ажилладаг. price_data-гаар дамжуулсан бүтээгдэхүүн системд бүртгэлгүй тул систем түүнд ямар хөнгөлөлт хамаарахыг тодорхойлж чадахгүй.

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "success_url": "https://example.mn/purchase/success",
          "allow_promotion_codes": true,
          "items": [
              { "price_id": 3, "quantity": 1 },
              { "price_id": 5, "quantity": 2 }
          ]
      }'

Дэлгэрэнгүйг Хөнгөлөлтийн код хуудаснаас уншина уу.

Давтагдах төлбөр (subscription)

Сар/жилийн мөчлөгтэй давтагдах (recurring) үнэтэй checkout төлөгдөхөд багц (subscription) автоматаар үүснэ. Энэ тохиолдолд хоёр нэмэлт шаардлага биелэх ёстой:

• customer_id заавал — багц тодорхой харилцагчид бүртгэгдэнэ.
• Ганц item — давтагдах үнэтэй checkout-д өөр item нэмэх боломжгүй.

Сунгалт, багц солилт, туршилтын хугацаа зэргийг Subscriptions хуудаснаас уншина уу.

Checkout лавлах

GET /v1/projects/:project_id/checkouts/:checkout_id

Зөвлөгөө

Төлөгдсөн эсэхийг мэдэхийн тулд энэ endpoint-ыг тасралтгүй дуудах (polling) шаардлагагүй — webhook тохируулбал checkout.completed event тэр даруй танд ирнэ.

Жишээ хүсэлт

curl -X GET https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts/13338 \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Жишээ гаралт

{
  "data": {
    "id": 13338,
    "url": "https://byl.mn/h/checkout/13338/Yi7smBuk",
    "client_reference_id": null,
    "mode": "payment",
    "status": "open",
    "expires_at": "2026-12-25T16:00:00.000000Z",
    "amount_subtotal": 1000,
    "amount_total": 1000,
    "customer_id": null,
    "customer_email": null,
    "is_guest": true,
    "allow_promotion_codes": false,
    "created_at": "2026-10-25T10:27:49.000000Z",
    "updated_at": "2026-10-25T10:27:49.000000Z"
  }
}

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

• Webhook — checkout.completed event-ийг өөрийн системд хүлээн авах
• Хөнгөлөлтийн код — код үүсгэж, хөнгөлөлт тохируулах
• Subscriptions — давтагдах төлбөр