# Для транзакций

Данное api позволяет получать информацию о ваших транзакциях с использованием различных фиьтров и сортировок. Основные принципы работы с api описаны выше

Точка входа для боевого (production) окружения:

GET /payment-gateway/v3/transactions

GET /api/public/transactions

# Выгрузка транзакций

Для лучшего понимания принципов работы с данным ендпоинтом предлагаем рассмотреть ряд примеров

Запрос на данную точку входа позволяет получить список транзакций клиента (например, платежи).

Для выполнения требуется скоуп transactions.read, который необходимо запросить при аутентификации

Каждая транзакция содержит opcode - тип транзакции (число).

Значение opcode	Наименование	Описание
1	Purchase	Платеж (одностадийная оплата)
2	Refund	Отмена платежа
3	Rebill	Платеж рекуррентный (автосписание)
4	PreAuth	Авторизация (в том числе с использованием токена карты)
5	Reversal	Отмена авторизации
6	ConfirmAuth	Платеж (завершение расчетов в рамках авторизованной суммы)
22	RefundAFT	Отмена платежа AFT
472	MoneySend	Выплата

# Пример 1. Список успешных платежей за определенный период, по 10 транзакций на странице

Формируем критерии отбора:

updated >= 2019-08-12T00:00:00Z (в UTC, точность - до секунды).
updated < 2019-08-13T00:00:00Z (в UTC, точность - до секунды).
status = success (оставляем только успешные платежи-погашения).
mw_type = transaction (позволяет убрать списания для привязки карт и оставить только платежи).

Объединяем критерии символом амперсанда &: updated>=2019-08-12T00:00:00Z&updated<2019-08-13T00:00:00Z&status=success&mw_type=transaction

После операции "urlencode": updated%3E%3D2019-08-12T00%3A00%3A00Z%26updated%3C2019-08-13T00%3A00%3A00Z%26status%3Dsuccess%26mw_type%3Dtransaction

Вставляем в запрос параметр limit_to=10 и критерии отбора. Результат приведен ниже.

Запрос

GET https://api.psp.io/payment-gateway/v3/transactions?limit_to=10&filter_by=updated%3E%3D2019-08-12T00%3A00%3A00Z%26updated%3C2019-08-13T00%3A00%3A00Z%26status%3Dsuccess%26mw_type%3Dtransaction

Для выполнения требуется скоуп transactions.read.

Ответ

{
	"cursor": {
		"count": 10,
		"prev": null,
		"total": 129,
		"next": "8fdce98f0d6a59348c93434040ac3eefa01a793e4788669eceb2c4f7b9f0e82e"
	},
	"transactions": [{
			"account_id": 659,
			"amount": 2310,
			"amount_converted": 2310,
			"authcode": "274000",
			"card_type": "2",
			"ccadress": null,
			"channel_id": 52,
			"client_id": 44,
			"contract_id": null,
			"contract_token": null,
			"created": "2019-05-22T19:22:17.488741Z",
			"cs0": null,
			"cs1": "1e68b13b34e247fd9ac3583ae9947127",
			"cs2": null,
			"cs3": null,
			"cs4": null,
			"cs5": null,
			"cs6": null,
			"cs7": null,
			"cs8": null,
			"cs9": null,
			"currency_id": 643,
			"currency_id_converted": 643,
			"customer_info": null,
			"email": "guess_who@yandex.ru",
			"gw_node_id": null,
			"hash": "2389d02074b695d1da9447d61bc2f335",
			"id": 19532557,
			"instrument_id": null,
			"instrument_type_id": 1,
			"ip": null,
			"is_aft": true,
			"lang": "en",
			"md": "366297521-E24D925A87503FF9",
			"mw_id": "1e68b13b-34e2-47fd-9ac3-583ae9947127",
			"mw_merchant_id": 516,
			"mw_node_id": null,
			"mw_timestamp_created": "2019-05-22T19:22:17.488765Z",
			"mw_type": "transaction",
			"opcode": 1,
			"order_id": "Иванов Иван Иванович AG9211234 14 дней",
			"pan": "533669******3074",
			"pan_id": "1bf1f988e19d2b1c3312bdedd77b3e16",
			"phone": null,
			"price": {
				"counterparty_total_price": 0,
				"mandarin_total_price": 35
			},
			"product_descr": "Оплата заказа № Иванов Иван Иванович AG9211234 14 дней",
			"product_id": 1,
			"rebill_from": null,
			"rebill_status": null,
			"rebill_statusreason": null,
			"reference_id": null,
			"remote_id": "CD31465822B1551C",
			"remote_id2": null,
			"remote_id3": null,
			"remote_id4": null,
			"remote_id5": null,
			"remote_id_ext": null,
			"remotely_processed": "2019-05-22T19:22:37.086658Z",
			"request_id": null,
			"response_code": 0,
			"rrn": "914291462363",
			"secure_mode": 1,
			"site_id": 1,
			"site_notified": null,
			"status": "success",
			"status_changes_counter": 106312335,
			"subprovider_id": null,
			"terminal_id": null,
			"termurl": null,
			"updated": "2019-05-22T19:22:37Z"
		},
		{
			"еще 9 элементов": "с такой же структурой"
		}
	]
}

Получить следующие 10 элементов можно запросом:

GET https://api.psp.io/payment-gateway/v3/transactions?cursor=8fdce98f0d6a59348c93434040ac3eefa01a793e4788669eceb2c4f7b9f0e82e

Общее количество страниц можно узнать, разделив total на count: 129/10 = 12 полных страницы по 10 элементов, и еще третья страница на 9 элементов.

Если параметр limit_to не указан, то по умолчанию выводится по 50 элементов на странице.

# Пример 2. Полная информацию о транзакции по transaction_id

Любая транзакция имеет уникальный 8-значный числовой номер. По нему вы можете получить полную информацию по транзакции. Вы можете увидеть его в личном кабинете. Например, 22943496.

Вставляем в запрос номер транзакции:

GET https://api.psp.io/payment-gateway/v3/transactions/22943496

Для выполнения требуется скоуп transactions.read.

Поскольку номер транзакции уникален, запрос всегда возвращает один элемент.

# Пример 3. Полную информацию о транзакции по payment_id

При создании транзакции, ее уникальный численно-буквенный идентификатор возвращается в синхронном ответе в поле id. Например, 43913ddc000c4d3990fddbd3980c1725.

При запросе в API это значение находится в поле cs1.

Формируем критерии отбора: cs1 = 43913ddc000c4d3990fddbd3980c1725

После операции "urlencode": cs1%3D43913ddc000c4d3990fddbd3980c1725

Вставляем в запрос критерии отбора:

GET https://api.psp.io/payment-gateway/v3/transactions?filter_by=cs1%3D43913ddc000c4d3990fddbd3980c1725

Для выполнения требуется скоуп transactions.read.

Структура ответа аналогична той, которая указана в примере 1.

Поскольку идентификатор транзакции уникален, запрос всегда возвращает массив из одного элемента.

# Выгрузка реестра транзакций в файл

# Инициализация процесса выгрузки

Данное api позволяет массово выгрузить реестр по транзакциям в формате xls. Основные принципы работы с api описаны выше.

ОБРАТИТЕ ВНИМАНИЕ!

Реестр формируются асинхронно, время формирования реестра варьируется от нескольких секунд и, ориентировочно, до получаса, в зависимости от количества операций в запросе.

Для выполнения требуются скоупы report-generator:public.read report-generator:public.write , которые необходимо запросить при аутентификации.

Для метода доступны следующие фильтры, параметры:

Параметр	Обязателен	Описание
updated	да	даты в формате updated >= 2019-08-12T00:00:00Z updated < 2019-08-13T00:00:00Z (в UTC, точность - до секунды)
opcode	нет	тип транзакции
channel_id	нет	id банка
report_format=xls	да	тип выгрузки, на данный момент доступен только формат xls
limit_to	нет	Лимит выгрузки, ограничений по колличеству нет, однако отсутствие лимита может увеличить время ожидания отчета.

Описание типов транзакций:

Значение opcode	Наименование	Описание
1	Purchase	Платеж (одностадийная оплата)
2	Refund	Отмена платежа
3	Rebill	Платеж рекуррентный (автосписание)
4	PreAuth	Авторизация (в том числе с использованием токена карты)
5	Reversal	Отмена авторизации
6	ConfirmAuth	Платеж (завершение расчетов в рамках авторизованной суммы)
22	RefundAFT	Отмена платежа AFT
472	MoneySend	Выплата

Список id банков:

channel_id	Описание
61	банк ПСБ
64	банк Открытие
66	банк Русский Стандарт
100	Apex bank

Запрос:

GET  https://api.psp.io/report-generator-nt/public/pay_transactions/export?report_format=xls&filter_by=status%20in%20success%26updated%3E%3D2024-05-28T21%3A00%3A00Z%26updated%3C2024-05-30T21%3A00%3A00Z%26channel_id%3D61&limit_to=100

Ответ в случае успешного создания запроса:

{
    "report": {
        "id": "9506073e-457d-4385-8eab-837672704c91",
        "status": "initial",
        "report_type": "report",
        "error_message": null,
        "created_at": "2023-05-29T20:38:55.469834Z",
        "updated_at": "2023-05-29T20:38:55.469834Z"
    }
}

# Проверка статуса выгрузки

Параметр	Тип	Обязателен	Описание
id	string	Да	id запроса - в конце Url строки указывается id запроса, полученный в ответе на инициализацию процесса

Запрос:

GET https://api.psp.io/report-generator-nt/public/report/afe31f52-3993-48cc-bb86-3eaadc5acd7d

Ответ в случае успешного создания запроса:

{
    "report": {
        "id": "9506073e-457d-4385-8eab-837672704c91",
        "status": "success",
        "report_type": "report",
        "error_message": null,
        "created_at": "2023-05-29T20:38:55.469834Z",
        "updated_at": "2023-05-29T20:38:56.091098Z"
    }
}

Если status запроса success, то он успешно сформирован и можно скачивать реестр.

# Выгрузка реестра в xls

Параметр	Тип	Обязателен	Описание
id	string	Да	id запроса - в Url строке указывается id запроса, полученный в ответе на инициализацию процесса

Запрос:

GET https://api.psp.io/report-generator-nt/public/report/427992c7-e630-4391-8923-7f8d0f127494/download

Ответ, в случае успешного создания запроса:

Ответ будет содержать набор символов файла xls. Данный ответ нужно сохранить в файл. По итогу будет получен реестр.

# Метод получения данных о транзакции в secure

Для выполнения требуется скоуп secure:transactions.read, который необходимо запросить при аутентификации

Получить данные о транзакции можно по её id или используя фильтр по параметрам:

# 1. Получение данных о транзакции по id

Запрос

GET https://secure.mandarinpay.com/api/public/transactions/da28496b6a5e4c6480e63755d7cdbfd7

Параметр	Тип	Обязателен	Описание
id	string	да	id транзакции - в конце Url строки указывается id транзакции, данные по которой необходимо получить.
mid	string	нет	номер проекта, по которому совершена была транзакция. Необходимо передать в заголовке (Header)

Ответ

{
    "id": "bea3bdbb2bcb44b5a2eaf91eb5036013",
    "merchant_id": 395,
    "query_string": "?merchantId=395&orderId=177e54fd-ae90-4b4e-8542-61442ba5d778&email=a.test%test.com&orderActualTill=2024-08-01%2009%3A02%3A30Z&price=50.00&callbackUrl=https%3A%2F%2Fsecure.mandarinpay.com%2Fcallback%2F&action=payout&customer_fullName=%20%20&customer_phone=%2B79121111111&customer_email=a.test%test.com",
    "gw_transaction_id": "23193036",
    "bank_transaction_id": null,
    "state": 1,
    "created_at": "2024-07-30T09:02:30.208341",
    "processed_at": "2024-07-30T09:02:32.157039",
    "expires_at": "2024-08-01T09:02:30+00:00",
    "next_action_scheduled_at": null,
    "type": 1,
    "order_id": "177e54fd-ae90-4b4e-8542-61442ba5d778",
    "creator_ip": "33.22.11.11",
    "extra": "{\n  \"Active3dsOperationId\": null,\n  \"customer_creditcard_number\": \"400000XXXXXX0002\",\n  \"CreditCardHolder\": null,\n  \"CreditCardExpirationYear\": 0,\n  \"CreditCardExpirationMonth\": 0,\n  \"Rrn\": \"2977333333\",\n  \"AuthCode\": null,\n  \"RemoteSystemId\": null,\n  \"ErrorCode\": null,\n  \"ErrorDescription\": null,\n  \"Had3DSecure\": null,\n  \"DocumentFileId\": null,\n  \"RouteOverride\": null,\n  \"Channel\": \"internal\",\n  \"SavedCreditCardNumber\": null,\n  \"IsPayoutOnlyCardBinding\": false,\n  \"UsedPreAuth\": false,\n  \"GwMerchantAccountId\": 1,\n  \"CardId\": \"214d269a62bbfb698711b41a1f564sd\",\n  \"PaymentReceiver\": null,\n  \"FailedGwMerchantAccountIds\": null,\n  \"IsSandbox\": false,\n  \"FiscalInformation\": {\n    \"Items\": [\n      {\n        \"Description\": \"Товар\",\n        \"Quantity\": 1.0,\n        \"TotalPrice\": 50.0,\n        \"Vat\": 6,\n        \"ProductType\": null,\n        \"Shipper\": null,\n        \"AgentType\": null,\n        \"CalculationMethod\": \"FULL_PAY\",\n        \"PaymentSubject\": \"PRODUCT\"\n      }\n    ],\n    \"TaxationSystem\": 0\n  }\n}",
    "extra_data": {
        "active3ds_operation_id": null,
        "customer_creditcard_number": "400000XXXXXX0002",
        "credit_card_holder": null,
        "credit_card_expiration_year": 0,
        "credit_card_expiration_month": 0,
        "rrn": "2977333333",
        "auth_code": null,
        "remote_system_id": null,
        "error_code": null,
        "error_description": null,
        "had3_d_secure": null,
        "document_file_id": null,
        "route_override": null,
        "channel": "internal",
        "saved_credit_card_number": null,
        "is_payout_only_card_binding": false,
        "used_pre_auth": false,
        "gw_merchant_account_id": 1,
        "card_id": "214d269a62bbfb698711b41a1f564sd",
        "payment_receiver": null,
        "failed_gw_merchant_account_ids": null,
        "is_sandbox": false,
        "fiscal_information": {
            "items": [
                {
                    "description": "Товар",
                    "quantity": 1.0,
                    "total_price": 50.0,
                    "vat": 6,
                    "product_type": null,
                    "shipper": null,
                    "agent_type": null,
                    "calculation_method": "FULL_PAY",
                    "payment_subject": "PRODUCT"
                }
            ],
            "taxation_system": 0
        }
    },
    "target_type": 3,
    "target": "5hGlT9iTQw/W1h6sdfs121sPnvnHocMx",
    "last_error": null,
    "update_stamp": 197251925,
    "subscription_id": null,
    "needs_auto_reversal": false,
    "custom_values": []
}

# 2. Получение списка транзакций с фильтрами(filter_by)

Список доступных фильтров:

Параметр	Описание
id	Идентификатор транзакции.
order_id	Идентификатор заказа в вашей системе.
state	Статус транзакции. Возможные значения: Success = 1 (Успех); Failed = 4 (Неуспех); PendingConfirmation = 3 (Ожидание); PendingExecution = 5 (Ожидание); Interrupted = 6 (Ожидание); Unknown = 7 (Неизвестный).
merchant_id	Идентификатор проекта.
processed_start_at и processed_end_at	Дата проведения операции. Возможность выбора диапазона дат по полю processed_at
type	Тип транзакции. Возможные значения: Pay = 0 (Платеж); PayOut = 1 (Выплата); PreAuth = 2 (Авторизация); Reversal = 3 (Отмена); Binding = 4 (Привязка).
target_type	Тип ссылки на существующую транзакцию. Возможные значения: Web = 0; BoundCard = 1; Transaction = 2; KnownCardNumber = 3; PayoutBestMt = 4; PayoutPhone = 5; PayoutYandexMoney = 6; PayoutWebMoney = 7; BankAccount = 8; PayoutQiwi = 9; Wallet = 10; PayoutGos = 11; PayoutSbp = 12.
created_start_date и created_end_date	Дата создания операции. Возможность выбора диапазона дат по полю created_at

Для построения фильтра в запросе используется параметр filter_by.
Критерии запроса разделяются символом амперсанда &.
Для регулирования количества транзакций в ответе используется параметр limit_to.
Если параметр limit_to не указан, то по умолчанию выводится по 25 элементов на странице.
Чтобы узнать общее количество страниц, нужно разделить total на count. Например: 129/10 = 12 полных страницы по 10 элементов, и еще третья страница на 9 элементов.

Запрос

GET https://secure.mandarinpay.com/api/public/transactions?filter_by=created_start_date>2024-07-30&created_end_date<2024-08-10

Ответ

