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

Авторизация мерчанта
Выставление счета на оплату
Запрос статуса и данных по операции
Запрос чека (массив)
Запрос чека (PDF)
Коды ошибок (error_code)
Возможные коды состояния 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
Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе.