Документация по веб-сервису 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

https://testpay.post.kz/ 

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). Для проведения платежа приложению необходимо выполнить следующие действия:

  1. Получить от сервиса уникальный ID и URL оплаты.
  2. Выполнить         перенаправление на указанный URL.
  3. Обработать запрос сервиса PayPost.
  4. Проверить статус оплаты.
  5. Возврат средств пользователю (владельцу карты, в разработке)

1.1.1 Получить от сервиса уникальный ID и URL оплаты

method: POST

url: /api/v0/orders/payment/

Content-Type: Application/json

*После выполнения данного запроса у клиента есть 3 попытки по 5 минут для произведения оплаты.

Параметры запроса

поле

описание

amount

Сумма которую нужно списать с карточки

back_link

Сервис даст возможность пользователю вернутся на указанный url, после завершения транзакции

payment_webhook

Сервис уведомит приложение о завершении платежа (сделает GET запрос на данный URL)

email

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"

}

Параметры ответа в случае успешного запроса

  • данные результата содержатся в поле “result”.

поле

описание

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/"

     }

  }

Параметры ответа в случае не успешного запроса

  • данные результата содержатся в поле “errors”.

поле

описание

field_name

Поле не прошедшая валидацию (отсутствие поля, тип поля и т.д)

{

    "success": false,

    "errors": {

         "amount": ["This field is required"]

     }

}

1.1.2 Выполнить перенаправление на указанный URL.

Приложение должно перенаправить пользователя (клиент проводящий оплату) на указанный URL, который был передан в параметре url ответа с описанного в 1.1.1. После чего пользователь должен произвести оплату. То есть на данном этапе система PayPost взаимодействует с покупателем.

1.1.3 Обработать запрос системы PayPost

После завершения платежа сервис (PayPost) сделает GET запрос на указанный url, который был передан приложением в параметре payment_webhook в 1.1.1. (Рассчитываем на то, что приложение знает для какого заказа был произведен платеж. То есть веб-хук будет содержать ID заказа). Например:

payment_webhook = "https://ticketon.kz/api/post_link/<order_id>"

1.1.4 Проверить статус оплаты

method: GET

url: /api/v0/orders/payment/<payment_id>/f

Content-Type: Application/json

Параметры ответа в случае успешного запроса

  • данные результата содержатся в поле “result”.

поле

описание

id

есть <payment_id> - Уникальный ID платежа сервиса

amount

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

email

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"

   },

}