/v1/webhook

Status o‘zgarishi haqida bildirishnomalar.

Buyurtma statusi yoki buyurtma bo‘yicha operatsiya statusi o‘zgarganda so‘rov yuboriladi.

Dastaklanadigan hodisalar:

  • ORDER_STATUS_UPDATED – buyurtma holati yangilash;
  • OPERATION_STATUS_UPDATED – mablag‘ yechish, qaytarish yoki to‘lovni bekor qilish operatsiyasi holatni yangilash.

So‘rov formati

So‘rov application/octet-stream formatida yuboriladi va ES256 algoritmi bilan imzolangan JWT-token ko‘rinishida bo‘ladi. So‘rovni qayta ishlashdan oldin uning haqiqiyligini tekshiring. Buni qanday qilish haqida Autentifikatsiyabo‘limida o‘qing.

Tekshirilib dekod qilingan JWT-tokenning payload qismi hodisa ma’lumotlarini o‘z ichiga olgan JSON'dan iborat bo‘ladi. Hodisalar misollarini ko‘ring.

Agar token ichida so‘rov tanasi mavjud bo‘lmasa

  • Do‘kon bekendi Content-Type: application/octet-stream sarlavhasi bilan keladigan xabarlarni qabul qila olishiga ishonch hosil qiling.
  • Brandmauer kiruvchi so‘rovlarni bloklamayotganini va so‘rov tanasini kesib tashlamayotganini tekshiring.

Boshqa xatoliklarni Webhooklar bilan bog‘liq muammolarni hal qilishbo‘limida ko‘ring.

Operatsiyalar idempotentligi

Buyurtma bilan bog‘liq amallarni bajarishda, masalan, /v2/orders/{order_id}/refund metodi orqali mablag‘larni qaytarishda, operatsiyaning noyob identifikatori – externalOperationIdni uzating.

U yordamida siz:

  • qaysi operatsiya bo‘yicha bildirishnoma kelganini aniqlashingiz;
  • v1/operations/{external_operation_id} metodi orqali operatsiya holatini tekshirishingiz;
  • operatsiya takrorlanishidan himoyalanishingiz mumkin.

Agar siz bir xil externalOperationId bilan so‘rovni qayta yuborsangiz, quyidagilardan birini olasiz:

  • operatsiya jarayonda bo‘lsa, joriy operatsiya haqida ma’lumot;
  • operatsiya yakunlangan bo‘lsa, reasonCode: "DUPLICATE_EXTERNAL_OPERATION_ID" xatosi.

Hodisalar misollari

Buyurtma to‘lovi

{
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2023-11-26T08:11:09.359370+00:00",
  "order":{
    "orderId": "700aa3f04df64b3b8712d6b51f752e8b",
    "paymentStatus": "CAPTURED"
  }
}

JWT-token namunasi bilan jwt.io saytida tanishishingiz mumkin.

Yandex tomonidan do‘kon bekendiga yuboriladigan so‘rov namunasi:

  curl -X POST https://test.uz/some/prefix/v1/webhook \
    --header 'User-Agent: YandexPay/1.0' \
    --header 'Accept: \*/\*' \
    --header 'Content-Type: application/octet-stream' \
    --header 'X-Request-Id: ff2a54885c4e45309853d2e33af1d63b\\_3a70f3062db640fcb2f3c34de1a27bd5' \
    --header 'X-Request-Timeout: 13970' \
    --compressed \
    -d eyJhbGciOiJFUzI1NiIsImV4cCI6MTcwMDk4NzYwMCwiaWF0IjoxNzAwOTg3MzAwLCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUkRFUl9TVEFUVVNfVVBEQVRFRCIsImV2ZW50VGltZSI6IjIwMjMtMTEtMjZUMDg6MTE6MDkuMzU5MzcwKzAwOjAwIiwib3JkZXIiOnsib3JkZXJJZCI6IjcwMGFhM2YwNGRmNjRiM2I4NzEyZDZiNTFmNzUyZThiIiwicGF5bWVudFN0YXR1cyI6IkNBUFRVUkVEIn19.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2024-04-25T07:56:29.974810+00:00",
  "order":{
    "orderId": "253222_1714029088",
    "paymentStatus": "FAILED"
  }
}

JWT-token namunasi bilan jwt.io saytida tanishishingiz mumkin.

Qaytarish

Maslahat

Avval qaytarishlar qanday ishlashini /v2/orders/{order_id}/refund bo‘limida o‘rganing.

To‘liq qaytarish

Buyurtma holati o‘zgargan-o‘zgarmaganidan qat’i nazar, 2 ta notifikatsiya yuboriladi: operatsiya bo‘yicha va buyurtma bo‘yicha.

  1. OPERATION_STATUS_UPDATED – qaytarish operatsiyasi muvaffaqiyatli yakunlandi:

    {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "OPERATION_STATUS_UPDATED",
  "eventTime": "2024-04-19T10:27:53.323878+00:00",
  "operation":{
    "operationId": "73dec2cd-db5c-4386-be6d-10c5b5a2ee09",
    "orderId": "86283",
    "status": "SUCCESS",
    "operationType": "REFUND"
  }
}

  2. ORDER_STATUS_UPDATED – buyurtma yakuniy REFUNDED holatiga o‘tdi. Endi qaytarishlarni chaqirish mumkin emas.

    {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2024-04-19T12:16:28.766392+00:00",
  "order":{
    "orderId": "86283",
    "paymentStatus": "REFUNDED"
  }
}

    JWT-token namunasi bilan jwt.io saytida tanishishingiz mumkin.

  1. OPERATION_STATUS_UPDATED – qaytarish operatsiyasi muvaffaqiyatsiz yakunlandi:

    {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "OPERATION_STATUS_UPDATED",
  "eventTime": "2024-06-13T22:27:53.323878+00:00",
  "operation":{
    "operationId": "73dec2cd-db5c-4386-be6d-10c5b5a2ee08",
    "orderId": "9c8aed6d-a8e5-4c6a-acd8-645538173f66",
    "status": "FAIL",
    "operationType": "REFUND"
  }
}

    JWT-token namunasi bilan jwt.io saytida tanishishingiz mumkin.

  2. ORDER_STATUS_UPDATED – buyurtma avvalgi CAPTURED holatida qoldi:

    {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2024-06-13T22:27:54.323878+00:00",
  "order":{
    "orderId": "9c8aed6d-a8e5-4c6a-acd8-645538173f66",
    "paymentStatus": "CAPTURED"
  }
}

Qisman qaytarish

Siz buyurtmaning to‘liq summasini bir nechta qisman qaytarishlar orqali qaytarishingiz mumkin. Barcha qaytarishlar summasi buyurtmaning to‘liq qiymatiga yetganda, buyurtma yakuniy REFUNDED holatiga o‘tadi. Undan keyin qaytarishlarni amalga oshirib bo‘lmaydi.

Buyurtma holati o‘zgargan-o‘zgarmaganidan qat’i nazar, 2 ta notifikatsiya yuboriladi: operatsiya bo‘yicha va buyurtma bo‘yicha.

Misol sifatida uchta sharbatdan iborat buyurtmani ko‘rib chiqamiz.

  1. Bitta sharbat uchun qisman qaytarish amalga oshirildi. Sizga 2 ta bildirishnoma keladi:

    1. OPERATION_STATUS_UPDATED – qaytarish operatsiyasi muvaffaqiyatli yakunlandi:

      {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "OPERATION_STATUS_UPDATED",
  "eventTime": "2024-04-19T10:27:53.323878+00:00",
  "operation":{
    "operationId": "73dec3cs-sd5t-4356-ne6d-10c79b5d2ee09",
    "externalOperationId": "123-partial-refund-1",
    "orderId": "123",
    "status": "SUCCESS",
    "operationType": "REFUND"
  }
}

    2. ORDER_STATUS_UPDATED – buyurtma PARTIALLY_REFUNDED holatiga o‘tdi:

      {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2024-04-19T12:16:28.766392+00:00",
  "order":{
    "orderId": "123",
    "paymentStatus": "PARTIALLY_REFUNDED"
  }
}

  2. Ikkinchi marta bir dona sharbat uchun qisman qaytarish amalga oshirildi. Sizga 2 ta bildirishnoma keladi:

    1. OPERATION_STATUS_UPDATED – qaytarish operatsiyasi muvaffaqiyatli yakunlandi:

      {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "OPERATION_STATUS_UPDATED",
  "eventTime": "2024-04-19T13:27:53.323878+00:00",
  "operation":{
    "operationId": "28fba9ds-kl2m-7891-qw3r-45e82c7f1bb12",
    "externalOperationId": "123-partial-refund-2",
    "orderId": "123",
    "status": "SUCCESS",
    "operationType": "REFUND"
  }
}

    2. ORDER_STATUS_UPDATED – buyurtma PARTIALLY_REFUNDED holatida qoldi:

      {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2024-04-19T13:27:54.321878+00:00",
  "order":{
    "orderId": "123",
    "paymentStatus": "PARTIALLY_REFUNDED"
  }
}

  3. Uchinchi qisman qaytarish amalga oshirildi. Barcha qaytarishlar summasi buyurtmaning to‘liq qiymatiga yetdi. Sizga 2 ta bildirishnoma keladi:

    1. OPERATION_STATUS_UPDATED – qaytarish operatsiyasi muvaffaqiyatli yakunlandi:

      {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "OPERATION_STATUS_UPDATED",
  "eventTime": "2024-04-19T13:40:51.323878+00:00",
  "operation":{
    "operationId": "64abc2ts-rj4y-3187-mf5g-56b71e9a4dd67",
    "externalOperationId": "123-partial-refund-3",
    "orderId": "123",
    "status": "SUCCESS",
    "operationType": "REFUND"
  }
}

    2. ORDER_STATUS_UPDATED – buyurtma yakuniy REFUNDED holatiga o‘tdi. Endi qaytarishlarni chaqirish mumkin emas.

      {
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2024-04-19T14:16:28.766392+00:00",
  "order":{
    "orderId": "123",
    "paymentStatus": "REFUNDED"
  }
}

Request

POST

https://example.merchant.uz/v1/webhook

Production

POST

https://sandbox.example.merchant.uz/v1/webhook

Sandbox

Body

application/json
{
  "event": "TRANSACTION_STATUS_UPDATE",
  "eventTime": "2025-05-26T21:00:36.08847+00:00",
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "operation": {
    "externalOperationId": "example",
    "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "status": "PENDING"
  },
  "order": {
    "cartUpdated": true,
    "orderId": "example",
    "paymentStatus": "PENDING"
  },
  "subscription": {
    "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "nextWriteOff": "2025-01-01T00:00:00Z",
    "status": "NEW",
    "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Name

Description

event

Type: string

Hodisa turi:

  • ORDER_STATUS_UPDATED – buyurtma holati yangilash;
  • OPERATION_STATUS_UPDATED – mablag‘ yechish, qaytarish yoki to‘lovni bekor qilish operatsiyasi holatni yangilash.

Enum: TRANSACTION_STATUS_UPDATE, ORDER_STATUS_UPDATED, OPERATION_STATUS_UPDATED, SUBSCRIPTION_STATUS_UPDATED

eventTime

Type: string<date-time>

Hodisa vaqti RFC 3339 formatida: YYYY-MM-DDThh:mm:ssTZD.

Example: 2025-05-26T21:00:36.08847+00:00

merchantId

Type: string<uuid>

Sotuvchining ID (identifikatori) raqami.

Example: 123e4567-e89b-12d3-a456-426614174000

operation
All of 1 type

  • Type: OperationWebhookData

    Example
    {
  "externalOperationId": "example",
  "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "status": "PENDING"
}

Operatsiya haqida ma’lumot. Ma’lumot OPERATION_STATUS_UPDATED hodisasi bilan birga keladi

Example
{
  "externalOperationId": "example",
  "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "status": "PENDING"
}

order
All of 1 type

  • Type: OrderWebhookData

    Example
    {
  "cartUpdated": true,
  "orderId": "example",
  "paymentStatus": "PENDING"
}

Buyurtma haqida ma’lumot. Ma’lumot ORDER_STATUS_UPDATED hodisasi bilan birga keladi.

Example
{
  "cartUpdated": true,
  "orderId": "example",
  "paymentStatus": "PENDING"
}

subscription
All of 1 type

  • Type: SubscriptionWebhookData

    Example
    {
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}

Obuna holati.

Example
{
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}

OperationWebhookData

Name

Description

operationId

Type: string<uuid>

Operatsiya identifikatori.

Example: 5d32f295-8723-457d-81f9-ab13f17b7bd6

operationType

Type: string

Operatsiya turi. Operatsiya turlari haqida batafsil ma’lumotni Operatsiya holatlari bo‘limida o‘qing.

Enum: AUTHORIZE, BIND_CARD, REFUND, CAPTURE, VOID, RECURRING, PREPAYMENT, SUBMIT

orderId

Type: string

Buyurtma yaratilganda v1/orders metodiga yuborilgan buyurtma ID raqami.

Example: example

status

Type: string

Operatsiya holati. Operatsiya holatlari haqida batafsil ma’lumotni Operatsiya holatlari bo‘limida o‘qing.

Enum: PENDING, SUCCESS, FAIL

externalOperationId

Type: string

Sotuvchi tizimidagi operatsiya identifikatori. U noyob bo‘lishi kerak.

Muayyan operatsiyani v1/operations/{external_operation_id} metodi orqali kuzatish uchun ushbu parametrni yuboring.

Example: example
Example
{
  "externalOperationId": "example",
  "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "status": "PENDING"
}

OrderWebhookData

Name

Description

orderId

Type: string

Buyurtma yaratilganda v1/orders metodiga yuborilgan buyurtma ID raqami.

Example: example

paymentStatus

Type: string

Buyurtma holati. Batafsil ma’lumotni Buyurtma holati bo‘limida o‘qing.

Enum: PENDING, AUTHORIZED, CAPTURED, VOIDED, REFUNDED, CONFIRMED, PARTIALLY_REFUNDED, FAILED

cartUpdated

Type: boolean

Savatcha yangilangan yoki yo‘qligi. Ballar orqali to‘lov amalga oshirilganda qaytariladi. Agar flag qiymati true bo‘lsa, yangilangan savatchani oling.
Example
{
  "cartUpdated": true,
  "orderId": "example",
  "paymentStatus": "PENDING"
}

SubscriptionWebhookData

Name

Description

customerSubscriptionId

Type: string<uuid>

Obuna ID raqami. Obuna muvaffaqiyatli yaratilganda SDK tomonidan qaytariladi. Shuningdek, obunani u bo‘yicha kelgan birinchi bildirishnoma orqali ham saqlab qo‘yish mumkin. Ushbu obuna bo‘yicha keyingi yangilanishlar aynan shu maydon qiymati bilan yuboriladi.

Example: 123e4567-e89b-12d3-a456-426614174000

status

Type: string

Obuna holati

Enum: NEW, ACTIVE, CANCELLED, EXPIRED

subscriptionPlanId

Type: string<uuid>

Shaxsiy kabinetda yoki API orqali yaratilgan obuna rejasi ID raqami.

Example: 123e4567-e89b-12d3-a456-426614174000

nextWriteOff

Type: string<date-time>

Obuna bo‘yicha keyingi pul yechish urinishining sanasi

Example: 2025-01-01T00:00:00Z
Example
{
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}

Responses

200 OK

Vebhuk muvaffaqiyatli qabul qilindi va qayta ishlangan. Javob tanasi ixtiyoriy bo‘lishi mumkin, ammo quyidagini yuborish tavsiya etiladi: {"status": "success"}. Agar 200 status kodi qaytarilsa, Yandex vebhuklarni qayta yuborishni to‘xtatadi.

Body

application/json
{
  "status": "success"
}

Name

Description

status

Type: string

Default: success

400 Bad Request

Vebhukni qayta ishlashda xatolik. Agar javob bo‘lmasa yoki 200dan boshqa status qaytarilsa, Yandex yangi JWT-token yaratadi va vebhukni qayta yuboradi:

  • dastlabki 10 ta urinish har 5 ms dan keyin;
  • keyin interval eksponentsial ravishda oshib boradi va 15 daqiqagacha yetadi;
  • shundan so‘ng 24 soat davomida har 15 daqiqada yuboriladi. Qayta yuborishlarning umumiy davomiyligi – 24 soat. Shundan keyin vebhuk yetkazilmagan deb hisoblanadi.

Body

application/json
{
  "reason": "example",
  "reasonCode": "FORBIDDEN",
  "status": "fail"
}

Name

Description

reasonCode

Type: string

Xatolik kodi:

  • FORBIDDEN – buyurtma mavjud, ammo to‘lov Yandex Split orqali amalga oshirilmagan;
  • ORDER_NOT_FOUND – buyurtma sotuvchi tizimida topilmadi;
  • ORDER_AMOUNT_MISMATCH – buyurtma summasi sotuvchi tizimidagi summa bilan mos kelmaydi;
  • ORDER_DETAILS_MISMATCH – buyurtma tafsilotlari sotuvchi tizimidagi ma’lumotlardan farq qiladi;
  • OTHER – umumiy xatolik;
  • UNAUTHORIZED – JWT-token imzosini tekshirish muvaffaqiyatsiz tugadi;
  • TOKEN_EXPIRED – JWT-token amal qilish muddati tugagan;
  • CONFLICT – bildirishnomadagi ma’lumotlar sotuvchi tizimidagi buyurtma holati bilan mos kelmaydi. Masalan, bekor qilingan buyurtma uchun to‘lov haqida bildirishnoma kelib tushdi.

Enum: FORBIDDEN, ITEM_NOT_FOUND, ORDER_NOT_FOUND, ORDER_AMOUNT_MISMATCH, ORDER_DETAILS_MISMATCH, OUT_OF_INVENTORY, PICKUP_POINT_NOT_FOUND, SHIPPING_DETAILS_MISMATCH, OTHER, UNAUTHORIZED, TOKEN_EXPIRED, CONFLICT

reason

Type: string

Xatolik sababining tavsifi.

Example: example

status

Type: string

Default: fail
Avvalgisi
Overview
Keyingisi
Foydali havolalar