Обработка ответов: формат ответа — Прием платежей по API ЮKassa

Формат ответа ЮKassa

Ответ на запрос содержит код ответа (состояния) HTTP, стандартные заголовки и при необходимости тело ответа.

Тело ответа при успехе

Основная сущность API ЮKassa — это объект. Например, для проведения платежа нужен объект платежа, а для проведения выплаты — объект выплаты. Каждый запрос в API ЮKassa связан с выполнением определенного действия над объектом, например создание объекта, получение информации о нём.

При успешной обработке запроса (HTTP 200) ЮKassa возвращает в теле ответа созданный, измененный или запрошенный объект или список объектов. Формат тела ответа — JSON. Параметры тела ответа зависят от запроса.

Подробнее об обработке ответов при HTTP 200

Пример тела ответа

JSON
{
  "id": "23d93cac-000f-5000-8000-126628f15141",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "100.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=23d93cac-000f-5000-8000-126628f15141"
  },
  "created_at": "2019-01-22T14:30:45.129Z",
  "description": "Заказ №1",
  "metadata": {},
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

Тело ответа при ошибке

Если с запросом что-то не так (код ответа HTTP, отличный от 200), то для кодов ответа HTTP 400, 401, 403, 404, 429 и 500 вернется тело ответа в формате JSON с описанием ошибки.

Параметр	Тип	Описание
type	string	Тип объекта. Фиксированное значение — `error` (ошибка). Обязательный параметр
id	string	Идентификатор ошибки. Используйте его, если вам необходимо обратиться в техническую поддержку. Обязательный параметр
code	string	Код ошибки. Возможные значения: `invalid_request` — неправильный запрос, например ошибка в значении параметра или нарушение логики проведения операции (HTTP 400); `invalid_credentials` — некорректные данные для аутентификации запросов (HTTP 401); `forbidden` — не хватает прав для выполнения операции (HTTP 403); `not_found` — запрашиваемый ресурс не найден (HTTP 404); `too_many_requests` — превышен лимит запросов в единицу времени (HTTP 429); `internal_server_error` — технические неполадки на стороне ЮKassa (HTTP 500). Обязательный параметр
description	string	Описание ошибки на английском языке. Необязательный параметр
parameter	string	Название заголовка или параметра тела ответа, из-за которого произошла ошибка. Необязательный параметр

Пример тела ответа при ошибке

JSON
{
  "type" : "error",
  "id" : "e65a8f85-f8b7-4f4f-9fd3-bfef99aacbbb",
  "code" : "invalid_request",
  "description" : "Idempotence key is too long. Send the value in accordance with the documentation",
  "parameter" : "Idempotence-Key"
}

У ответов с другими кодами HTTP (405, 415) тело отсутствует. Для этих ответов причина возникновения ошибки указывается в заголовках (например, в заголовке Reason-Phrase).

Подробнее об ответах при ошибке — в описании кодов ответа HTTP.

Что почитать еще