Общая информация

Протокол онлайн платежей позволяет начать быстро и безопасно принимать платежи с банковских карт.

Протокол представляет собой полнофункциональное API для платежных операций. API использует REST-архитектуру. Параметры передаются методом PUT в теле запроса в формате JSON.

Способы взаимодействия

Протокол онлайн платежей позволяет использовать несколько вариантов взаимодействия:

Checkout - платежная форма на стороне QIWI.
API - полнофункциональное API для платежных операций.

Доступные методы

Метод	API	Checkout
Одношаговая авторизация средств	+	+
Двухшаговая авторизация средств	+	+
Токенизация	+	+
Оплата токеном	+	-

Начало работы

Для того, чтобы начать работу с протоколом, необходимо выполнить 3 простых шага.

Шаг 1. Оставить заявку на подключение b2b.qiwi.com

После обработки заявки с вами свяжется менеджер, чтобы обсудить возможные варианты подключения, собрать необходимые документы и начать интеграцию.

Шаг 2. Получить доступ к личному кабинету

При подключении к Протоколу онлайн платежей вы получите ваш id и доступ в личный кабинет. Доступ отправляется по email на указанный вами адрес. Более подробно с функциональностью можно ознакомиться в Личном кабинете.

Шаг 3. Выпустить secret key для взаимодействия

Для использования API и отправки запросов используется параметр авторизации - SECRET_KEY. Параметр авторизации указывается в заголовке Authorization, значение которого формируется как Bearer SECRET_KEY.

Тестовый и боевой режим

Все запросы в Протоколе онлайн платежей необходимо отправлять на URL:

https://api.qiwi.com/partner{API_REQUESTS}

Далее при описании всех запросов указывается только часть пути {API_REQUESTS}.

При подключении для вас создается id, которая находится в тестовом режиме. При этом вы можете проводить операции без списания средств с банковской карты. Подробнее о тестовом режиме можно узнать в разделе Тестовые данные.

Когда интеграция на вашей стороне закончена, мы переводим id в боевой режим. В боевом режиме происходят реальные списания с карт.

Checkout

Быстрый старт

Выставите счет покупателю

Прежде всего, необходимо получить ссылку на платежную форму и перенаправить покупателя по этой ссылке.

Пример тела запроса

 {
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "expirationDateTime": "2018-04-13T14:30:00+03:00"
   }

Отправьте PUT-запрос на URL /bill/v1/bills/{billId}, передав параметры:

Параметр	Описание	Тип
billId	Уникальный идентификатор счета в вашей системе	string
amount	Инфомрация о сумме счета	Object
amount.value	Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков	Number(6.2)
amount.currency	Идентификатор валюты счета (Alpha-3 ISO 4217 код)	String
expirationDateTime	Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус `EXPIRED` и последующая оплата станет невозможна.	URL-закодированная строка `ГГГГ-ММ-ДДTчч:мм:cc+\-чч:мм`

В ответ вы получите сообщение со следующими данными:

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

 {
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Test",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
  }

Параметр	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе
siteId	String	Идентификатор вашего сайта в QIWI Кассе
amount	Object	Информация о сумме счета
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе счета
status.value	String	Текущий статус счета
status.changedDateTime	String	Дата обновления статуса. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
customFields	Object	Дополнительные поля
customer	Object	Идентификаторы пользователя. Возможные опции: `email`, `phone`, `account`
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: `YYYY-MM-DDThh:mm:ss`
payUrl	String	Ссылка на созданную платежную форму
expirationDateTime	String	Срок действия созданной формы для оплаты. Формат даты: `YYYY-MM-DDThh:mm:ss+\-hh:mm`

Подробнее

Перенаправьте клиента на полученную в ответе ссылку

Для того, чтобы оплатить заказ, клиенту необходимо перейти по ссылке, указанной в поле payUrl в ответе. Перенаправьте клиента по ссылке и ожидайте получения уведомления об оплате.

Дождитесь уведомления об оплате

После того, как клиент оплатит выставленный вами счет, вам будет отправлены два серверных уведомления. Первое уведомление (тип уведомления payment) - об успешно прошедшем платеже. Второе уведомление (тип уведомления bill) - уведомление об оплате выставленного счета.

Уведомление о проведении платежа

Пример уведомления о проведении платежа

 {
  "payment": {
    "paymentId":"9999999",
    "type":"PAYMENT",
    "createdDateTime":"2019-06-03T08:19:16+03:00",
    "status": {
      "value":"SUCCESS",
      "changedDateTime":"2019-06-03T08:19:16+03:00"
    },
    "amount": {
      "value":111.11,
      "currency":"RUB"},
    "paymentMethod": {
      "type":"CARD",
      "cardHolder":"CARD HOLDER",
      "cardExpireDate":"1/2025",
      "maskedPan":"411111******0001"},
    "gatewayData": {
      "type":"ACQUIRING",
      "authCode":"181218",
      "rrn":"123"
    },
    "customer": {},
    "billId":"f1e1a1f11ae111a11a111111e1111111",
    "flags": ["SALE"]
  },
  "type":"PAYMENT",
  "version":"1"
}

Параметр	Тип	Описание
paymentId	String	Уникальный идентификатор платежа в вашей системе
type	String	Тип операции
createdDateTime	String	Системная дата создания платежа. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
amount	Object	Информация о сумме платежа
amount.value	Number	Сумма платежа, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Валюта платежа (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе платежа
status.value	String	Текущий статус платежа
status.changedDateTime	String	Дата обновления статуса. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
paymentMethod	Object	Информация о средстве платежа
paymentMethod.type	String	Тип средства платежа. Возможные значения: `TOKEN`,`CARD`
paymentMethod.maskedPan	String	Маскированный PAN карты
paymentMethod.cardHolder	String	Имя владельца карты
paymentMethod.expityDate	String	Дата истечения действия срока карты
gatewayData	String	Данные платежного шлюза
gatewayData.type	String	Тип шлюза. Возможные значения: `ACQUIRING`
gatewayData.authcode	String	Код авторизации
gatewayData.rrn	String	Значение RRN (ISO 8583)
customFields	Object	Дополнительные поля
customer	Object	Идентификаторы пользователя. Возможные опции: `email`, `phone`, `account`, `ip`
billId	String	Идентификатор счета
flags	Array of strings	Флаги операции: `SALE` - одношаговый сценарий

Пример уведомления об оплате счета


{ "bill":
  {  
     "siteId":"23044",
     "billId":"1519892138404fhr7i272a2",
     "amount":{  
        "value":"100",
        "currency":"RUB"
     },
     "status":{  
        "value":"PAID",
        "datetime":"2018-03-01T11:16:12+03"
     },
     "customer":{},
     "customFields":{},
     "creationDateTime":"2018-03-01T11:15:39+03",
     "comment":"Test",
     "expirationDateTime":"2018-04-01T11:15:39+03:00+03"
   },
  "version":"1"
}

Уведомление об оплате счета

Параметр	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе
siteId	String	Идентификатор вашего сайта в QIWI Кассе
amount	Object	Информация о сумме счета
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе счета
status.value	String	Текущий статус счета
status.changedDateTime	String	Дата обновления статуса. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
customFields	Object	Дополнительные поля
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
expirationDateTime	String	Срок действия созданной формы для оплаты. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`

Подробнее о настройке серверных уведомлений, а также о различных типах уведомлений можно узнать в разделе Серверные уведомления.

Сделать возврат покупателю

Для того, чтобы сделать возврат по операциям, необходимо отправить запрос на возврат.

Запрос отправляется на URL

/bill/v1/bills/{billId}/refunds/{refundId}

Пример тела запроса на возврат.

{
    "amount": {
         "currency": "RUB",
         "value": 42.24
    }
}

Параметр	Тип	Описание
billId	String	Уникальный идентификатор счета
refundId	String	Уникальный идентификатор возврата в вашей системе
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Идентификатор валюты счета (Alpha-3 ISO 4217 код)

Подробнее

Дополнительно

Двухшаговый сценарий

Как произвести холдирование средств

Пример запроса на холдирование:

{
   "amount": {  
     "currency": "RUB",  
     "value": 42.24
   },
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customFields": {},
   "paymentFlags":["AUTH"]
   }

Для этого необходимо добавить в запрос выставления счета дополнительный параметр: "paymentFlags":["AUTH"].

Параметр	Тип	Описание
billId	string	Уникальный идентификатор счета в вашей системе
amount	Object	Информация о сумме счета
amount.value	Number(6.2)	Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков
amount.currency	(Alpha-3 ISO 4217 код)	Идентификатор валюты счета
expirationDateTime	URL-закодированная строка `YYYY-MM-DDThh:mm:ss±hh`	Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус `EXPIRED` и последующая оплата станет невозможна
paymentFlags	Array of strings	Дополнительные платежные флаги Доступные значения: "AUTH" - выполнить двухшаговый сценарий авторизации средств

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


{
    "siteId": "test-01",
    "billId": "gg",
    "amount": {
        "currency": "RUB",
        "value": "42.24"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-28T16:26:36.835+03:00"
    },
    "customFields": {
        "AUTH": "true"
    },
    "comment": "Spasibo",
    "creationDateTime": "2019-08-28T16:26:36.835+03:00",
    "expirationDateTime": "2019-09-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=78d60ca9-7c99-481f-8e51-0100c9012087"}

В ответе вы получите ссылку на платежную форму:

Параметр	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе
siteId	String	Идентификатор вашего сайта в QIWI Кассе
amount	Object	Информация о сумме счета
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе счета
status.value	String	Текущий статус счета
status.changedDateTime	String	Дата обновления статуса. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
customFields	Object	Дополнительные поля, включает `paymentFlags`
customFields.AUTH	String	Идентификатор транзакции с двухшаговой авторизацией
customer	Object	Идентификаторы пользователя. Возможные опции: `email`, `phone`, `account`
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: `YYYY-MM-DDThh:mm:ss`
payUrl	String	Ссылка на созданную платежную форму
expirationDateTime	String	Срок действия созданной формы для оплаты. Формат даты: `YYYY-MM-DDThh:mm:ss+\-hh:mm`

Узнать id транзакции для подтверждения

Пример уведомления

{
  "payment":
  {
    "paymentId":"804900",  <==paymentId, необходимый для capture
    "type":"PAYMENT",
    "createdDateTime":"2019-08-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2019-08-28T12:58:53+03:00"
    },
    "amount":{
      "value":1.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444\*\*\*\*\*\*4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

После того, как платеж успешно совершен, вам придет серверное уведомление.

Используйте для подтверждения операции (capture) параметр paymentId из уведомления.

Параметр	Тип	Описание
paymentId	String	Уникальный идентификатор счета в вашей системе
type	String	Тип операции
createdDateTime	String	Системная дата создания счета. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
amount	Object	Информация о сумме платежа
amount.value	Number	Сумма платежа, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Валюта платежа (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе платежа
status.value	String	Текущий статус платежа
status.changedDateTime	String	Дата обновления статуса. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`
paymentMethod	Object	Информация о средстве платежа
paymentMethod.type	String	Тип средства платежа. Возможные значения `TOKEN`,`CARD`
paymentMethod.maskedPan	String	Маскированный PAN карты
paymentMethod.cardHolder	String	Имя владельца карты
paymentMethod.expityDate	String	Дата истечения действия срока карты
gatewayData	String	Данные платежного шлюза
gatewayData.type	String	Тип шлюза. Возможные значения: `ACQUIRING`
gatewayData.authcode	String	Код авторизации
gatewayData.rrn	String	Значение RRN (ISO 8583)
customFields	Object	Дополнительные поля
customer	Object	Идентификаторы пользователя. Возможные опции: `email`, `phone`, `account`, `ip`
billId	String	Идентификатор счета
flags	Array of strings	Флаги операции: `SALE`-одношаговый сценарий

Подтвердить операцию

Используя номер операции (paymentId), можно выполнить capture - подтверждение операции.

Выполните PUT-запрос c пустым телом на URL

/payin/v1/sites/{siteId}/payments/{paymentId}/captures/{captureId}

где:

{siteId} - уникальный ID ТСП, можно увидеть в ответе на запрос холдирования средств
{paymentId} - ID операции, string, уникальный идентификатор платежа, приходит в серверном уведомлении
{captureId} - ID подтверждения, string, уникальный идентификатор на стороне ТСП, ТСП указывает его самостоятельно

Подробнее

Запросы, Статусы и Ошибки

Создание счета

 {
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {}  
   }
}

 {
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
  }

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Операция возврата

{
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}

{
    "amount": {
      "value": 50.50,
      "currency": "RUB"
    },
    "datetime": "2018-03-01T16:06:57+03",
    "refundId": "1",
    "status": "PARTIAL"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Операция подтверждения (для двухшагового сценария)

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": "6.77"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

API

Быстрый старт

Пример тела запроса

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  }
}

Для того, чтобы позволить вашему клиенту произвести оплату, необходимо создать платеж. Выполните следующие действия:

1. Авторизуйте платеж

Отправьте PUT-запрос на URL

/payin/v1/sites/{siteId}/payments/{paymentId}

с параметрами:

{siteId}: ваш id
{paymentId}: номер платежа, уникальный на стороне ТСП
paymentMethod: описание платежных данных
amount: сумма (value) и валюта (currency) платежа

Подробнее

В ответе вы получите следующие данные:

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

{
    "paymentId": "1811",
    "billId": "autogenerated-a29ea8c9-f9d9-4a60-87c2-c0c4be9affbc",
    "createdDateTime": "2019-08-15T13:28:26+03:00",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "444444******1049",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-15T13:28:26+03:00"
    }
}

Параметр	Тип	Описание
paymentId	String	Уникальный идентификатор платежа в вашей системе, такой же как в запросе
createdDateTime	String	Системная дата создания платежа. Формат даты: `YYYY-MM-DDThh:mm:ss+hh:ss`
amount	Object	Информация о сумме платежа
amount.value	Number	Сумма платежа, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Валюта платежа (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе платежа
status.value	String	Текущий статус платежа
status.changedDateTime	String	Дата обновления статуса. Формат даты: `YYYY-MM-DDThh:mm:ss±hh`

Чаще всего для создания платежа вам понадобится пройти дополнительную аутентификацию. Такое может произойти, если:

Для платежа обязателен CVV
Необходимо произвести 3DS аутентификацию

Если есть необходимость в дополнительной аутентификации, в ответе вы получите дополнительный объект requirements c полями:

"requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
}

