Pagination

What is pagination

When data sets get large, it becomes inefficient to return them in a single response. To make it faster for both the server and API clients, we divide the data into small chunks. The API client asks for a chunk of data, and the server returns it along with a token called a cursor. The API client then sends the cursor back to the server to request the next chunk of data. This process repeats until the API client has iterated through all the data and is called pagination.

How does pagination work in the API?

All “list” endpoints in Cash App Pay use pagination, and support two pagination-related fields on the request:

• cursor, which is a string used by the server to fetch the next page of data. Use the cursor from the response to populate this field.
• limit, which is an integer from 1 to 100 that sets the maximum number of resources that can be returned in the response.

A cursor is provided at the top-level of each paginated response if there is another page of data to load. Once no cursor is present on the response, you’ve iterated through all the data.

Example: Listing all payments

In this example, we’ll attempt to list all the payments taken by our API client. First, we’ll build a cURL request to call list payments:

1
{
2
  "method": "get",
3
  "url": "https://sandbox.api.cash.app/network/v1/payments",
4
  "headers": {
5
    "Accept": "application/json",
6
    "Authorization": "Client CLIENT_ID API_KEY_ID",
7
    "X-Region": "SEA",
8
    "X-Signature": "sandbox:skip-signature-check"
9
  },
10
  "query": {
11
    "limit": 1
12
  }
13
}

The API will respond with some JSON that looks like this:

1
{
2
  "payments": [
3
    {
4
      "id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
5
      "amount": 1500,
6
      "refunded_amount": 100,
7
      "net_amount": 1400,
8
      "currency": "USD",
9
      "customer_id": "AUTH_24g7nq7m1je9b6fnzbtvwzqej",
10
      "merchant_id": "MERCHANT_4vxs5egfk7hmta3qx2h6rp91x",
11
      "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
12
      "status": "AUTHORIZED",
13
      "created_at": "2022-01-01T12:00:00Z",
14
      "updated_at": "2022-01-05T12:00:00Z",
15
      "refund_ids": [
16
        "PWCR_da1v3j4p3z15y47adpzzq0whj"
17
      ],
18
      "reference_id": "external-id"
19
    }
20
  ],
21
  "cursor": "be167132a9f2b565"
22
}

Since we set the limit parameter to 1, only one resource is returned. To grab the next resource, we would make a similar request, but with the addition of the cursor as a query parameter:

1
{
2
  "method": "get",
3
  "url": "https://sandbox.api.cash.app/network/v1/payments",
4
  "headers": {
5
    "Accept": "application/json",
6
    "Authorization": "Client CLIENT_ID API_KEY_ID",
7
    "X-Region": "SEA",
8
    "X-Signature": "sandbox:skip-signature-check"
9
  },
10
  "query": {
11
    "limit": 1,
12
    "cursor": "be167132a9f2b565"
13
  }
14
}

In the response, notice that there is no longer a cursor field:

1
{
2
  "payments": [
3
    {
4
      "id": "PWC_50n21zyac0v2yhq23vvhk7xkwpc",
5
      "amount": 100,
6
      "net_amount": 100,
7
      "currency": "USD",
8
      "customer_id": "AUTH_24g7nq7m1je9b6fnzbtvwzqej",
9
      "merchant_id": "MERCHANT_4vxs5egfk7hmta3qx2h6rp91x",
10
      "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
11
      "status": "CAPTURED",
12
      "created_at": "2022-01-01T12:00:00Z",
13
      "updated_at": "2022-01-05T12:00:00Z",
14
      "reference_id": "external-id"
15
    }
16
  ]
17
}

This means that there is no more data to page through; we’ve now iterated through the entire data set.