Протокол Merchant API

Введение

Этот документ является коммерческим документом, который представлен по соглашению обеих сторон и описывает методы и запросы в биллинговой системе. Все данные принимаются POST методом Ответ возвращается в формате JSON. Обращение производится данными запросами check, pay, и check_status

Описание каждого запроса:

check - метод, который должен выполниться до использования метода pay. Используется для получения дополнительной информации от Merchant и проверки возможности реальной транзакции.

pay - метод, который должен выполниться после того как метод (Response) вернет значение True. Данный метод используется для того, чтобы выполнилась реальная транзакция.

check_status - метод, который должен выполниться после pay. Используется для получения информации от транзакции он возвращает true или false

Описание

Шаг 1. Первым делом вы должны подготовить 3 - url: окончания адресов должны быть

1) .../api/payment/check

2) .../api/payment/pay

3) .../api/payment/check_status

Шаг 2. Для безопасности каждый запрос будет отправлен с токенам. Токен предоставим во время интеграции

Шаг 3. Каждый платеж в системе Мерчанта должен иметь уникальный идентификатор, который передается Платежной организации в переменной agent_transaction_id – целое число длиной до 25 знаков. По данному идентификатору производится дальнейшая сверка взаиморасчетов и решение спорных вопросов.

Шаг 4. При проведении платежа сумма к зачислению передается в переменной amount – дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). Если сумма представляет целое число, то оно дополняется точкой и нулями, например – «1000.00».

Шаг 5. Идентификатор клиента (номер лицевого счета, телефона, логин и т.д.) передается в переменной account – строка, содержащая буквы, цифры и спецсимволы, длиной до 200 символов. После отправкой запроса в сервис Мерчанта должен произвести проверку корректности в соответствии с регулярным выражением

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

Вы должны подготовить свой сервер для получение запросов от нашего сервера. Мы будем отправляет "check" запрос. Описание параметров будут ниже

Все данные будут отправляться методом POST

{{url}}/api/payment/check

token - который мы вам предоставим в процессе интеграции

Параметры запроса (request):

Параметр Тип Описание
method string REQUEST
merchant_id string Уникальный идентификатор поставщика
account string Аккаунт или номер телефона
agent_transaction_id Int Уникальный идентификатор биллинговые системы(Наш уникальный ID)
amount double Сумма платежа (валюта от договора)
params object Объект с параметрами метода. Если в данном методе нет параметров, поле можно опустить

Параметры ответа (response):

Параметр Тип Описание
succes:true boolean Ответ при успешном запросе
succes:false boolean Ответ при не успешном запросе

Headers

Content-Type application/json
token {{token}}

Body raw (application/json)

{ "method": "check", "merchant_id": 1, "account": "123456", "agent_transaction_id 123456789, "amount": 1000.00, "params" : {} }

Example RequestCheck

'{

curl --location --request POST '{{url}}/api/payment/check  ' \
--header 'Content-Type: application/json' \
--header 'token: {{token}}' \
--data-raw '{
    "method": "check",
    "merchant_id": 1,
    "account": "123456",
    "agent_transaction_id "160014461782",
    "amount": 1000.00,
    "params" : {}
}'

Example Response 200 OK

Body
{
    "succes" : true,
}

POST pay

{{url}}/api/payment/pay

token - который мы вам предоставим в процессе интеграции

Параметры запроса (request):

Параметр Тип Описание
method string REQUEST
merchant_id string Уникальный идентификатор поставщика
account string Аккаунт или номер телефона
amount double,Int Сумма платежа (валюта от договора)
params object Объект с параметрами метода. Если в данном методе нет параметров, поле можно опустить

Параметры ответа (response):

Параметр Тип Описание
state: 1 string Ответ от сервера как прошло транзакция
transaction_id string Идентификатор транзакции
"state:1" - Оплата успешно

 "state:2" - В процессе

 "state:  " - С любым другим числом означает ошибку

Headers

Content-Type application/json
token {{token}}

Body raw (application/json)

{ "method": "pay", "merchant_id": 1 , "account": "123456", "amount": 1000.00, "params" : {} }

Example Request

'{

curl --location --request POST '{{url}}/api/payment/pay  ' \
--header 'Content-Type: application/json' \
--header 'token: {{token}}' \
--data-raw '{
    "method": "pay",
    "merchant_id": 1,
    "account": "123456", 
    "amount": 1000.00,
    "params" : {}
}'

Example Response 200 OK

Body
{
  "state": 1,
  "transaction_id": "87967231"
}

POST check status

{{url}}/api/payment/check_status

token - который мы вам предоставим в процессе интеграции

Параметры запроса (request):

Параметр Тип Описание
methodstringv REQUEST
transaction_idstring Идентификатор транзакции

Параметры ответа (response):

Параметр|Тип|Описание

state: 1|string|Ответ от сервера как прошло транзакция

Headers

Content-Type application/json
token {{token}}

Body raw (application/json)

{
  "method": "check_status",
  "transaction_id": "87967231"
}

Example Request

'{curl --location --request POST '{{url}}/api/payment/check_status' \
--header 'Content-Type: application/json' \
--header 'token: ' \
--data-raw '{
  "method": "check_status",
  "transaction_id": {{transaction_id}}
}'

Example Response

{
  "state": 1
}
"state:1" - Проверка статуса успешно выполнено

 "state:2" - В процессе

 "state:  " - С любым другим числом означает ошибку

скачать postman_collection