threeDS: параметры pareq и acsUrl для перенаправления на страницу подтверждения от эмитента
cvv: данные CVV

2. (опционально) Завершите аутентификацию клиента

Отправьте PUT-запрос на URL

payin/v1/sites/{siteUid}/payments/{paymentId}/complete

и укажите параметры:

cvv
Данные 3DS

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  },
  "cvv2": {
    "cvv2": "string"
  }
}

Подробнее

3. Подтвердите платеж

Используя номер операции (paymentId), можно произвести capture - подтверждение операции.

Отправьте PUT-запрос c пустым телом на URL

/payin/v1/sites/{siteId}/payments/{paymentId}/captures/{captureId}

где:

{siteId} - уникальный ID ТСП, можно увидеть в ответе на запрос холдирования средств
{paymentId} - ID операции, string, уникальный идентификатор платежа, получается в серверном уведомлении
{captureId} - ID подтверждения, string, уникальный идентификатор на стороне ТСП, ТСП указывает его самостоятельно

Подробнее

Пример подтверждения

curl https://api.qiwi.com/partner/payin/v1/sites/test-01/payments/2820220333/captures/43234
-X PUT
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer NDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE
-d ‘{}'

Запросы, Статусы и Ошибки

Платеж

{
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example payment",
  "paymentId": "string",
  "billId": "string",
  "amount": {
    "currency": "RUB",
    "value": 200
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "CARDHOLDER NAME"
  },
  "customer": {
    "account": "string",
    "address": {
      "city": "Moscow",
      "country": "Russian Federation",
      "details": "Severnoe chertanovo microdistrict 1a 1",
      "region": "Moscow city"
    },
    "email": "customer@example.com",
    "phone": "+79991234567"
  },
  "deviceData": {
    "datetime": "2017-09-03T14:30:00+03:00",
    "fingerprint": "TW96aWxsYS81LjAgKHBsYXRmb3JtOyBydjpnZWNrb3ZlcnNpb24p",
    "ip": "127.0.0.1",
    "screenResolution": "1280x1024",
    "timeOnPage": 1440,
    "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion"
  },
  "extras": {},
  "flags": [
    "SALE"
  ]
}

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : "200.00"
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : "0.00"
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : "0.00"
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "extras" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Статус платежа

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : "200.00"
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : "0.00"
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : "0.00"
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "extras" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Завершение аутентификации

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  },
  "cvv2": {
    "cvv2": "string"
  }
}

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : "200.00"
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : "0.00"
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : "0.00"
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "COMPLETED",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "extras" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Подтверждение покупки

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": "6.77"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Статус подтверждения

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": "6.77"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Создание возврата

