Object lists
In Yandex.Checkout, 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 Yandex.Checkout API collections support bulk upload using object lists. For example, you can get a list of payments , a list of refunds , or a list of receipts .
For the main resources of the Yandex.Checkout 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
ParameterTypeMandatoryDescription
limitnumberOptionalSize 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
cursorstringOptionalCursor 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.
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://payment.yandex.net/api/v3/payments?limit=2 \
  -u <Shop ID>:<Secret Key> \
In response, Yandex.Checkout 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
ParameterTypeMandatoryDescription
typestringMandatoryFormat of request results output. Possible value:
list
itemsarrayMandatoryArray of objects matching the request parameters
next_cursorstringOptionalCursor to the next fragment of the list (see Pagination). Example:
cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15
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://money.yandex.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": "100001",
        "gateway_id": "1000001"
      },
      "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": "MasterCard",
          "issuer_country": "RU",
          "issuer_name": "Sberbank"
        },
        "title": "Bank card *4444"
      },
      "recipient": {
        "account_id": "100001",
        "gateway_id": "1000001"
      },
      "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, Yandex.Checkout 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://payment.yandex.net/api/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": "100001",
        "gateway_id": "1000001"
      },
      "refundable": false,
      "test": false,
      "cancellation_details": {
        "party": "payment_network",
        "reason": "payment_method_restricted"
      }
    }
  ]
}
 
Limiting the number of requests
Yandex.Checkout 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, Yandex.Checkout will return HTTP code 429 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
JSON
{
  "type": "error",
  "code": "too_many_requests",
  "description": "Wow, so many requests! Try to use an exponential backoff of your requests.",
  "id": "a8c33ab1-ddbf-43cd-990b-f3a943cafe3c"
}
 
See also
Payment listsRefund listsReceipt listsDaily reports