Документация по веб-сервису PayPost.
Подключение к сервисной платформе.
Версия 1.0.0
Описание API.
* Обязательные поля указаны жирным шрифтом,
* Необязательные поля указаны курсивным шрифтом.
* Каждый url запроса должен заканчиваться слэшем ‘/’
Запросы.
Все запросы должны содержать заголовок (Header) Authorization, в значении которого должен присутствовать токен. Также в заголовок можно добавить язык, после чего описания ответов будут на соответствующем языке, например:
Authorization: Token 4443a98e3389a2d90b05da7eae342e5f61ffd39c
Accept-Language: en (default=ru, en, kk)
Ответы
Все ответы возвращаются в формате JSON. Если запрос не верный, то в ответе присутствует параметр detail в котором содержится пояснение ошибки, а также ответ имеет соответствующий статус, например:
401 Unauthorized - “не авторизован” { "detail": "Invalid token" (передан неверный токен) } |
404 Not Found - “не найдено” { "detail": "Not found." (не найден запрашиваемый объект) } |
В случае успешного запроса ответ обязательно содержит параметр ‘success’. Если поле ‘success’ является истиной (success=true), то данные результата переданы в параметре ‘result’. В противном случае, ошибки будут описаны в массиве ‘errors’, каждый элемент которого описывает ошибку более детально. Например:
{ "success": false, "errors": { "amount": ["This field is required."], "non_field_errors": ["payment is already exists"] } } *При ошибках валидации будут возвращены поля не прошедшие валидацию. Для остальных ошибок будет возвращено поле non_field_errors |
{ "success": true, "result": { "url": "http://ip_address/payment/e6da35ac-5ea0-48a5-b262-98e28e0a736f/", "amount": "200.00", "payment": "e6da35ac-5ea0-48a5-b262-98e28e0a736f" } } |
Данные тестового сервера
server | |
token | -- запросите у менеджера проекта -- |
postman_file | -- запросите у менеджера проекта -- |
key | -- запросите у менеджера проекта -- для тестового сервера используется “DEMO” |
данные карты | имя cardholder: CLIENT TEST 4189 7328 0417 1638 03/23 CVV 627 Блок сумма на тесте составляет 5 тенге. |
Админка с новым дизайном: https://testpay.post.kz/admin-panel - тестовый, https://pay.post.kz/admin-panel - боевой.
1. Платежи
Сервис онлайн-платежей органично сливается с вашим приложением и позволяет принимать все виды международных банковских карт обеспечивая полную поддержку технологий 3-D Secure.
1.1 Общий сценарий платежа
Сценарий платежа представляет собой последовательность запросов от приложения (подключаемая система) и ответов от сервиса (PayPost). Для проведения платежа приложению необходимо выполнить следующие действия:
method: POST
url: /api/v0/orders/payment/
Content-Type: Application/json
*После выполнения данного запроса у клиента есть 3 попытки по 5 минут для произведения оплаты.
Параметры запроса
поле | описание |
amount | Сумма которую нужно списать с карточки |
back_link | Сервис даст возможность пользователю вернутся на указанный url, после завершения транзакции |
payment_webhook | Сервис уведомит приложение о завершении платежа (сделает GET запрос на данный URL) |
email пользователя на который будет выслано уведомление в виде чека | |
language | язык отображения страницы оплаты default=ru (kk, en) |
currency | Валюта платежа default=KZT (KZT, ) |
type | способ оплаты (card, simcard, wallet) default =’card’ Оплата балансом телефона (simcard) на данный момент недоступна) |
phone_number | номер абонента с которого должен списаться баланс. обязательно должен присутствовать, если способ оплаты производится через “simcard” формат: начинается с +7, далее следуют 10 цифр номера. например +77776665544 |
order_iin | ИИН плательщика (именно ИИН, не БИН) |
{ "amount": "200", "back_link": "https://ticketon.kz/back_link", "payment_webhook": "https://ticketon/kz/webhook", "email": "card_holder@gmail.com" } | |
Параметры ответа в случае успешного запроса
поле | описание |
amount | Сумма списания (та что была передана при запросе) |
payment | Уникальный ID платежа в системы PayPost |
url | URL для произведения оплаты, на который нужно перенаправить клиента (покупатель) |
{ "success": true, "result": { "amount": "200.00", "payment": "e6da35ac-5ea0-48a5-b262-98e28e0a736f", "url": "https://pay.post.kz/payment/e6da35ac-5ea0-48a5-b262-98e28e0a736f/" } } | |
Параметры ответа в случае не успешного запроса
поле | описание |
field_name | Поле не прошедшая валидацию (отсутствие поля, тип поля и т.д) |
{ "success": false, "errors": { "amount": ["This field is required"] } } | |
Приложение должно перенаправить пользователя (клиент проводящий оплату) на указанный URL, который был передан в параметре url ответа с описанного в 1.1.1. После чего пользователь должен произвести оплату. То есть на данном этапе система PayPost взаимодействует с покупателем.
После завершения платежа сервис (PayPost) сделает GET запрос на указанный url, который был передан приложением в параметре payment_webhook в 1.1.1. (Рассчитываем на то, что приложение знает для какого заказа был произведен платеж. То есть веб-хук будет содержать ID заказа). Например:
payment_webhook = "https://ticketon.kz/api/post_link/<order_id>" |
method: GET
url: /api/v0/orders/payment/<payment_id>/f
Content-Type: Application/json
Параметры ответа в случае успешного запроса
поле | описание |
id | есть <payment_id> - Уникальный ID платежа сервиса |
amount | сумма платежа |
email введенный пользователем при оплате | |
currency | валюта оплаты |
date_created | дата создания объекта оплаты в секундах |
status | статус оплаты тип которого Integer в диапазоне 1-6. 1:Waiting – Ожидает завершения оплаты пользователем 2:Expired – Истекло время ожидания оплаты (5 минут) 3:Canceled – Пользователь нажал назад на странице оплаты для ввода данных карт 4:Paid – Оплата завершена успешно 5:Failed – Возникла ошибка при оплате (часто из за недостачи средств или запрета проведений интернет-транзакций банком пользователя) 6:Confirmed – Был произведен перевод средств на транзитный счет клиента (*Клиент – пользователь (Ticketon) который использует сервис PayPost ) 7: Full Refund - Был произведён полный возврат денег на карту оплаты 8: Partial Refund - Был произведён частичный возврат денег на карту оплаты 9: это FULL_REFUND_ACCOUNT_STATUS, то есть деньги в колвир посадили, после чего сделали возврат на карту 10: это PARTIAL_REFUND_ACCOUNT_STATUS, то же самое, но возврат частичный |
used_amount | Сумма переведенная на транзитный счет |
refund_amount | Сумма, которая была возвращена. |
is_kazpost_card | Была ли оплата картой казпочты или нет (True/False) |
rrn | Референс транзакции |
cardholder_name | ФИО владельца карты, что вводится на странице оплаты |
card_pan | Зашифрованный номер карты (первые 6 и последние 4 цифры) |
{ "success": true, "result": { "status": 6, "id": "e6da35ac-5ea0-48a5-b262-98e28e0a736f", "amount": "10000.00", "refund_amount": "3200.00", "used_amount": "6800.00", "email": "login@gmail.com", "date_created": "1500489574", "currency": "KZT", "is_kazpost_card": "true", "rrn": "917085863611", "cardholder_name": "TEST TESTOV", "card_pan": "418974xxxxxx7605" }, } | |