{
  "refundId": "tcwv3132",
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": "2.34"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Статус возврата

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": "2.34"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Статус возвратов

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": "2.34"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Причины отклонения

Причины отклонения передаются в ответах на запросы в поле status.reason и в поле status.reasonCode уведомления.

Причина отклонения	Описание
INVALID_STATE	Некорректный статус транзакции
INVALID_AMOUNT	Некорректная сумма
DECLINED_BY_MPI	Отклонено MPI
DECLINED_BY_FRAUD	Отклонено фрод-мониторингом
GATEWAY_INTEGRATION_ERROR	Ошибка взаимодействия с банком
GATEWAY_TECHNICAL_ERROR	Техническая ошибка на стороне банка
ACQUIRING_MPI_TECH_ERROR	Техническая ошибка при проведение 3DS аутентификации
ACQUIRING_GATEWAY_TECH_ERROR	Техническая ошибка
ACQUIRING_ACQUIRER_ERROR	Техническая ошибка
ACQUIRING_AUTH_TECHNICAL_ERROR	Ошибка при проведении авторизации средств
ACQUIRING_ISSUER_NOT_AVAILABLE	Ошибка эмитента Банк-эмитент не доступен
ACQUIRING_SUSPECTED_FRAUD	Ошибка эмитента. Подозрение на фрод
ACQUIRING_LIMIT_EXCEEDED	Ошибка эмитента. Превышен один из лимитов
ACQUIRING_NOT_PERMITTED	Ошибка эмитента. Операция не разрешена
ACQUIRING_INCORRECT_CVV	Ошибка эмитента. Некорректный CVV
ACQUIRING_EXPIRED_CARD	Ошибка эмитента. Неверный срок действия карты
ACQUIRING_INVALID_CARD	Ошибка эмитента. Проверьте корректность введенных данных
ACQUIRING_INSUFFICIENT_FUNDS	Ошибка эмитента. Недостаточно средств
ACQUIRING_UNKNOWN	Неизвестная ошибка
BILL_ALREADY_PAID	Счет уже оплачен
PAYIN_PROCESSING_ERROR	Ошибка при проведении платежа

Дополнительно

Серверные уведомления

Протокол поддерживает 4 типа уведомлений: payment, capture, refund и bill.

Уведомление представляет собой входящий POST-запрос. Тело запроса содержит JSON-сериализованные данные счета (кодировка UTF-8).

В уведомлении присутствует подпись запроса, которую ТСП необходимо проверять на своей стороне для исключения возможности подделки уведомления.

Для дополнительной уверенности следует принимать уведомления о платежах только с указанных ниже IP-адресов компании QIWI.

79.142.16.0/20
195.189.100.0/22
91.232.230.0/23
91.213.51.0/24

Уведомление считается успешно доставленным, если сервер ТСП ответил HTTP кодом состояния 200 OK. Таким образом, до тех пор пока не будет ответа сервера с кодом состояния 200 OK, система будет осуществлять попытки доставки уведомления через увеличивающиеся интервалы времени в течение суток с момента операции.

Адрес сервера для уведомлений указывается в Личном Кабинете на сайте kassa.qiwi.com в разделе "Настройки". Можно также указать адрес сервера в опциональном параметре callbackUrl в запросе к API.

Авторизация уведомлений

После получения входящего уведомления необходимо проверить подлинность данного уведомления. Для этого используется механизм цифровой подписи. Подпись уведомления отправляется в заголовке X-Api-Signature-SHA256. Для формирования подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256.

Алгоритм проверки подписи:

Объединить значения определенных параметров в одну строку с разделителем "|". Например:

parameters = {amount.currency}|{amount.value}|{billId}|{siteId}|{status}

где {*} – значение параметра уведомления. Все значения при проверке подписи должны трактоваться как строки. В описании уведомлений указаны специфические параметры для расчета подписи.
Вычислить HMAC-хэш c алгоритмом хэширования SHA256:

hash = HMAС(SHA256, secret_key, parameters) Где:
- secret_key – ключ функции (UTF-8);
- parameters – строка из п.1 (UTF-8);
Сравнить значение заголовка X-Api-Signature-SHA256 с результатом из п.2.

Уведомления PAYMENT, CAPTURE, REFUND

{
   "payment/refund/capture":{
      "paymentId/refundId/captureId":"4504751",
      "tokenData":{
         "paymentToken":"4cc975be-483f-8d29-2b7de3e60c2f",
         "expiredDate":"2021-12-31T00:00:00+03:00"
      },
      "type":"PAYMENT",
      "createdDateTime":"2019-10-08T11:31:37+03:00",
      "status":{
         "value":"SUCCESS",
         "changedDateTime":"2019-10-08T11:31:37+03:00"
      },
      "amount":{
         "value":2211.24,
         "currency":"RUB"
      },
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"220024/*/*/*/*/*/*5036",
         "rrn":null,
         "authCode":null,
         "type":"CARD"
      },
      "customer":{
         "ip":"79.142.20.248",
         "account":"token32",
         "phone":"0"
      },
      "billId":"testing122",
      "flags":[
         "SALE"
      ]
   },
   "type":"PAYMENT",
   "version":"1"
}

Параметр	Описание	Тип
paymentId/refundId/captureId	Уникальный идентификатор платежа/возврата/подтверждения в системе ТСП	String(200)
type	Тип операции	String(200)
createdDatetime	Дата создания операции	URL-закодированная строка `ГГГГ-ММ-ДДTЧЧ:ММ:ССZ`
amount	Информация о сумме операции	Object
amount.value	Сумма операции, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)
amount.currency	Идентификатор валюты операции (Alpha-3 ISO 4217 код)	String(3)
billId	ID счета, соответствующего операции	String(200)
status	Информация о статусе операции	Object
status.value	Строковое значение статуса	String
status.changedDatetime	Дата обновления статуса	URL-закодированная строка `ГГГГ-ММ-ДДTЧЧ:ММ:ССZ`
status.reasonCode	Код причины отклонения	String(200)
status.reasonMessage	Описание причины отклонения	String(200)
status.errorCode	Код ошибки	Number
paymentMethod	Информация о средстве платежа	Object
paymentMethod.type	Тип метода оплаты	String
paymentMethod.maskedPan	Маскированный PAN карты	String
paymentMethod.rrn	RRN платежа (по ISO 8583)	Number
paymentMethod.authCode	Auth-code платежа	Number
customer	Информация о пользователе, на которого был выставлен счет	Object
customer.phone	Номер телефона, на который был выставлен счет (если был указан при выставлении счета)	String
customer.email	E-mail пользователя (если был указан при выставлении счета)	String
customer.account	Идентификатор пользователя в системе ТСП (если был указан при выставлении счета)	String
customer.ip	IP адрес пользователя	String
customer.country	страна адрес пользователя	String
flags	Дополнительные команды для API	Массив. Доступные значения - `SALE`/`REVERSAL`
version	Версия уведомлений	String

