Выставление счета для Кабинета мерчанта

  1. Авторизация мерчанта
  2. Выставление счета на оплату
  3. Запрос статуса и данных по операции
  4. Запрос чека (массив)
  5. Запрос чека (PDF)
  6. Коды ошибок (error_code)
  7. Возможные коды состояния HTTP

1. Авторизация мерчанта

Авторизация происходит методом POST запроса URL: {{url}}/v1/auth

Входные параметры:

Headers:

Параметр Значение
Content-Type application/json
language ru (по умолчанию)
Time-Zone Временная зона - по умолчанию время указано в UTC-0 (Пример: Asia/Almaty)

Body:

Параметр Тип Описание
login string Логин Субъекта
password string Пароль мерчанта

Возвращаемые параметры:

Параметр Тип Описание
parent_login string Логин родительского субъекта
subject_type int Тип авторизованного субъекта
country int ID страны
id int ID авторизованного субъекта
login string Логин авторизованного субъекта
status int Статус авторизованного субъекта
roles массив со string внутри Роли авторизованного субъекта
assignments string Внутренняя система ролей
token string Уникальный авторизационный токен
email string Почта авторизованного субъекта
created_at string Дата и время авторизации

Пример запроса:

{
    "login":"merchant_name",
    "password":"password"
}

Пример успешного ответа:

HTTP status code: 200 OK - Успешно. Запрошенный ресурс был найден и передан в теле ответа.

{
    "parent_login": SystemAgent,
    "subject_type": 3000,
    "country": 1,
    "id": 374818,
    "login": "merchViktor,
    "status": 1,
    "roles": [
        "rMerchant",
        "rMerchantSmpp"
    ],
    "assignments": null,
    "token": "jwt ...",
    "email": null,
    "created_at": "2021-07-30T08:55:31+0000",
    "identified": 0
}

Параметр “token” - сгенерированный авторизационный токен. Предназначен для последующих запросов, на каждом последующем шаге необходимо передавать токен в headers параметр authorization, в значение (value).

Время жизни авторизационных данных:
Сессия: 24 минуты
JWT: 24 часа
Сгенерированный токен с кабинета: 12 месяцев

2. Выставление счета на оплату

Выставление счета на оплату происходит методом POST запроса URL: {{url}}/v1/invoice/create
На данном шаге происходит отправка сообщения на номер абонента с кодом для подтверждения операции. И в системе wooppay формируется операция на 11 статусе (описание статусов ниже).

Входные параметры:

Headers:

Параметр Значение
Content-Type application/json
language ru (по умолчанию)
Time-Zone Временная зона - по умолчанию время указано в UTC-0 (Пример: Asia/Almaty)
Authorization Полученный токен для авторизации

Body:

Параметр Тип Описание Обязательный параметр
reference_id string Индивидуальный номер операции (общий идентификатор операции между вашей и нашей системой), необходимо генерировать новый при каждой оплате Да
amount double Сумма пополнения Да
death_date YYYY-MM-DD hh:mm:ss Дата закрытия инвойса Нет
merchant_name string Логин мерчанта (это ваш логин, получаете от Wooppay и используете на шаге авторизации) Нет
request_url string Запрос, который выполнит Wooppay после успешной оплаты. Спецсимволы - необходимо url-кодировать. Возможно отправлять GET и POST запросы. Пример POST {“url”:“https://www.test.com/test.php",“type”:"POST”} Нет
back_url string Адрес, на который будет переадресован, пользователь после оплаты (можете указать ваш сайт) Нет
option integer Тип инвйоса, в текущем кейсе используется 4/5, это тип инвойса при котором происходит привязка карты (при выборе option 4 будет предоставлена возможность оплаты и с карты и с кошелька с последующей привязкой, при выборе option 5 будет возможность оплаты только с карты с последующей ее привязкой) Да
description string Описание. Данный параметр нужен для обмена данными между Wooppay и вашей системы Нет
user_phone string Номер телефона пользователя Да
service_name string Системное имя услуги (указывается имя мерчанта и добавляется «_invoice», например имя мерчанта wooppay, сервис выглядит следующим образом wooppay_invoice) Нет

requestUrl - адрес на котором сервер мерчанта ждет уведомления об успешной оплате инвойса. По умолчанию выполняется GET запрос на указанный URL.

Если необходимо выполнить POST запрос, то в requestUrl нужно передать JSON с параметрами url и type, где url — url на который ожидается уведомление, type — тип запроса. Уведомление отработает, сразу, как пользователь выполнит оплату заказа и операция будет проведена в системе WOOPPAY. Запросы выполняются 120 раз, каждую минуту, до получения от сервера мерчанта ответа в виде JSON {“data”:1}. После истечения 120 попыток — запросы прекращаются.

Возвращаемые параметры:

Параметр Тип Описание
operation_url string Ссылка для оплаты инвойса
operation_id string Индивидуальный номер операции
invoice_id string ID инвойса
key string Ключ необходимый для оплаты инвойса
replenishment_id string ID операции продажи в системе Wooppay (потребуется передать на следующий шаг для проведения операции)

Пример запроса:

{
  "reference_id" : "{{$timestamp}}",
  "amount" : "100",
  "user_phone": "77771545454",
  "email": "example@example.com",
  "merchant_name" : "merchViktor",
  "request_url": {
          "url": "https://domain.ltd/",
          "type":"POST"},
  "back_url": "https://www.test.wooppay.com",
  "description": "nothing",
  "death_date": "2025-12-25 22:42:03",
  "option": "4"
}

Пример успешного ответа:

HTTP status code: 200 OK - Успешно. Запрошенный ресурс был найден и передан в теле ответа.

{
    "operation_url": "https://www.test.wooppay.com/invoice/operation?id=323756&key=e987671f8ab9aaa007a95a6c1741cec7",
    "response": {
        "operation_id": "51079950",
        "replenishment_id": "51076676",
        "invoice_id": "323756",
        "key": "e987671f8ab9aaa007a95a6c1741cec7"
    }
}

3. Запрос статуса и данных по операции

Данный метод нужен для запроса статуса и данных по операциям. GET: {{url}}/v1/history/transaction/get-operations-data

Входные параметры:

Headers:

Параметр Значение
Content-Type application/json
language ru (по умолчанию)
Time-Zone Временная зона - по умолчанию время указано в UTC-0 (Пример: Asia/Almaty)
Authorization Полученный токен для авторизации

Body:

Параметр Тип Описание Обязательный параметр
operation_ids array operation_id полученный на 2 шаге создания операции (методом: {{url}}/v1/invoice/create) Да

Возвращаемые параметры:

В ответ возвращается массив с данными по каждой операции. Если операция не принадлежит субъекту или по ней нет данных то в ответе не приходят данные.

Параметр Описание
operation_id ID операции
status Статус операции
amount Сумма операции
external_id Общий идентификатор операции (Внешний ID для wooppay)

Возможные статусы операций:

Статус Описание
11 Новая операция
12 На рассмотрении
14 Проведена
17 Отменена
19 Ожидает проведения
20 Удалена

Пример запроса:

{
  "operation_ids": [
    "51077610"
  ]
}

Пример успешного ответа:

[
    {
        "operation_id": 51079950,
        "status": 14,
        "amount": 100,
        "external_id": "1627460470"
    }
]

Примечание:

Необходимо добавить в финальные статусы 19. Если WOOPPAY прислали уведомление, статус операции в системе 19 или 14 — значит операция уже проведена или точно будет проведена.

4. Запрос чека (массив данных по операции)

Запрос чека по операции происходит методом GET запроса URL: {{url}}/v1/history/receipt/51077610

Запрос должен происходить по operation_id полученный на 2 шаге создания операции (методом: {{url}}/v1/invoice/create)

Входные параметры:

Headers:

Параметр Значение
Content-Type application/json
language ru (по умолчанию)
Time-Zone Временная зона - по умолчанию время указано в UTC-0 (Пример: Asia/Almaty)
Authorization Полученный токен для авторизации

Body не требуется.

Возвращаемые параметры:

Параметр Тип Описание
id int ID операции
operator_title string Юридическое имя оператора
operator_bin int БИН оператора
login int Логин (номер телефона указанный при оплате)
time string Время проведения платежа
merchant_title string Юридическое имя мерчанта
merchant_bin int БИН мерчанта
service_title string Название сервиса
ident: массив с объектами json Поля с данными
1. title 2. value 1. string 2. string 1. Название поля 2. Значение поля
amount float Сумма платежа
commission float Комиссия
admit float Сумма, на которую пополнится счет
vat float НДС
emitent float Имя эмитента
agent string Имя специалиста
operation_type int Тип операции
transaction объект json Поля с данными
1. status 2. type 1. int 2. int 1. Статус операции 2. Тип операции
linked_operations массив со string внутри Операции, связанные с данной операцией

Пример запроса:

GET: {{url}}/v1/history/receipt/51079950

Пример успешного ответа:

HTTP status code: 200 OK - Успешно.

{
    "id": 51077610,
    "operator_title": "ТОО \"WOOPPAY\" (ВУППЭЙ)",
    "operator_bin": "120340004314",
    "login": "992985390012",
    "time": "2021-07-28T08:21:23+0000",
    "merchant_title": "Имя мерчанта",
    "merchant_bin": "111111111111",
    "service_title": "Оплата счета на сайте «имя сайта»",
    "ident": [
        {`
            "title": "f",
            "value": null
        }
    ],
    "amount": 10,
    "commission": 0,
    "admit": 10,
    "vat": 0,
    "emitent": "EUBank01",
    "agent": "Агент",
    "operation_type": 334,
    "transaction": {
        "parentId": 51077611,
        "status": 14,
        "type": 334
    },
    "linked_operations": [
        "51077611"
    ]
}

5. Запрос чека (в формате PDF)

Входные параметры:

Headers:

Параметр Значение
Content-Type application/json
language ru (по умолчанию)
Time-Zone Временная зона - по умолчанию время указано в UTC-0 (Пример: Asia/Almaty)
Authorization Полученный токен для авторизации

Body не требуется.

Пример запроса:

GET: {{url}}/v1/history/receipt/pdf/51077610

В ответе выходит готовый чек в формате PDF.

Коды ошибок (error_code):

Код Описание
1111 Превышены лимиты при создании новой операции
1140 Неверный тип операции
1143 Неверный статус операции
1156 Операция запрещена
1509 Неверный СМС-код
1510 Превышено количество попыток ввода
1512 На балансе недостаточно средств
1516 Номер не зарегистрирован в MFS
1518 Недостаточно средств
1522 Неверный тарифный план
1604 Ошибка взаимодействия с оператором
1606 На балансе недостаточно средств
1607 Номер клиента не найден в системе MFS
1608 Не потрачен стартовый\бонусный баланс
1609 Неверный тарифный план
1611 Недоступно для юр.лиц
1612 Недоступно для абонентов в роуминге
1613 Данная услуга вам недоступна. Обратитесь к оператору
2010 Некорректная структура пакета
3013 Недостаточно полномочий для выполнения операции
3027 Операция с данным Id была использована ранее
3037 Неверный код подтверждения
3038 Ваш номер уже занят процессом оплаты, завершите оплату или подождите 5 минут
3040 Превышено количество попыток ввода
3068 Операция недоступна
3069 Операция не найдена
3077 Номер не принадлежит оператору
4001 Не классифицированная ошибка
4007 Платёж запрещён
4009 Технические проблемы на стороне мерчанта
4010 Мерчант временно недоступен
4013 Неверный формат номера
5001 Сервис не найден
5002 Проверка на валидацию не прошла
5011 Операция не найдена
5012 Не найдена дочерняя операция

Возможные коды состояния HTTP:

HTTP status code 201 Created
Ресурс был успешно создан в ответ на POST-запрос. Заголовок Location содержит URL, указывающий на только что созданный ресурс.

HTTP status code 400 - Bad Request
Неверный запрос. Может быть связано с разнообразными проблемами на стороне пользователя, такими как неверные JSON-данные в теле запроса, неправильные параметры действия, и.т.д.

HTTP status code 403 - Forbidden
У вас нет прав для пользования данным действием или ресурсом.

HTTP status code 404 - Not Found
Не удается найти данные согласно запросу.

HTTP status code 422 - Unprocessable Entity
Проверка данных завершилась неудачно. Подробные сообщения об ошибках смотрите в теле ответа.

HTTP status code 500 - Internal server error
Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе.