Отчеты
Общие положения по API¶
Все запросы отправляются по протоколу HTTPS с использованием метода POST.
Формат запросов и ответов — JSON.
Структура JSON-ответа всегда представляет собой dict (ассоциативный массив).
Если присутствует ключ err_code или error, запрос не завершен. В этом случае параметр err_code и error в ответе представляет собой сообщение с описанием ошибки.
Основные коды ошибок:
Authorization token required– параметрtokenне передается в заголовке запросаInvalid auth token– URL-адресtokenявляется либо недействительным, либо устаревшимMerchant not found– мерчант не найденyou have no access to this report– либоreport_idнедействителен, либо у вас нет доступа к отчету
Пример ответа в случае ошибки
{
"error": "Authorization token required",
"err_code": "Authorization token required"
}
Токен авторизации должен быть отправлен в HTTP-заголовке Authorization вашего запроса.
Пример запроса с заголовком, содержащим access token
curl 'https://pay.payme.uz/api/extend/company/report/' \
-H "Authorization: Token 4cDY6LgviVN85g70eDHXygrmYTourFAT"
Аутентификация¶
Перед получением данных из отчета необходимо получить токен доступа.
Запрос JSON POST следует отправить на конечную точку: https://pay.payme.uz/authorizer/token/application/get
Parameters of authentication request
| Параметр | Обязательный | Тип | Описание | Пример |
|---|---|---|---|---|
application_id |
обязательный | string(20) | Идентификатор компании. Пожалуйста, обратитесь в службу поддержки Payme для получения идентификатора и секретного ключа. | 1234 |
date |
обязательный | string(1024) | Дата в любом формате. Дата является солью для хеша подписи sha512 | 2020-04-06 11:15:27 или 1586171872 или любая другая строка |
signature |
обязательный | string(128) | Подпись | 7eec02ed1088b47da639549a109c0e98 a75e2d8c76dfa33db4ee18359b2ea677 dda37516abc0e439b286261a48d49d3e 2fd885d9f09c8ff5c7308afe4180688a |
signature формируется путем объединения закрытого ключа приложения, идентификатора приложения и параметра даты с помощью вертикальной черты | (в кодировке utf-8).
К полученной строке следует применить хеш-функцию SHA-512.
Пример формирования сигнатуры
from datetime import datetime
import hashlib
date = str(datetime.now())
company_id = str(%your_company_id%)
signature = hashlib.sha512('|'.join(['%your_company_private_key%', company_id, date]).encode('utf-8')).hexdigest()
<?php
$date = strtotime("now");
$company_id = %application_id%;
$signature = hash('sha512', join('|',array('%your_company_private_key%', $company_id, $date)));
Если запрос прошел успешно, токен будет содержаться в параметре token ответа JSON и истечет через 1 час.
В противном случае ответ будет содержать ключи error_code и error_message.
Пример curl запроса
curl 'https://pay.payme.uz/authorizer/token/application/get' \
-H "Content-Type: application/json; charset=utf-8" \
-X POST --data-binary @- <<EOF
{
"signature": "5124cef4e69a015c1662f0ff963adc9f85ff60e365445ffcf6688737da726becb298211e5040c9ac74e3f56ff1065b42c281e300370436bec539f6b2679b91ee",
"application_id": "2",
"date": "2024-04-06 11:15:27"
}
EOF
Пример ответа в случае ошибки
{
"request_id": "SuVhZRMS7JDD2iGS",
"token": "Yq0GXWeOZ1m8BsiCa4iQPDB84Wjw346",
"expires_in": 3602
}
{
"error_code": 403,
"error_message": "Incorrect signature",
"request_id": "cGeC7PH59ESqQw30"
}
Получение данных отчета¶
Запрос следует отправить методом POST на конечную точку: https://pay.payme.uz/api/extend/company/report/
Пример запроса для получение данных отчета
| Параметр | Обязательный | Тип | Описание | Пример |
|---|---|---|---|---|
filters |
обязательный | JSON-объекты[] | Набор фильтров, индивидуальный для каждого отчета (report_id) | “filters”: [ { “s”: “settlement_date”, “m”: “dateis”, “v”: “2019-01-24” } ] |
merchant_id |
обязательный | integer(12) | Уникальный идентификатор мерчанта. Генерируется Payme во время регистрации мерчанта. | 4056281 |
report_id |
обязательный | integer(12) | Уникальный идентификатор отчета (см. Список доступных отчетов) | 688 |
on_page |
обязательный | integer(12) | Ограничение количества записей, возвращаемых в рамках одного запроса (рекомендуется от 10 до 500) | 500 |
page |
обязательный | целое число(12) | Записывает смещение страницы. Например, при on_page = 50, чтобы получить данные с 51 по 100, необходимо передать page = 2 | 2 |
| Параметр | Обязательный | Тип | Описание | Пример |
|---|---|---|---|---|
data |
обязательный | JSON-объекты[][] | Набор данных в виде отсортированного двумерного массива JSON | “data”: [ [ 1234567890, 10000000001 ], [ 1234567891, 10000000002 ] ] |
fields |
обязательный | string[] | Список возвращаемых полей | “fields”: [ “payment_id”, “order_time”, “order_status”, “actual_amount”, “currency”, “fee”, “order_id”, “settlement_amount”, “settlement_currency”, “settlement_date”, “settlement_status”, «odb_ref», «tran_time», «settlement_type», «payment_system», «sender_email», «order_desc», «merchant_data», «settlement_desc», «transaction_id» ] |
rows_count |
обязательный | целое число(12) | Количество записей в полном наборе данных | 500 |
rows_on_page |
обязательный | целое число(12) | Количество записей, возвращаемых в контексте данного запроса | 50 |
rows_page |
обязательный | integer(12) | Смещение диапазона в полном наборе данных. Например, если rows_on_page = 50 и rows_page = 2, то в контексте данного запроса возвращаются записи с 51 по 100 | 2 |
Пример запроса и ответа
curl 'https://pay.payme.uz/api/extend/company/report/' \
-H "Authorization: Token k1y0qXZ6KgO4GIfkeRlEznao0zbzYdhf" \
-d @- << EOF
{
"on_page": 10,
"page": 1,
"filters": [
{
"s": "settlement_date",
"m": "from",
"v": "2019-01-24"
},
{
"s": "settlement_date",
"m": "to",
"v": "2019-01-27"
},
{
"s": "actual_amount",
"m": "=",
"v": "630.00"
}
],
"merchant_id": 1398432,
"report_id": "403"
}
EOF
{
"data": [
[
1234567890,
"2025-01-23 10:58:38",
"approved",
"630.00",
"UZS",
"11.97",
"test-25697841-1",
"618.03",
"EUR",
"2025-01-24 08:00:00",
"completed",
"2426012568",
"2025-01-23 10:58:38",
"purchase",
"Visa/MC",
"test@test.com",
"Test order 1",
"[]",
"Test payment 1",
10000000001
],
[
1234567891,
"2025-01-23 10:56:51",
"approved",
"572.86",
"UZS",
"10.88",
"test-94341241-1",
"561.98",
"EUR",
"2025-01-24 08:00:00",
"completed",
"2426012568",
"2025-01-23 10:56:51",
"purchase",
"Visa/MC",
"test2@test.com",
"Test order 2",
"[]",
"Test payment 2",
10000000002
]
],
"rows_count": 2,
"fields": [
"payment_id",
"order_time",
"order_status",
"actual_amount",
"currency",
"fee",
"order_id",
"settlement_amount",
"settlement_currency",
"settlement_date",
"settlement_status",
"odb_ref",
"tran_time",
"settlement_type",
"payment_system",
"sender_email",
"order_desc",
"merchant_data",
"settlement_desc",
"transaction_id"
],
"rows_page": 1,
"rows_on_page": 10
}
Используйте фильтры¶
filter — это массив объектов JSON.
Каждый объект filter должен содержать следующие атрибуты:
s – имя поля, к которому применяется фильтр
m – операнд поиска (=, <, > и т. д., в зависимости от типа поля)
v – значение поля, подлежащее фильтрации
Пример фильтра
[
{
"s": "settlement_date",
"m": "dateis",
"v": "2019-01-24"
}
]
Операнды в зависимости от типа поля¶
Example
float: ‘=’, ‘>’, ‘<’, ‘!=’, ‘isnull’, ‘notnull’
int: ‘=’, ‘>’, ‘<‘, ‘!=’, ‘any’, ‘isnull’, ‘notnull’
date: «dateis», «from», «to», «isnull», «notnull», «notdate»
текст: «=», «!=», «like», «!like», «start», «empty», «any», «notnull»
bool: istrue
select: ‘=’, ‘!=’, ‘any’
array: in_array
daterange: «daterange»
Неочевидные режимы поиска¶
Example
любые:
{“s”: “id”, “m”: “=”, “v”: “10,20,30”} – filter values specified with comma separator
фильтр применяется как id в (10,20,30)
Источник:
{“s”: “timestart”, “m”: “from”, “v”: “2020-01-10”} - filter is applied as timestart >= ‘2020-01-10’
{“s”: “timestart”, “m”: “from”, “v”: “-2”} - filter is applied as timestart >= now() – 2 days
to:
{“s”: “timestart”, “m”: “to”, “v”: “2020-01-10”} - filter is applied as timestart < ‘2020-01-11‘
dateis – «daye equal» – данные, отфильтрованные с начала указанного дня (00:00) до начала следующего дня (00:00) (не включая следующий день)
like – фильтрует частичное совпадение фрагментов
!like – частичный фрагмент не должен совпадать
start – «начиная с»
Список доступных отчетов¶
Параметры запроса для получения данных отчета
| Идентификатор отчета | Поля | Обязательные поля фильтра | Пример фильтра | Описание |
|---|---|---|---|---|
| 500 | chargeback_createtime - datetime(YYYY-MM-DD HH24:MI:SS)tran_id - integer(12)sender_email - string(1000)status - string(1000)tran_timestart - datetime(YYYY-MM-DD HH24:MI:SS)tran_timeend - datetime(YYYY-MM-DD HH24:MI:SS)tran_type - string(1000)protocol - string(1000)currency - string(3)amount - decimal(19,2)payout_date - datetime(YYYY-MM-DD HH24:MI:SS)payout_amoun - datetime(YYYY-MM-DD HH24:MI:SS) |
tran_id ИЛИ chargeback_createtime |
[ { "on_page": 5, "page": 1, "filters": [ { "s": "chargeback_createtime", "m": "from", "v": "2019-12-11" }, { "s": "chargeback_createtime", "m": "to", "v": "2019-12-13" } ], "merchant_id": 4056281, "report_id": "500" } ] |
Отчет о возвратных платежах |
| 528 | tran_id - integer(12)parent_tran_id - integer(12)sender_email - string(1000)status - string(1000)tran_timestart - datetime(YYYY-MM-DD HH24:MI:SS)tran_timeend - datetime(YYYY-MM-DD HH24:MI:SS)tran_type - string(1000)currency - string(3)actual_amount - decimal(19,2)payout_date - datetime(YYYY-MM-DD HH24:MI:SS)payout_amoun - decimal(19,2)order_desc - string(1000)checkout_url - string(1000) |
tran_id ИЛИ tran_timestart |
[ { "on_page": 5, "page": 1, "filters": [ { "s": "tran_timestart", "m": "from", "v": «2019-12-11» }, { "s": «tran_timeend», "m": «to», "v": «2019-12-13» } ], "merchant_id": 4056281, "report_id": «528» } ] |
Отчет об успешных транзакциях |
| 745 | payment_id - integer(12)order_timestart - datetime(YYYY-MM-DD HH24:MI:SS)order_timeend - datetime(YYYY-MM-DD HH24:MI:SS)order_status - string(1000)amount - decimal(19,2)actual_amount - decimal(19,2)transaction_id - integer(19)currency - string(3)actual_currency - string(3)order_type - строка(1000)approval_code - строка(6)card_bin - строка(6)eci - строка(2)fee - десятичное число(19,2)masked_card - строка(19)order_id - строка(1000)payment_system - строка(1000)response_code - целое число(4)response_description - строка(1000)reversal_amount - десятичное число(19,2)rrn - строка(1000)sender_email - string(1000)settlement_amount - decimal(19,2)settlement_currency - string(3)settlement_date - datetime(YYYY-MM-DD HH24:MI:SS)merchant_data - string(1000)order_desc - string(1000)payer_country - string(1000)bank_name - string(1000)bank_country - string(3)card_expire_date - datetime(MM/YYYY)card_brand - string(1000)fee_name - string(1000)fee_type - string(1000)fee_percent_value - decimal(19,3)fee_fix_value - decimal(19,3) |
order_timestart ИЛИ order_timeend ИЛИ payment_id ИЛИ order_id |
[ { "on_page": 5, "page": 1, "filters": [ { "s": "order_timestart", "m": "from", "v": "2019-12-11" }, { "s": "order_timestart", "m": "to", "v": "2019-12-13" } ], "merchant_id": 4056281, "report_id": "745" } ] |
Отчет по всем транзакциям |
| 969 | payment_id - integer(12)tran_id - integer(12)order_id - string(1000)tran_timeend - datetime(YYYY-MM-DD HH24:MI:SS)actual_amount - decimal(19,2)settlement_currency - string(3)fee - decimal(19,2)settlement_amount - decimal(19,2)settlement_date - datetime(YYYY-MM-DD HH24:MI:SS)batch_id - integer(12)order_type - string(1000)order_status - string(1000)card_brand - string(1000)payment_system - string(1000)masked_card - string(19)rrn - integer(12)approval_code - string(6)order_desc - string(1000)merchant_data - string(1000)payer_country - строка(1000)bank_name - строка(1000)card_expire_date - дата и время(ММ/ГГГГ)card_brand - строка(1000)fee_name - строка(1000)fee_type - строка(1000)fee_percent_value - десятичное число(19,3)fee_fix_value - десятичное число(19,3) |
settlement_date ИЛИ tran_timeend ИЛИ payment_id ИЛИ order_id |
[ { "on_page": 5, "page": 1, "filters": [ { "s": "settlement_date", "m": "from", "v": "2025-03-11" }, { "s": "settlement_date", "m": "to", "v": "2025-03-12" } ], "merchant_id": 4056281, "report_id": "969" } ] |
Отчет о возмещении расходов |