«QIWI Казахстан»

Схема работы

В проведении каждого платежа с использованием «QIWI Казахстан» задействуются веб-сервис мерчанта, один из интерфейсов и платeжная платформа JetPay, а также сервис «QIWI Казахстан».

Рис.: Схемы работы при оплате и выплате через Gate

Рис.: Схема работы при оплате через терминал «QIWI Казахстан», а также через электронный кошелек

Основные операции

	Интерфейсы			Суммы, KZT		Время
	Payment Page	Gate	Dashboard	минимум	максимум	базовое	предельное
Оплата						*	30 суток
Выплата						*	24 часа

* Подробную информацию уточняйте у своего курирующего менеджера.

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

Сценарии использования

Проведение оплат с использованием метода «QIWI Казахстан» выполняется с обращением пользователя к физическому терминалу «QIWI Казахстан», а проведение выплат — с уведомлением пользователей через веб-сервис мерчанта..

Рис.: Оплата через Gate с использованием физического терминала или электронного кошелька

Рис.: Выплата через Gate

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

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

Для оплаты через Gate с использованием платeжного метода «QIWI Казахстан» со стороны веб-сервиса необходимо:

1. Обработать запрос на проверку существования лицевого счeта пользователя.
2. Отправить ответ с информацией о существовании лицевого счeта пользователя.
3. Обработать запрос на получение идентификатора платежа на стороне веб-сервиса.
4. Отправить ответ с идентификатором платежа.
5. Принять оповещение о результате оплаты.

Информация о формате запросов и параметрах инициирования оплат через Gate при работе с методом «QIWI Казахстан» и о формате оповещений о результатах оплат приведена далее.

Формат запросов

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

1. Запрос verify для проверки существования лицевого счeта пользователя отправляется методом POST на заданный URL веб-сервиса.
2. Запрос содержит следующие обязательные параметры:
   • type — тип операции на стороне веб-сервиса, значение параметра всегда verify;
   • customer_id — идентификатор пользователя в системе мерчанта;
   • project_id — идентификатор проекта, полученный от JetPay при интеграции;
   • signature — подпись запроса.

   Рис.: Пример запроса на проверку существования лицевого счeта пользователя

   {
      "type":"verify",
      "project_id":111,
      "customer_id":"johndoe@example.com",
      "signature":"lY0LT8AzpR7zGce5qfYGacOuYlHGWqkMcQlqmjlsDDZI2gVcE1qVeWANnkIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
   }

3. Ответ на запрос verify должен быть отправлен синхронно и содержать следующие обязательные параметры:
   • code — код ответа на запрос;
   • currency — валюта платежа в формате ISO-4217 alpha-3.

   Табл. 1. Допустимые коды ответов

   Код	Описание
   0	Операция успешна
   400	Ошибка подписи
   404	Лицевой счeт пользователя не существует
   500	Общая ошибка, причина должна быть описана в необязательном параметре message

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

   {
      "code":0,
      "currency":"KZT",
      "additional_customer_id": "HFVDW42345"
   }

Формат оповещений

Для оповещений о результатах оплат с применением метода «QIWI Казахстан» используется стандартный формат, описание которого представлено в разделе Оповещения (callbacks) в Gate.

В данном случае оповещение свидетельствует о том, что в рамках проекта 238 проведена успешная оплата в размере 20,00 KZT.

