/v2/orders/{order_id}/refund

Buyurtma uchun mablag‘ni qaytarish so‘rovi.

Metod asinxron hisoblanadi.

Qaytarish jarayoni sxemasi

Cheklovlar

Siz to‘lovni to‘liq yoki qisman qaytarishingiz mumkin.

Qaytarishlar quyidagi paymentStatus holatlaridan birida bo‘lgan to‘lovlar uchun mavjud:

• CAPTURED – buyurtma muvaffaqiyatli to‘langan, mablag‘ to‘lovchining hisobidan yechilgan;
• PARTIALLY_REFUNDED – buyurtma bo‘yicha mablag‘ning bir qismi qaytarilgan.

Qaytarish muvaffaqiyatli bajarilgandan so‘ng, to‘lovning paymentStatus holati quyidagicha o‘zgaradi:

• REFUNDED – agar to‘liq qaytarish amalga oshirilgan bo‘lsa;
• PARTIALLY_REFUNDED – agar qaytarishdan keyin buyurtmada hali ham mahsulotlar qolgan bo‘lsa.

Joriy kun uchun qaytarilgan mablag‘lar summasi keyingi ish kunida hamkorga buyurtma bo‘yicha to‘lanadigan summadan ushlab qolinadi.

Misol: do‘koningizda 1000 soʻm buyurtma amalga oshirildi va 200 soʻm qaytarildi. Keyingi ish kunida siz 800 soʻm miqdorida to‘lovni olasiz (1000 − 200).

Qaytarish holatidagi o‘zgarishlarni /webhook orqali, shuningdek quyidagi so‘rovlar yordamida kuzatish mumkin:

• /operations/{external_operation_id}/
• /order/{order_id}/

Qaytarish statusini tekshirish misoli

/operations/{external_operation_id}/ metodi orqali externalOperationId bo‘yicha joriy qaytarish operatsiyasining holatini tekshirish mumkin.

Agar operatsiya hali yakunlanmagan bo‘lsa, masalan: "status": "PENDING". Bu holatda qaytarish uchun takroriy so‘rov yuborish mumkin emas.

{
  "code": 200,
  "status": "success",
  "data": {
    "operation": {
      "operationId": "52b3c4a8-528b-45eb-a57f-8f808f65d28f",
      "operationType": "REFUND",
      "orderId": "OrderS-2038",
      "amount": "250.00",
      "pointsAmount": null,
      "status": "PENDING", // возврат в процессе
      "reason": null,
      "params": { "motive": null, "branch_id": null, "manager_id": null },
      "externalOperationId": "OrderS-2038",
      "created": "2025-03-14T14:58:45.850206+03:00",
      "updated": "2025-03-14T14:58:45.850206+03:00"
    }
  }
}

/operations/{external_operation_id}/ metodi yordamida buyurtmaning barcha tafsilotlarini tekshirish mumkin.

Quyidagi misolda qaytarish operatsiyasi muvaffaqiyatli yakunlangan – "status": "SUCCESS", to‘lov esa "paymentStatus": "PARTIALLY_REFUNDED" holatida. Qaytarish uchun takroriy so‘rov yuborish mumkin.

{
  "code": 200,
  "status": "success",
  "data": {
    "operations": [
      {
        "operationId": "52b3c4a8-528b-45eb-a57f-8f808f65d28f",
        "operationType": "REFUND",
        "orderId": "OrderS-2038",
        "amount": "250.00",
        "status": "SUCCESS", // возврат успешно завершен
        "reason": null,
        "params": { "motive": null, "branch_id": null, "manager_id": null },
        "externalOperationId": "OrderS-2038",
        "created": "2025-03-14T14:58:45.850206+03:00",
        "updated": "2025-03-14T14:58:46.084886+03:00",
        "approvalCode": null
      },
      {
        "operationId": "9c763cfb-dcf6-4056-be8f-ca9e2e61d772",
        "operationType": "AUTHORIZE",
        "orderId": "OrderS-2038",
        "amount": "500.00",
        "status": "SUCCESS",
        "reason": null,
        "params": {},
        "externalOperationId": null,
        "created": "2025-03-14T14:58:07.161667+03:00",
        "updated": "2025-03-14T14:58:07.414886+03:00",
        "approvalCode": null
      }
    ],
    "order": {
      "currencyCode": "RUB",
      "cart": {
        "items": [
          {
            "productId": "p2",
            "quantity": { "count": "1", "available": null, "label": null },
            "type": "UNSPECIFIED",
            "title": "Яндекс.Станция Мини",
            "description": null,
            "total": "250",
            "subtotal": null,
            "discountedUnitPrice": "250",
            "unitPrice": null,
            "measurements": null,
            "finalPrice": "250",
            "pointsAmount": null,
            "features": null
          }
        ],
        "total": { "amount": "250", "pointsAmount": null, "label": null },
        "cartId": "1eed9a9827e68ba8981d9961c1237624fabc19cda05044b574e06302e83c7549",
        "externalId": null,
        "coupons": null,
        "discounts": null,
        "measurements": null
      },
      "merchantId": "76cc0f5c-91c4-40f2-9794-64a64c3c6011",
      "orderAmount": "250.00",
      "orderId": "OrderS-2038",
      "paymentMethod": { "methodType": "CARD", "cardLast4": "0412", "cardNetwork": "MASTERCARD" },
      "shippingMethod": null,
      "metadata": null,
      "created": "2025-03-14T14:58:03.699930+03:00",
      "updated": "2025-03-14T14:58:46.084886+03:00",
      "paymentStatus": "PARTIALLY_REFUNDED", // платеж частично возвращен
      "reason": null,
      "paymentUrl": "https://sandbox.pay.yandex.uz/l/I1RnP9",
      "isPrepayment": false,
      "splitCode": null
    },
    "delivery": null
  }
}

Qaytarish turlari

To‘lovni to‘liq yoki qisman qaytarish mumkin.

To‘liq qaytarishni amalga oshirish uchun buyurtma summasiga teng bo‘lgan faqat refundAmount parametrini yuboring.

Qisman qaytarishni amalga oshirish uchun qaytariladigan summaga teng refundAmount qiymatini yuboring va qaytarilayotgan mahsulotlar hamda xizmatlardan iborat savatni qo‘shing. Savatni quyidagi usullardan biri orqali shakllantirish mumkin:

• 1-usul: Qaytarishdan keyingi savat holatini ko‘rsatish.

  Buning uchun targetCart maydonidan foydalaning – bu qaytarish amalga oshirilgandan keyin xaridorda qolishi kerak bo‘lgan yakuniy savatdir. Agar bu maydon ko‘rsatilmagan bo‘lsa, savat to‘liq qaytarilmoqda deb hisoblanadi.

  targetShipping maydoni faqat Yandex Pay Checkout uchun qo‘llaniladi. Boshqa holatlarda ushbu maydonni bo‘sh qoldirish kerak. Agar bu maydon ko‘rsatilmagan bo‘lsa, yetkazish narxi ham to‘liq qaytariladi deb hisoblanadi.

• 2-usul: Qaytariladigan mahsulotlarni ko‘rsatish

  refundCart maydonidan foydalaning – unda qaytarilayotgan pozitsiyalar haqida ma’lumot beriladi: qaytarilayotgan mahsulotlar soni yoki aniq mahsulot narxini kamaytirish kerak bo‘lgan summa. Agar ushbu maydon ko‘rsatilmagan bo‘lsa, qaytarish butun savat bo‘yicha amalga oshiriladi.

Qaytarish misollari

Keling, orderId = Order-123 bo‘lgan buyurtma va quyidagi savat misolida ko‘rib chiqamiz.

{
  "items": [
    {
      "productId": "id-1",
      "price": "50",
      "title": "Sharikli ruchka",
      "quantity": {
        "count": "10"
      }
    },
    {
      "productId": "id-2",
      "price": "200",
      "title": "Bloknot",
      "quantity": {
        "count": "2"
      }
    }
  ]
}

To‘liq qaytarish

http POST https://sandbox.pay.yandex.uz/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" 'refundAmount:="900.00"'

Qisman qaytarish

Mahsulot birliklarini qaytarish

Faraz qilaylik, ikkita sharikli ruchkani qaytarish kerak. Bu quyidagi so‘rov orqali amalga oshiriladi:

http POST https://sandbox.pay.yandex.uz/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'targetCart[items][0]:={"productId": "id-1", "quantityCount": "8"}' \
  'targetCart[items][1]:={"productId": "id-2", "quantityCount": "2"}' \
  'refundAmount:="100.00"'

Ushbu misolda:

• Sharikli ruchkalar soni 2 taga kamaydi – ya’ni 10 donadan 8 donaga tushdi.
• So‘rovda price maydoni ko‘rsatilmagan, ammo uni ko‘rsatish ruxsat etiladi.
• Bloknot pozitsiyasida quantityCount o‘zgarmagan, shuning uchun uni ko‘rsatmaslik ham mumkin edi.

Pulning bir qismini qaytarish

Faraz qilaylik, har bir bloknot uchun 30 soʻm miqdorida mablag‘ni qaytarish kerak. Bu pozitsiya narxini kamaytirish orqali amalga oshiriladi.

http POST https://sandbox.pay.yandex.uz/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'targetCart[items]:=[{"productId": "id-1"}, {"productId": "id-2", "price": "170"}]' \
  'refundAmount:="60.00"'

Ushbu misolda:

• Bloknot narxi 30 soʻmga kamaydi – ya’ni 200 dan 170 soʻmgacha tushdi;
• Shu tariqa jami 60 soʻm miqdorida qaytarish amalga oshiriladi, chunki bloknotlar 2 ta edi.
• quantityCount maydonlari ko‘rsatilmagan, biroq zarur bo‘lsa ularning oldingi qiymatlarini ko‘rsatish mumkin.

Qaytarilayotgan mahsulot miqdorini ko‘rsatgan holda qaytarish

Faraz qilaylik, ikkita sharikli ruchkani qaytarish kerak. Bu quyidagi so‘rov orqali amalga oshiriladi:

http POST https://sandbox.pay.yandex.uz/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'refundCart[items][0]:={"productId": "id-1", "quantityCount": "2"}' \
  'refundAmount:="100.00"'

Ushbu misolda:

• Sharikli ruchkalar soni 2 taga kamaydi – ya’ni 10 donadan 8 donaga tushdi.
• So‘rovda price maydoni ko‘rsatilmagan, ammo uni ko‘rsatish to‘liq ruxsat etilgan edi.

Mahsulot narxining qaysi qismini qaytarish kerakligi ko‘rsatilgan holdagi qaytarish

Faraz qilaylik, har bir bloknot uchun 30 soʻm miqdorida mablag‘ni qaytarish kerak. Bu pozitsiya narxini kamaytirish orqali amalga oshiriladi.

http POST https://sandbox.pay.yandex.uz/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'refundCart[items]:=[{"productId": "id-1"}, {"productId": "id-2", "price": "30"}]' \
  'refundAmount:="60.00"'

Ushbu misolda:

• Bloknot narxi 30 ga kamaydi – 200 soʻmdan 170 soʻmgacha.
• Shu tariqa jami 60 soʻm miqdorida qaytarish amalga oshiriladi, chunki bloknotlar 2 ta edi.
• quantityCount maydonlari ko‘rsatilmagan, biroq zarur bo‘lsa ularning oldingi qiymatlarini ko‘rsatish mumkin.

Request

https://pay.yandex.uz/api/merchant/v2/orders/{order_id}/refund

https://sandbox.pay.yandex.uz/api/merchant/v2/orders/{order_id}/refund

Path parameters

{
  "branchId": "example",
  "externalOperationId": "example",
  "managerId": "example",
  "motive": "example",
  "refundAmount": "123.45",
  "refundCart": {
    "items": [
      {
        "price": "123.45",
        "productId": "example",
        "quantityCount": "123.45"
      }
    ]
  },
  "targetCart": null,
  "targetShipping": {
    "amount": "123.45"
  }
}

{
  "items": [
    {
      "price": "123.45",
      "productId": "example",
      "quantityCount": "123.45"
    }
  ]
}

{
  "items": [
    {
      "price": "123.45",
      "productId": "example",
      "quantityCount": "123.45"
    }
  ]
}

{
  "amount": "123.45"
}

{
  "price": "123.45",
  "productId": "example",
  "quantityCount": "123.45"
}

[
  {
    "price": "123.45",
    "productId": "example",
    "quantityCount": "123.45"
  }
]

{
  "items": [
    {
      "price": "123.45",
      "productId": "example",
      "quantityCount": "123.45"
    }
  ]
}

{
  "amount": "123.45"
}

Responses

{
  "code": 200,
  "data": {
    "operation": {
      "amount": "123.45",
      "created": "2025-01-01T00:00:00Z",
      "externalOperationId": "example",
      "operationId": "123e4567-e89b-12d3-a456-426614174000",
      "operationType": "AUTHORIZE",
      "orderId": "example",
      "params": {},
      "pointsAmount": "123.45",
      "reason": "example",
      "status": "PENDING",
      "updated": "2025-01-01T00:00:00Z"
    }
  },
  "status": "success"
}

{
  "operation": {
    "amount": "123.45",
    "created": "2025-01-01T00:00:00Z",
    "externalOperationId": "example",
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "params": {},
    "pointsAmount": "123.45",
    "reason": "example",
    "status": "PENDING",
    "updated": "2025-01-01T00:00:00Z"
  }
}

{}

{
  "amount": "123.45",
  "created": "2025-01-01T00:00:00Z",
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "params": {},
  "pointsAmount": "123.45",
  "reason": "example",
  "status": "PENDING",
  "updated": "2025-01-01T00:00:00Z"
}

{
  "amount": "123.45",
  "created": "2025-01-01T00:00:00Z",
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "params": {},
  "pointsAmount": "123.45",
  "reason": "example",
  "status": "PENDING",
  "updated": "2025-01-01T00:00:00Z"
}

{
  "operation": {
    "amount": "123.45",
    "created": "2025-01-01T00:00:00Z",
    "externalOperationId": "example",
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "params": {},
    "pointsAmount": "123.45",
    "reason": "example",
    "status": "PENDING",
    "updated": "2025-01-01T00:00:00Z"
  }
}