Mandarin

# Transaction API

This api allows you to get information about your transactions using various filters and sorting. 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

# Examples

For a better understanding of the principles of working with this handpoint, we suggest you look at a number of examples

*Request to this entry point allows you to get a list of customer transactions (e.g., payments).

The transactions.read skip is required to execute and must be requested at authentication

Each transaction contains opcode - transaction type (number).

opcode value Name Description
1 Purchase Payment (one-stage payment)
2 Refund Cancel payment
3 Rebill Recurrent payment (autoschedule)
4 PreAuth Authorization (by card token)
5 Reversal Cancel authorization
6 ConfirmAuth Finalization (completion of payment within the authorized amount)
22 RefundAFT Cancel AFT payment
472 MoneySend Payout

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

We form the selection criteria:

  • updated >= 2019-08-12T00:00:00Z (in UTC, accurate to a second).

  • updated < 2019-08-13T00:00:00Z (in UTC, accurate to a second).

  • status = success (leave only successful payments-payments).

  • mw_type = transaction (allows you to remove debits for card binding and leave only the 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 the "urlencode" operation: 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 query. 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

The transactions.read scoop is required for execution.

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": "Ivanov Ivanovich AG9211234 14 days",
			"pan": "533669******3074",
			"pan_id": "1bf1f988e19d2b1c3312bdedd77b3e16",
			"phone": null,
			{ "price": {
				"counterparty_total_price": 0,
				"mandarin_total_price": 35
			},
			"product_descr": "Payment of Order No. Ivan Ivanovich AG9211234 14 days",
			"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"
		},
		{
			"nine more elements": "with the same structure"
		}
	]
}

You can retrieve the next 10 items with a query:

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 of 9 items.

If the limit_to parameter is not specified, 50 items are output by default on the page.

# Example 2. Full transaction information by transaction_id

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

Insert the transaction number in the query:

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

The transactions.read scoop is required for execution.

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

# Example 3. Full information about the transaction by payment_id

When a transaction is created, its unique numeric-letter identifier returns in sync response in the id field. Например, 43913ddc000c4d3990fddbd3980c1725.

When queried in the API this value is in the cs1 field.

Form the selection criteria: cs1 = 43913ddc000c4d3990fddbd3980c1725

After the "urlencode" operation: cs1%3D43913ddc000c4d3990fddbd3980c1725

Insert the selection criteria in the query:

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

The transactions.read scoop is required for execution.

The structure of the answer is the same as in Example 1.

Since the transaction ID is unique, the query always returns an array of

# Method for obtaining transaction data in secure

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

You can get data about a transaction by its id or using a filter 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 string, the id of the transaction for which data must be obtained is indicated.
mid string no the project number for which the transaction was made. Must be passed in the header

Answer

{
 "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%3 A%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\": \"Product\",\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": "Product",
 "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 ID.
order_id The order ID in your system.
state Transaction status.
merchant_id Project ID.
processed_start_at and processed_end_at Date of the operation. Ability to select a date range using the processed_at field
type Transaction type. Possible values:
Pay = 0 (Payment);
PayOut = 1 (Payment);
PreAuth = 2 (Authorization);
Reversal = 3 (Cancel);
Binding = 4 (Binding).
target_type The 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 The date the operation was created. 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, the limit_to parameter is used. If the limit_to parameter is not specified, then by default 25 elements are displayed per page. To find out the total number of pages, you need to divide total by count. For example: 129/10 = 12 full pages of 10 elements, and another third page of 9 elements.

Request

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

Answer

{
 "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%3 A%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\": \"Product\",\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": "Product",
 "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": []
  },
  {
  "another 122 elements": "with the same structure"
  }
 ]
}

one element.

# Method for balance request

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

Requires scope pay_bank_account_balance.read to execute

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": "Promsvyazbank",
"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": "Russian Standard Bank",
 "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
 }
}

←