# Transactions

This API allows you to retrieve information about your transactions using various filters and sorting options. The basic principles of working with the API are described above

Entry point for the production environment:

GET /payment-gateway/v3/transactions

GET /api/public/transactions

# Exporting transactions

To better understand how this endpoint works, we suggest reviewing several examples

A request to this entry point allows you to get a list of customer transactions (for example, payments).

Requires the transactions.read scope, which must be requested during authentication

Each transaction contains opcode — the transaction type (number).

opcode value	Name	Description
1	Purchase	Payment (single-stage payment)
2	Refund	Payment cancellation
3	Rebill	Recurring payment (automatic debit)
4	PreAuth	Authorization (including using a card token)
5	Reversal	Cancel authorization
6	ConfirmAuth	Payment (completion of settlement within the authorized amount)
22	RefundAFT	AFT payment cancellation
472	MoneySend	Payout

# Example 1. List of successful payments for a specific period, 10 transactions per page

Form the selection criteria:

updated >= 2019-08-12T00:00:00Z (in UTC, accurate to the second).
updated < 2019-08-13T00:00:00Z (in UTC, accurate to the second).
status = success (keep only successful payments).
mw_type = transaction (removes card-binding debits and leaves only payments).

Combine the criteria with the ampersand symbol &: updated>=2019-08-12T00:00:00Z&updated<2019-08-13T00:00:00Z&status=success&mw_type=transaction

After urlencode: updated%3E%3D2019-08-12T00%3A00%3A00Z%26updated%3C2019-08-13T00%3A00%3A00Z%26status%3Dsuccess%26mw_type%3Dtransaction

Insert the parameter limit_to=10 and the selection criteria into the request. The result is shown below.

Request

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

Requires the transactions.read scope.

Response

{
	"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 элементов": "с такой же структурой"
		}
	]
}

You can retrieve the next 10 items with a request:

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

The total number of pages can be found by dividing total by count: 129/10 = 12 full pages of 10 items, and a third page with 9 items.

If the limit_to parameter is not specified, 50 items are returned per page by default.

# Example 2. Full transaction information by transaction_id

Any transaction has a unique 8-digit numeric identifier. You can use it to get full information about the transaction. You can see it in your personal account. For example, 22943496.

Insert the transaction number into the request:

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

Requires the transactions.read scope.

Since the transaction number is unique, the request always returns one item.

# Example 3. Full transaction information by payment_id

When a transaction is created, its unique alphanumeric identifier is returned in the synchronous response in the id field. For example, 43913ddc000c4d3990fddbd3980c1725.

When querying the API, this value is in the cs1 field.

Form the selection criteria: cs1 = 43913ddc000c4d3990fddbd3980c1725

After urlencode: cs1%3D43913ddc000c4d3990fddbd3980c1725

Insert the selection criteria into the request:

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

Requires the transactions.read scope.

The response structure is the same as in Example 1.

Since the transaction identifier is unique, the request always returns an array of one element.

# Exporting a transaction register to a file

# Initializing the export process

This API allows you to bulk-export a transaction register in xls format. The basic principles of working with the API are described above.

PLEASE NOTE!

Registers are generated asynchronously. Generation time varies from a few seconds to approximately half an hour, depending on the number of operations in the request.

Requires the scopes report-generator:public.read and report-generator:public.write, which must be requested during authentication.

The following filters and parameters are available for the method:

Parameter	Required	Description
updated	yes	dates in the format updated >= 2019-08-12T00:00:00Z updated < 2019-08-13T00:00:00Z (in UTC, accurate to the second)
opcode	no	transaction type
channel_id	no	bank id
report_format=xls	yes	export type; currently only xls format is available
limit_to	no	Export limit; there is no cap on quantity, but omitting the limit may increase report wait time.

Transaction types:

opcode value	Name	Description
1	Purchase	Payment (single-stage payment)
2	Refund	Payment cancellation
3	Rebill	Recurring payment (automatic debit)
4	PreAuth	Authorization (including using a card token)
5	Reversal	Cancel authorization
6	ConfirmAuth	Payment (completion of settlement within the authorized amount)
22	RefundAFT	AFT payment cancellation
472	MoneySend	Payout

List of bank ids:

channel_id	Description
61	PSB bank
64	Otkritie bank
66	Russian Standard bank
100	Apex bank

Request:

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

Response if the request is successfully created:

{
    "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"
   }
}

# Checking export status

Parameter	Type	Required	Description
id	string	Yes	Request id — at the end of the URL, specify the id received in the response when initializing the process

Request:

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

Response if the request is successfully created:

{
    "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"
   }
}

If the request status is success, it has been generated successfully and you can download the register.

# Downloading the register in xls

Parameter	Type	Required	Description
id	string	Yes	Request id — in the URL, specify the id received in the response when initializing the process

Request:

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

Response if the request is successfully created:

The response will contain the raw bytes of an xls file. Save this response to a file. The result will be the register.

# Method for obtaining transaction data in secure

Requires the secure:transactions.read scope, which must be requested during authentication

You can obtain transaction data by its id or using filters by parameters:

# 1. Obtaining transaction data by id

Request

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

Parameter	Type	Required	Description
id	string	yes	Transaction id — at the end of the URL, specify the id of the transaction for which data must be retrieved.
mid	string	no	Project number for which the transaction was made. Must be passed in the Header

Response

{
    "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. Obtaining a list of transactions with filters (filter_by)

List of available filters:

Parameter	Description
id	Transaction identifier.
order_id	Order identifier in your system.
state	Transaction status. Possible values: Success = 1 (Success); Failed = 4 (Failed); PendingConfirmation = 3 (Pending); PendingExecution = 5 (Pending); Interrupted = 6 (Pending); Unknown = 7 (Unknown).
merchant_id	Project identifier.
processed_start_at and processed_end_at	Operation date. Ability to select a date range using the `processed_at` field
type	Transaction type. Possible values: Pay = 0 (Payment); PayOut = 1 (Payout); PreAuth = 2 (Authorization); Reversal = 3 (Cancellation); Binding = 4 (Binding).
target_type	Type of reference to an existing transaction. Possible values: 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 and created_end_date	Operation creation date. Ability to select a date range using the `created_at` field

To build a filter in the request, use the filter_by parameter. Query criteria are separated by the ampersand character &. To regulate the number of transactions in the response, use the limit_to parameter. If the limit_to parameter is not specified, 25 items are returned per page by default. To find out the total number of pages, divide total by count. For example: 129/10 = 12 full pages of 10 items, and a third page with 9 items.

Request

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

Response

{
    "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 элемента": "с такой же структурой"
		}
    ]
}

# Method for balance request

The method allows you to obtain information on the balance of funds in the account for payouts. In the response you will receive all current balances of the banks connected to your account, as well as the date and time of the last balance update.

Requires the pay_bank_account_balance.read scope, which must be requested during authentication

Request

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

You must pass your client id as the value of {client_id}

Response in case of a successful request (200 OK)

{
    "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
    }
}

← Basic principles Bulk Resending Callbacks →