Подпись считается для этих полей по умолчанию:

PAYMENT: payment.paymentId|payment.createdDateTime|payment.amount.value

REFUND: refund.refundId|refund.createdDateTime|refund.amount.value

CAPTURE: capture.captureId|capture.createdDateTime|capture.amount.value

Сервис нотификаций перекладывает неуспешные коллбэки по очередям:

2 попытки с отложенным временем по 5 секунд
2 попытки с отложенным временем по 1 минуте
2 попытки с отложенным временем по 5 минут

Время повторной отправки может немного сдвигаться в бОльшую сторону.

Уведомления BILL

Данный тип уведомления отправляется только при использовании Checkout. Нотификация будет отправлена, как только выставленный счет будет оплачен.

Пример уведомления

{
   "bill":{
      "siteId":"Obuc-00",
      "billId":"testing122",
      "amount":{
         "value":"2211.24",
         "currency":"RUB"
      },
      "status":{
         "value":"PAID",
         "changedDateTime":"2019-10-08T11:31:39+03"
      },
      "customer":{
         "account":"account42"
      },
      "customFields":{},
      "comment":"Spasibo",
      "creationDateTime":"2019-10-08T11:30:16+03",
      "expirationDateTime":"2019-10-13T14:30:00+03"
   },
   "version":"1"
}

Параметр	Описание	Тип
billId	Уникальный идентификатор платежа в системе ТСП	String(200)
siteId	Идентификатор сайта ТСП в QIWI Кассе	Number
amount	Информация о сумме счета	Object
amount.value	Сумма счета, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)
amount.currency	Идентификатор валюты счета (Alpha-3 ISO 4217 код)	String(3)
status	Информация о статусе счета	Object
status.value	Строковое значение статуса	String
status.changedDateTime	Дата обновления статуса	URL-закодированная строка `ГГГГ-ММ-ДДTЧЧ:ММ:ССZ`
customer	Информация о пользователе, на которого был выставлен счет	Object
customer.phone	Номер телефона, на который был выставлен счет (если был указан при выставлении счета)	String
customer.email	E-mail пользователя (если был указан при выставлении счета)	String
customer.account	Идентификатор пользователя в системе ТСП (если был указан при выставлении счета)	String
creationDatetime	Дата создания счета	URL-закодированная строка `ГГГГ-ММ-ДДTЧЧ:ММ:ССZ`
expirationDateTime	Срок оплаты счета	URL-закодированная строка `ГГГГ-ММ-ДДTЧЧ:ММ:ССZ`
comment	Комментарий к счету	String(255)
customFields	Дополнительные данные счета (если были указаны при выставлении счета).	Object
version	Версия уведомлений	String

Подпись считается для этих полей по умолчанию:

BILL: amount.currency|amount.value|billId|siteId|status

Ответ → POST

После того, как был получен входящий запрос-уведомление, необходимо проверить подлинность цифровой подписи и отправить ответ в формате JSON.

HTTP/1.1 200 OK
Content-Type: application/json

{
 "error":"0"
}

В ответе должен вернуться код результата обработки уведомления. Код результата должен находиться в параметре error.

Передача чека (54-ФЗ)

Чек передается в параметре cheque в операциях bill и payment при работе через Checkout и API, соответственно.

Описание чека

"cheque" : {
	"sellerId" : 3123011520,
	"customerContact" : "Test customer contact",
  "chequeType" : "COLLECT",
	"taxSystem" : "OSN",
	"positions" : [ {
		"quantity" : 1,
		"price" : {
			    "value" : 7.82,
			    "currency" : "RUB"
			    },
		"tax" : "NDS_0",
		"paymentSubject" : "PAYMENT",
		"paymentMethod" : "FULL_PAYMENT",
		"description" : "Test description"
			}
			]
	    }

Параметр	Условие	Тип данных	Описание
sellerId	Обязательно	decimal	ИНН организации, для которой пробивается чек
chequeType	Обязательно	decimal	Признак расчета (тэг 1054): `COLLECT` – Приход `COLLECT_RETURN` - Возврат прихода CONSUME - Расход `CONSUME_RETURN` -Возврат расхода
customerContact	Обязательно	string(64)	Телефон или электронный адрес покупателя (тэг 1008)
taxSystem	Обязательно	decimal	Система налогообложения (тэг 1055): `OSN` - Общая, ОСН `USN` – Упрощенная доход, УСН доход `USN_MINUS_CONSUM` – Упрощенная доход минус расход, УСН доход - расход `ENVD` – Единый налог на вмененный доход, ЕНВД `ESN` - Единый сельскохозяйственный налог, ЕСН `PATENT` – Патентная система налогообложения, Патент
positions	Обязательно	array	Массив товаров
quantity	Обязательно	decimal	Количество предмета расчета (тэг 1023)
price	Обязательно	decimal	Цена за единицу предмета расчета с учетом скидок и наценок (тэг 1079)
tax	Обязательно	decimal	Ставка НДС (тэг 1199): `NDS_CALC_18_118` - с учетом НДС 18% (18/118) `NDS_CALC_10_110` – с учетом НДС 10% (10/110) `NDS_0` – ставка НДС 0% `NO_NDS` – НДС не облагается `NDS_CALC_20_120` – с учетом НДС 20% (20/120) (20/120)
description	Обязательно	string(128)	Наименование предмета расчета
paymentMethod	Обязательно	decimal	Признак способа расчёта (тэг 1214): `ADVANCED_FULL_PAYMENT` – предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета. `PARTIAL_ADVANCE_PAYMENT` – предоплата. Частичная предварительная оплата до момента передачи предмета расчета. `ADVANCE` – аванс. `FULL_PAYMENT` – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета. `PARTIAL_PAYMENT` – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит. `CREDIT` – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит. `CREDIT_PAYMENT` – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).
paymentSubject	Обязательно	decimal	Признак предмета расчёта (тэг 1212): `COMMODITY` – товар. О реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар). `EXCISE_COMMODITY` – подакцизный товар. О реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар). `WORK` – работа. О выполняемой работе (наименование и иные сведения, описывающие работу). `SERVICE` – услуга. Об оказываемой услуге (наименование и иные сведения, описывающие услугу). `GAMBLING_RATE` – ставка азартной игры. О приеме ставок при осуществлении деятельности по проведению азартных игр. `GAMBLING_PRIZE` – выигрыш азартной игры. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр. `LOTTERY_TICKET` – лотерейный билет. О приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей. `LOTTERY_PRIZE` – выигрыш лотереи. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей. `GRANTING_RESULTS_OF_INTELLECTUAL_ACTIVITY` – предоставление результатов интеллектуальной деятельности. О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации. `PAYMENT` – платеж. Об авансе, задатке, предоплате, кредите, взносе в счет оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета. `AGENCY_FEE` – агентское вознаграждение. О вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом. `COMPAUND_PAYMENT_SUBJECT` – составной предмет расчета. О предмете расчета, состоящем из предметов, каждому из которых может быть присвоено значение выше перечисленных признаков. `OTHER_PAYMENT_SUBJECT` – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета.

Токенизация

Протокол онлайн платежей поддерживает механизм токенизации карт. Токенизация карт позволяет сохранять карты пользователей в зашифрованном виде и в дальнейшем использовать их для безакцептных платежей.

По умолчанию токенизация карт отключена. Если Вам необходимо подключить данную функцию, обратитесь к своему сопровождающему менеджеру.

Выпуск платежного токена

Пример тела запроса

{
   "amount": {  
     "currency": "RUB",  
     "value": 2211.24
   },
   "comment": "Spasibo",
   "expirationDateTime": "2020-12-26T14:30:00+03:00",
   "customer": {
   	"account":"token324"
   },
   "paymentFlags":["BIND_PAYMENT_TOKEN"]
   }

Для того, чтобы выпустить платежный токен, необходимо в запросе на создание платежа указать:

Платежный флаг "BIND_PAYMENT_TOKEN" - флаг, указывающий системе на необходимость выпуска платежного токена
{account} - уникальный идентификатор Покупателя в системе ТСП

Не указывайте один и тот же account для всех Ваших пользователей. Это может привести к тому, что пользователи смогут произвести оплату чужими картами.

Пример нотификации с токеном

{
  "payment":
  {
    "paymentId":"9790769",
  "tokenData": {
    "paymentToken":"66aebf5f-098e-4e36-922a-a4107b349a96",
    "expiredDate":"2021-12-31T00:00:00+03:00"
  },
  "type":"PAYMENT",
  "createdDateTime":"2020-01-23T15:07:35+03:00",
  "status": {
    "value":"SUCCESS",
    "changedDateTime":"2020-01-23T15:07:36+03:00"
  },
  "amount": {
    "value":2211.24,
    "currency":"RUB"
  },
  "paymentMethod": {
    "type":"CARD",
    "maskedPan":"4111111111",
    "cardHolder":"CARD HOLDER",
    "cardExpireDate":"12/2021",
    "type":"CARD"
  },
  "customer": {
     "ip":"79.142.20.248",
     "account":"token324",
     "phone":"0"
   },
  "billId":"testing1222213",
  "flags":["SALE"]
},
 "type":"PAYMENT",
 "version":"1"
}

В ответ в нотификации типа payment вы получите следующие данные:

Параметр	Тип данных	Описание
tokenData	Object	Объект, содержащий данные о выпущенном токене карты
tokenData.paymentToken	String	Токен карты
tokenData.expiredDate	String	Дата окончания срока действия токена. Формат даты: `YYYY-MM-DDThh:mm:ss±hh:mm`

Полученные данные необходимо использовать при оплате.

Оплата платежным токеном

Произвести оплату с помощью выпущенного токена можно только через API.

Для этого в объекте paymentMethod вместо платежных данных укажите параметры:

Пример платежного запроса с токеном

{
  "amount": {
    "currency": "RUB",
    "value": 2000.00
  },
   "paymentMethod" : {
    "type": "TOKEN",
    "paymentToken" : "f42abb6c-4b6b-464e-adcc-fbdc197bd24d"
  },
  "customer": {
        "account": "token324"
    }
}

Параметр	Тип	Описание
type	String	Тип операции. Необходимо указать `TOKEN`
paymentToken	String	Токен карты

Также не забудьте указать account - уникальный идентификатор пользователя, для которого был выпущен токен. Без данного параметра оплата с помощью токена невозможна.

Выплаты

По умолчанию, выплаты по проведенным операциям производятся раз в 2 дня и минимальным порогом 10.000 рублей. Если вам необходимо кастомное расписание, обратитесь к вашему курирующему менеджеру.

КИВИ взимает комиссию за каждую подтвержденную операцию. Если отмена операции была произведена до подтверждения, комиссия не взимается. Если была произведена частичная отмена до подтверждения операции, комиссия будет пересчитана.

Тестовые данные

Для тестирования операций оплаты используются боевые URL сервисов оплаты. Для каждого нового ТСП в системе создаются siteId и по умолчанию включаются в режим тестирования. Также можно запросить переключение в режим тестирования любого своего siteId, либо добавление нового siteId в тестовом режиме через своего менеджера.

В тестовом режиме можно использовать любой номер карты, удовлетворяющий алгоритму Luhn.

В режиме тестирования из валют (параметр currency) разрешен только рубль РФ (643).

CVV в режиме тестирования может быть любым (произвольные 3 цифры).

Для тестирования различных вариантов оплаты и ответов необходимо использовать различные сроки действия карты:

Если месяц срока действия - 02, то операция будет проведена неуспешно.
Если месяц срока действия - 03, то операция будет проведена успешно с задержкой в 3 секунды.
Если месяц срока действия - 04, то операция будет проведена неуспешно с задержкой в 3 секунды.
Во всех остальных случая операция выполняется успешно.

Для проведения операции с 3DS необходимо использовать строку unknown name в имени держателя карты. 3DS в тестовом режиме можно проверить только при вводе номера реальной карты.

Общая информация

Способы взаимодействия

Доступные методы

Начало работы

Тестовый и боевой режим

Checkout

Быстрый старт

Выставите счет покупателю

HEADERS

Перенаправьте клиента на полученную в ответе ссылку

Дождитесь уведомления об оплате

Сделать возврат покупателю

HEADERS

Дополнительно

Двухшаговый сценарий

Запросы, Статусы и Ошибки

Создание счета

Операция возврата

Операция подтверждения (для двухшагового сценария)

API

Быстрый старт

Запросы, Статусы и Ошибки

Платеж

Статус платежа

Завершение аутентификации

Подтверждение покупки

Статус подтверждения

Создание возврата

Статус возврата

Статус возвратов

Причины отклонения

Дополнительно

Серверные уведомления

HEADERS

Авторизация уведомлений

Уведомления PAYMENT, CAPTURE, REFUND

Уведомления BILL

Ответ → POST

Передача чека (54-ФЗ)

Описание чека

Токенизация

Выпуск платежного токена

Оплата платежным токеном

Выплаты

Тестовые данные