PaymentNut
Документация для разработчиков / Работа с API / Поиск транзакций
API PaymentNut позволяет программно осуществлять поиск транзакций по определенным критериям. По найденным транзакциям отдается подробная информация. Данный способ доступа к информации о транзакции удобен, когда требуется машинно получить и обработать данные без открытия Личного Кабинета.

URL: https://paymentnut.ru/api/transaction/v1
Метод отправки: POST, параметры передаются в теле запроса в формате ключ=значение
Аутентификация: используется HTTP Basic Auth – отправка логина и пароля в заголовке HTTP–запроса. В качестве логина используется Идентификатор проекта, в качестве пароля – API ключ. Оба этих значения доступны в настройках проекта Личного Кабинета его владельцу.
Поддерживаемые параметры:

Наименование параметра Описание Допустимые символы Минимальное, максимальное кол–во знаков Допустимые значения Обязателен Пример
search_type Тип поиска 1 – поиск всех транзакций проекта

2 – поиск транзакции по ее идентификатору

3 – поиск транзакций по идентификатору счета

4 – поиск транзакций по идентификатору продукта

5 – поиск транзакций по значению reference_1

6 – поиск транзакций по значению reference_2

7 – поиск транзакций по значению reference_3

8 – поиск транзакций по значению subscription_id (идентификатор подписки)

Да 5
search_value Значение критерия поиска [a-zA-Z0-9 ] 0, 32 Любые Обязателен для следующих типов поиска: 2, 3, 4, 5, 6, 7, 8 customer99
timestamp_1_operator Оператор сравнения переменной timestamp_1 [0-9] 1, 1 1 – меньше
2 – больше
Обязателен если задано значение timestamp_1 2
timestamp_1 Значение времени создания транзакции (transaction_date_created, Unix timestamp), в сочетании с оператором (timestamp_1_operator) [0-9] 10, 10 Любые Нет 1659312000
timestamp_2_operator Оператор сравнения переменной timestamp_2 [0-9] 1, 1 1 – меньше
2 – больше
Обязателен если задано значение timestamp_2 1
timestamp_2 Значение времени создания транзакции (transaction_date_created, Unix timestamp), в сочетании с оператором (timestamp_2_operator)

В сочетании с timestamp_1 возможно задать промежуток поиска.
[0-9] 10, 10 Любые Нет 1661904000
status Статус транзакции [0-9] 1, 1 1 – Ожидает аутентификации
2 – Отклонена
3 – Авторизована
4 – Завершена
5 – Отменена
Нет 4


Пример запроса (PHP и CURL):


$project_id='0D2239F1BBDAA3E4F98CFD0CDF2F9D73';
$api_key='1EA457132ABC39FBBA99A0EEFE0BF13D';
$url='https://paymentnut.ru/api/transaction/v1';

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_USERPWD, $project_id . ":" . $api_key);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,"search_type=5&search_value=customer99&timestamp_1_operator=2&timestamp_1=1659312000&timestamp_2_operator=1&timestamp_2=1661904000&status=4");

//в данном примере происходит поиск завершенных транзакций (status=4) со значением reference_1=customer99, в период между 1-ым и 31 августа 2022 г.

$response=curl_exec($ch);

$response=json_decode($response, true);
print_r($response);


Ответ

В случае успешного выполнения запроса и нахождения транзакций удовлетворяющих критерию поиска, возвращается JSON с response_code=1 и подмассивом response, который содержит ключи и значения с данными о транзакции (описания ключей (параметров) приводится ниже).

В случае, неуспешного выполнения запроса или отсутствия транзакций удовлетворяющих критерию поиска, возвращается JSON с response_code=0, response=x. Возможные значения response (ошибок) приводятся ниже.


Данные транзакции (response_code=1)

Параметр Значение
transaction_id Идентификатор транзакции
related_transaction_id Связанная транзакция (для транзакций с типом возврат)
payment_method Метод оплаты:

1 – банковской картой

2 – по QR коду через Систему быстрых платежей в РФ (СБП)
transaction_date_created Время создания (Unix timestamp)
transaction_date_last_declined Время отклонения (Unix timestamp)
transaction_date_authorized Время авторизации (Unix timestamp)
transaction_date_cancelled Время отмены (Unix timestamp)
transaction_date_completed Время подтверждения (Unix timestamp)
two_step_transaction Признак двухстадийной транзакции:

0 – Нет (одностадийная)

1 – Да (двухстадийная)
status Статус транзакции:

1 – Ожидает 3-D Secure аутентификации

2 – Отклонена

3 – Авторизована (при двухстадийных транзакциях)

4 – Завершена (при одностадийных транзакциях и при двухстадийных транзакциях после их подтверждения)

5 – Отменена (при двухстадийных транзакциях)
operation_type Тип транзакции:

1 – Оплата

2 – Возврат
transaction_failure_reason Причина отклонения
description Назначение платежа
amount Сумма
currency_code Код валюты (ISO 4217)
originator_object_type Связанный объект, которым инициализирована транзакция:

1 – Счет

2 – Продукт

3 – Вызов по API

4 – Подписка
originator_object_id Идентификатор связанного объекта
subscription_enabled Транзакция по подписке:

1 – Да

0 – Нет
subscription_initial_transaction Транзакция по подписке является установочным платежом:

1 – Да

0 – Нет (является регулярным платежом)
subscription_id Идентификатор подписки
is_subscription_transaction_retry Транзакция является повторной попыткой неудачного регулярного платежа по подписке:

1 – Да

0 – Нет
subscription_originating_failed_transaction_id Идентификатор неудачной регулярной транзакции по подписке, которой инициирована настоящая транзакция (если is_subscription_retry=1)
reference_1 Значение поля reference_1 (при вызове по API)
reference_2 Значение поля reference_2 (при вызове по API)
reference_3 Значение поля reference_3 (при вызове по API)
custom_data Значение поля custom_data (при вызове по API)
coupon_code Код купона акции
promotion_id Идентификатор акции кода купона
card_first_six Первые 6 цифр номера карты (значение может отсутствовать)
card_last_four Последние 4 цифры номера карты
card_type Платежная система карты
card_issuer Эмитент карты (значение может отсутствовать)
card_issuer_country Код страны эмитента карты (ISO 3166-1 alpha-2)
auth_code Код авторизации (значение может отсутствовать)
rrn_code Код RRN (значение может отсутствовать) при payment_method=1, уникальный идентификатор запроса в информационной системе при payment_method=2
transaction_email Email введеный при оплате

Транзакции по оплатам через СБП

При оплате по QR коду через Систему быстрых платежей в РФ (СБП) (payment_method=2), значения следующих переменных передаются пустыми: card_first_six, card_last_four, card_type, card_issuer, card_issuer_country, auth_code.


Возвращаемые ошибки (response_code=0, response=x)

Response Значение
1 Некорректное значение Идентификатора проекта в логине HTTP Basic Auth
2 Некорректное значение API ключа в пароле HTTP Basic Auth
3 Недопустимое значение поля search_type
4 Недопустимое кол–во символов в поле search_value
5 Идентификатор проекта или API ключ указан неверно или проект не может работать по API
7 Не указано значение search_value
8 Транзакции не найдены
9 Недопустимое кол–во символов в timestamp_1
10 Не задано значение для timestamp_1_operator, но задано значение для timestamp_1
11 Недопустимое кол–во символов в timestamp_2
12 Не задано значение для timestamp_2_operator, но задано значение для timestamp_2
13 Недопустимое значение status