{
    "cursor": {
        "count": 25,
        "next": "aea21d3bdc111519",
        "prev": null,
        "total": 123
    },
	"transactions": [
        {
    "id": "bea3bdbb2bcb44b5a2eaf91eb5036013",
    "merchant_id": 395,
    "query_string": "?merchantId=395&orderId=177e54fd-ae90-4b4e-8542-61442ba5d778&email=a.test%test.com&orderActualTill=2024-08-01%2009%3A02%3A30Z&price=50.00&callbackUrl=https%3A%2F%2Fsecure.mandarinpay.com%2Fcallback%2F&action=payout&customer_fullName=%20%20&customer_phone=%2B79121111111&customer_email=a.test%test.com",
    "gw_transaction_id": "23193036",
    "bank_transaction_id": null,
    "state": 1,
    "created_at": "2024-07-30T09:02:30.208341",
    "processed_at": "2024-07-30T09:02:32.157039",
    "expires_at": "2024-08-01T09:02:30+00:00",
    "next_action_scheduled_at": null,
    "type": 1,
    "order_id": "177e54fd-ae90-4b4e-8542-61442ba5d778",
    "creator_ip": "33.22.11.11",
    "extra": "{\n  \"Active3dsOperationId\": null,\n  \"customer_creditcard_number\": \"400000XXXXXX0002\",\n  \"CreditCardHolder\": null,\n  \"CreditCardExpirationYear\": 0,\n  \"CreditCardExpirationMonth\": 0,\n  \"Rrn\": \"2977333333\",\n  \"AuthCode\": null,\n  \"RemoteSystemId\": null,\n  \"ErrorCode\": null,\n  \"ErrorDescription\": null,\n  \"Had3DSecure\": null,\n  \"DocumentFileId\": null,\n  \"RouteOverride\": null,\n  \"Channel\": \"internal\",\n  \"SavedCreditCardNumber\": null,\n  \"IsPayoutOnlyCardBinding\": false,\n  \"UsedPreAuth\": false,\n  \"GwMerchantAccountId\": 1,\n  \"CardId\": \"214d269a62bbfb698711b41a1f564sd\",\n  \"PaymentReceiver\": null,\n  \"FailedGwMerchantAccountIds\": null,\n  \"IsSandbox\": false,\n  \"FiscalInformation\": {\n    \"Items\": [\n      {\n        \"Description\": \"Товар\",\n        \"Quantity\": 1.0,\n        \"TotalPrice\": 50.0,\n        \"Vat\": 6,\n        \"ProductType\": null,\n        \"Shipper\": null,\n        \"AgentType\": null,\n        \"CalculationMethod\": \"FULL_PAY\",\n        \"PaymentSubject\": \"PRODUCT\"\n      }\n    ],\n    \"TaxationSystem\": 0\n  }\n}",
    "extra_data": {
        "active3ds_operation_id": null,
        "customer_creditcard_number": "400000XXXXXX0002",
        "credit_card_holder": null,
        "credit_card_expiration_year": 0,
        "credit_card_expiration_month": 0,
        "rrn": "2977333333",
        "auth_code": null,
        "remote_system_id": null,
        "error_code": null,
        "error_description": null,
        "had3_d_secure": null,
        "document_file_id": null,
        "route_override": null,
        "channel": "internal",
        "saved_credit_card_number": null,
        "is_payout_only_card_binding": false,
        "used_pre_auth": false,
        "gw_merchant_account_id": 1,
        "card_id": "214d269a62bbfb698711b41a1f564sd",
        "payment_receiver": null,
        "failed_gw_merchant_account_ids": null,
        "is_sandbox": false,
        "fiscal_information": {
            "items": [
                {
                    "description": "Товар",
                    "quantity": 1.0,
                    "total_price": 50.0,
                    "vat": 6,
                    "product_type": null,
                    "shipper": null,
                    "agent_type": null,
                    "calculation_method": "FULL_PAY",
                    "payment_subject": "PRODUCT"
                }
            ],
            "taxation_system": 0
        }
    },
    "target_type": 3,
    "target": "5hGlT9iTQw/W1h6sdfs121sPnvnHocMx",
    "last_error": null,
    "update_stamp": 197251925,
    "subscription_id": null,
    "needs_auto_reversal": false,
    "custom_values": []
		},
		{
			"еще 122 элемента": "с такой же структурой"
		}
    ]
}

# Метод для запроса баланса

Метод позволяет получить информацию по остатку средств на счете для выплат. В ответе вы получите все актуальные балансы банков, которые у вас подключены, а также дата и время последнего обновления баланса.

Для выполнения требуется скоуп pay_bank_account_balance.read, который необходимо запросить при аутентификации

Запрос

GET https://api.psp.io/balance/v3/client/{client_id}/balance

В качестве значения {client_id} необходимо передать ваш client id

Ответ в случае успешного запроса (200 ОК)

{
    "status": {
        "success": true,
        "errors": []
    },
    "client": {
        "id": 12345,
        "balances": [
            {
                "name": "psb",
                "description": "Промсвязьбанк",
                "balance": [
                    {
                        "account_id": 1112,
                        "account_number": "40701810600000003456",
                        "real": {
                            "amount": 8740.43,
                            "updated_at": "2025-03-06T11:35:03.415986"
                        },
                        "virtual": {
                            "amount": 8740.43,
                            "updated_at": "2025-03-06T11:35:03.415986"
                        }
                    }
                ]
            },
            {
                "name": "brs",
                "description": "Банк Русский Стандарт",
                "balance": [
                    {
                        "account_id": 1113,
                        "account_number": "",
                        "real": {
                            "amount": 2853812.00,
                            "updated_at": "2025-03-06T08:10:39.464010"
                        },
                        "virtual": {
                            "amount": 2853812.00,
                            "updated_at": "2025-03-06T08:10:39.464010"
                        }
                    }
                ]
            }
        ],
        "total_balance": 2862552.43
    }
}

← Основные принципы Массовая переотправка Callbacks →