Working with object lists — Payment acceptance via the YooMoney API

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=50` Default value: 10 Optional parameter
cursor	string	Cursor to the next fragment of the list. Example: `cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15` For 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-8de646d39ec15` Optional 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."
}