{
        "project_id": 238,
        "payment": {
            "id": "1554967098",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "method": "Qiwi Kz Terminal",
            "sum": {
                "amount": 2000,
                "currency": "KZT"
            },
            "description": ""
        },
        "account": {
            "number": "user9876"
        },
        "operation": {
            "id": 36425000001206,
            "type": "sale",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "created_date": "2019-04-11T07:18:19+0000",
            "request_id": "25f3114242a16ab1e010ebab4fe816b9d105ff33b90281",
            "sum_initial": {
                "amount": 2000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "KZT"
            },
            "provider": {
                "id": 1197,
                "payment_id": "999990000001a1",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "HRcDJN84ghAJL2hPW9yUbVMm7SRPewQJuH+mz4gcipXc8sI
                         dToQunzSUEiy7w5vA3+MVIO8xHSNsQB5qCCm5kXA=="
    }
}

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

• Общий порядок интеграции
• Подписывание и проверка подписи
• Типы платежей, операции и платежи
• Статусы операций и коды ответов

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

Для оплаты через Gate с использованием платeжного метода «QIWI Казахстан» со стороны веб-сервиса необходимо:

1. Обработать запрос на проверку существования лицевого счeта пользователя.
2. Отправить ответ с информацией о существовании лицевого счeта пользователя.
3. Обработать запрос на получение идентификатора платежа на стороне веб-сервиса.
4. Отправить ответ с идентификатором платежа.
5. Принять оповещение о результате оплаты.

Информация о формате запросов и параметрах инициирования оплат через Gate при работе с методом «QIWI Казахстан» и о формате оповещений о результатах оплат приведена далее.

Формат запросов

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

1. Запрос verify для проверки существования лицевого счeта пользователя отправляется методом POST на заданный URL веб-сервиса.
2. Запрос содержит следующие обязательные параметры:
   • type — тип операции на стороне веб-сервиса, значение параметра всегда verify;
   • customer_id — идентификатор пользователя в системе мерчанта;
   • project_id — идентификатор проекта, полученный от JetPay при интеграции;
   • signature — подпись запроса.

   Рис.: Пример запроса на проверку существования лицевого счeта пользователя

   {
     "type": "verify",
     "project_id": 111,
     "customer_id": "johndoe@example.com",
     "signature": "lY0LT8AzpR7zGce5qfYGacOuYlHG...kIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
   }

3. Ответ на запрос verify должен отправляться синхронно и содержать следующие обязательные параметры:
   • code — код ответа на запрос;
   • currency — валюта платежа в формате ISO-4217 alpha-3.

   Табл. 3. Возможные коды ответов

   Код	Описание
   0	Операция успешна
   400	Ошибка подписи
   404	Лицевой счeт пользователя не существует
   500	Общая ошибка, описание причины может содержаться в необязательном параметре message

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

   {
      "code":0,
      "currency":"KZT",
      "additional_customer_id": "HFVDW42345"
   }

Формат оповещений

В оповещениях о результате оплаты с использованием метода «QIWI Казахстан» используется типовой формат, который описан в разделе Оповещения (callbacks) в Gate.

В следующем примере в оповещении содержится информация о том, что в рамках проекта 238 проведена оплата в размере 20,00 KZT.

{
        "project_id": 238,
        "payment": {
            "id": "1554967098",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "method": "Qiwi Kz Terminal",
            "sum": {
                "amount": 2000,
                "currency": "KZT"
            },
            "description": ""
        },
        "account": {
            "number": "user9876"
        },
        "operation": {
            "id": 36425000001206,
            "type": "sale",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "created_date": "2019-04-11T07:18:19+0000",
            "request_id": "25f3114242a16ab1e010ebab4fe816b9d105ff33b90281",
            "sum_initial": {
                "amount": 2000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "KZT"
            },
            "provider": {
                "id": 1197,
                "payment_id": "999990000001a1",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "HRcDJN84ghAJL2hPW9yUbVMm7SRPewQJuH+mz4gcipXc8sI
                         dToQunzSUEiy7w5vA3+MVIO8xHSNsQB5qCCm5kXA=="
    }
}

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

• Общий порядок интеграции
• Подписывание и проверка подписи
• Типы платежей, операции и платежи
• Статусы операций и коды ответов

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

Для выплаты через Gate с использованием метода «QIWI Казахстан» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL JetPay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.

Информация о формате запросов и параметрах инициирования выплат с применением метода «QIWI Казахстан» через Gate, а также о формате оповещений о результатах выплат приведена далее. Общая информация о работе с API — в разделе Использование API Gate.

Формат запросов

При формировании запросов на выплату с применением метода «QIWI Казахстан» необходимо учитывать следующее:

1. Должен использоваться запрос /v2/payment/wallet/qiwi-kz/payout, отправляемый методом POST. Этот запрос относится к группе запросов для проведения платежей с использованием электронных кошельков /v2/payment/wallet/{payment_method}/payout.
2. В запросе должны присутствовать следующие объекты и параметры:
   • general — объект, содержащий основные сведения о запросе:
     • project_id — идентификатор проекта, полученный от JetPay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после определения всех параметров запроса. (Подробнее см. раздел Использование подписи к данным.);
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;
     • ip_address — IP-адрес устройства пользователя;
     • email — адрес электронной почты пользователя;
     • first_name — имя пользователя;
     • last_name — фамилия пользователя;
   • account — объект, содержащий сведения о счeте пользователя:
     • number — номер QIWI Кошелька;
   • payment — объект, содержащий сведения о выплате:
     • amount — сумма выплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют;
     • currency — код валюты выплаты в формате ISO-4217 alpha-3.
3. Валютой платежа может быть только KZT.
4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Вот пример данных из запроса на выплату с использованием метода «QIWI Казахстан»:

{
    "general": {
        "project_id": 35,
        "payment_id": "test_123",
        "signature": "kUi2x9dKHAVNU0FY"
    },
    "customer": {
        "ip_address": "198.51.100.47",
        "id":"12345",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "account": {
        "number": "9182221133"
    },
    "payment": {
        "amount": 100,
        "currency": "KZT"
    }
}

Формат оповещений

Для оповещений о результатах выплат с применением метода «QIWI Казахстан» используется стандартный формат, описание которого представлено в разделе Оповещения (callbacks) в Gate.

В следующем примере в оповещении содержится информация о том, что в рамках проекта 1234 проведена выплата в размере 100,00 KZT.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_48",
        "type": "payout",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "qiwi-kz",
        "sum": {
            "amount": 10000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "id": 29,
        "type": "payout",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

В следующем примере содержится информация об отклонении выплаты.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_48",
        "type": "payout",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "qiwi-kz",
        "sum": {
            "amount": 10000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "id": 29,
        "type": "payout",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "created_date": "2022-03-25T11:19:53+0000",
        "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb",
        "sum_initial": {
            "amount": 10000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "KZT"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnlVlf155QSlXJKR4m8C4z2iFYv58P4VnHANu445/jmY+g=="
}

Дополнительные материалы

Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:

• Общий порядок интеграции
• Подписывание и проверка подписи
• Типы платежей, операции и платежи
• Статусы операций и коды ответов

Информация о проведении выплат отображается в разделах Платежи и Мануальные платежи интерфейса Dashboard.

Более подробная информация о проведении выплат через Dashboard представлена в разделе Проведение выплат.

Как и при работе с другими платежными методами, которые предоставляет JetPay, при использовании этого метода доступны разные способы анализа информации о платежах и операциях.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (dashboard.jetpay.kz), в том числе с помощью аналитических панелей в разделе Аналитика.

Также можно выгружать необходимую информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:

• Dashboard позволяет выгружать данные в формате CSV с помощью инструментов в разделе Отчеты. При этом можно выполнять разовые и периодические выгрузки информации на локальный компьютер.
• Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы к конечной точке /operations/get.

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