Working with object lists
In YooMoney, you can get the information not just for a single specific object (for example, a payment) but for a number of them as well, in the format of a list of objects. This is useful when you want to check by the API, upload a significant amount of data to another system, conduct analytics, or perform any other tasks related to the simultaneous processing of a large number of objects.
For main resources (payments, refunds, receipts), the lists will contain information only about the objects created within the last 3 years.
Request and response formats
Most of the YooMoney API collections support bulk upload using object lists. For example, you can get a list of payments , a list of refunds , a list of receipts , or a list of deals (if you use Safe deal).
For the main resources of the YooMoney API, the procedures for obtaining the lists are similar. You can add to a GET request the parameters for sorting objects by specific criteria (depending on the collection ) as well as parameters for customizing the output of results.
Parameters for setting the output of results
| Parameter | Type | Description |
|---|---|---|
limit | number | Size of the output of request results: the number of objects sent in the response. Possible values: 1 to 100. Example: limit=50Default value: 10 Optional parameter |
cursor | string | Cursor to the next fragment of the list. Example: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15For the cursor, use the value of the next_cursor parameter received in response to the previous request (see Pagination).Used if the end of the list has not been reached. Optional parameter |
Example of a request for a list of payments with a limitation on the number of objects in the output
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments?limit=2 \ -u <Shop ID>:<Secret Key> \
In response, YooMoney will return a list of objects that meet the request parameters. The list will be sorted by the object creation date in descending order (from newest to oldest).
Response parameters
| Parameter | Type | Description |
|---|---|---|
type | string | Format of request results output. Possible value: list (list).Required parameter |
items | array | Array of objects matching the request parameters. Required parameter |
next_cursor | string | Cursor to the next fragment of the list (see Pagination). Example: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15Optional parameter |
Example of the response body
JSON
{ "type": "list", "items": [ { "id": "2419a771-000f-5000-9000-1edaf29243f2", "status": "pending", "paid": false, "amount": { "value": "100.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=2419a771-000f-5000-9000-1edaf29243f2" }, "created_at": "2019-03-12T11:10:41.802Z", "description": "Order No. 1", "metadata": { "order_id": "37" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }, { "id": "22e12f66-000f-5000-8000-18db351245c7", "status": "waiting_for_capture", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2018-07-18T10:51:18.139Z", "description": "Order No. 72", "expires_at": "2018-07-25T10:52:00.233Z", "metadata": { }, "payment_method": { "type": "bank_card", "id": "22e12f66-000f-5000-8000-18db351245c7", "saved": false, "card": { "first6": "555555", "last4": "4444", "expiry_month": "07", "expiry_year": "2022", "card_type": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *4444" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false } ], "next_cursor": "37a5c87d-3984-51e8-a7f3-8de646d39ec15" }
Pagination
If the number of results in the list exceeds the value set in the
limit parameter, YooMoney will use pagination, i.e split the list into fragments (“pages”). In this case, the response to the original request will return the first fragment of the list and a cursor to the next one in the next_cursor parameter. To get the next fragment, repeat the original request with the cursor parameter specifying the received cursor.Example of a request for a list of payments with a cursor to the next fragment of the list
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments?limit=2&cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15 \ -u <Shop ID>:<Secret Key> \
Example of response body when the end of the list is reached
JSON
{ "type": "list", "items": [ { "id": "22979b7b-000f-5000-9000-1a603a795739", "status": "canceled", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2018-05-23T15:24:43.812Z", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22979b7b-000f-5000-9000-1a603a795739", "saved": false }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false, "cancellation_details": { "party": "payment_network", "reason": "payment_method_restricted" } } ] }
Limiting the number of requests
YooMoney limits the number of incoming requests to improve the stability of the service. If you send too many requests within a short period of time, YooMoney will return HTTP 429 code with the
too_many_requests error code. In this case, we recommend increasing the interval between requests to reduce the total number of hits per unit of time.Example of response body when there are too many requests
HTTP
HTTP/2 429 Server: nginx Date: Wed, 20 Apr 2022 14:04:13 GMT Content-Type: application/json Content-Length: 199 Signature: v1 29f2269d 1 MGUCMQCJiMvqupFLDI4PY0dLlmVK6WnqagBVCk7OFP0qScRAALdPcFXaZZsmgzf6MSgasjICMAQZGgYdZolt98rlGJfdA/m2J7DqSuzddc1NLrzZv71eLiTYBAI+PHZ6EfyNKISGKA== { "type" : "error", "id" : "2a9ab90e-f69f-4844-980b-4e3ec4ff1c86", "code" : "too_many_requests", "description" : "Wow, so many requests! Try to use an exponential backoff of your requests." }
See also