Перейти к содержанию

Отчеты

Общие положения по 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"
}
]
Отчет о возмещении расходов