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`	Төлбөр хүлээж байна.
`complete`	Төлөгдсөн. `checkout.completed` webhook илгээгдсэн байна.
`expired`	Хугацаа дууссан. Дахин төлөх боломжгүй.

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

Checkout объект

Талбар	Төрөл	Тайлбар
`id`	Number	Checkout ID.
`url`	String	Харилцагчид үзүүлэх төлбөрийн хуудас.
`status`	String	Төлөв: `open`, `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	Хөнгөлөлтийн кодын талбар идэвхтэй эсэх.
`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	Хөнгөлөлтийн код оруулах талбар идэвхжүүлэх.
`discounts[]`	Array	false	Шууд хямдрал.
`subscription_id`	Number	false	Сунгах/солих багцын ID.

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

json

{
  "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-д бүртгэлгүй бүтээгдэхүүний үнэ, нэрийг хүсэлт дотроо шууд дамжуулна (динамик үнэ, сагс гэх мэт).

WARNING

Бүтээгдэхүүний хямдралтай хөнгөлөлтийн код болон багц (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.

shell

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	Тоо хэмжээ.

shell

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	Тоо хэмжээ.

shell

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	Оруулж болох хамгийн их тоо.

json

{
  "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 тэмдэгт хүртэл.

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

shell

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 төгрөгийн хямдрал "Хямдрал" тайлбартайгаар харагдана:

Byl хямдруулсан checkout

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

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

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

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

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

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

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

shell

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

TIP

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

Жишээ хүсэлт

shell

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

Жишээ гаралт

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 — давтагдах төлбөр

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

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

Төлөвүүд ​

Checkout объект ​

Checkout үүсгэх ​

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

price (lookup key) ​

price_id ​

price_data ​

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

Хямдрал ​

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

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

Checkout лавлах ​

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

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

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

Төлөвүүд

Checkout объект

Checkout үүсгэх

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

price (lookup key)

price_id

price_data

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

Хямдрал

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

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

Checkout лавлах

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