Migrating to Cursor Pagination

To migrate your requests to use Cursor Pagination:

  1. Send a versioning header with your requests. For more info about including a versioning header, see Versioning .
  2. When you switch to a version that supports pagination, all object responses remain the same, but the page metadata changes:

Old

Copy
Copied
    "page": {
        "offset": 0,
        "limit": 20,
        "count": 1241393
    }

New

Copy
Copied
    "page": {
        "limit": 20,
        "next_cursor": "TRhT44rAqsCQaRQqaEGhHvn9"
    }

Cursor-Based Pagination Requests

Here's an example of a request that uses cursor-based pagination to fetch the last three submitted transfers.

Copy
Copied
curl 'https://finix.sandbox-payments-api.com/transfers?limit=3' \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \

Example Response

Copy
Copied
{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TRc4LX6X9aT7LC9scUP6EeNk",
      "amount" : 100,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "93ef8a90-aba3-4719-8835-055228ed15f5",
      "currency" : "USD",
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "source" : null,
      "destination" : null,
      "ready_to_settle_at" : "2022-04-19T16:07:11.02Z",
      "externally_funded" : "FALSE",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "fee_type" : "CARD_FIXED",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2022-04-19T16:07:10.89Z",
      "updated_at" : "2022-04-19T16:07:11.00Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDddHpRqwf2VsH2XB1fmLfhM",
      "subtype" : "PLATFORM_FEE",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRc4LX6X9aT7LC9scUP6EeNk"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDddHpRqwf2VsH2XB1fmLfhM"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRc4LX6X9aT7LC9scUP6EeNk/payment_instruments"
        },
        "parent" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
      }
    }, {
      "id" : "TRbsCAH2ChsLz6BTU4A7Xkzm",
      "amount" : 13243,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "73708b08-472e-4879-9380-0b7cbdac1496",
      "currency" : "USD",
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "source" : null,
      "destination" : null,
      "ready_to_settle_at" : "2022-04-19T16:07:11.02Z",
      "externally_funded" : "FALSE",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "fee_type" : "CARD_BASIS_POINTS",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2022-04-19T16:07:10.53Z",
      "updated_at" : "2022-04-19T16:07:10.71Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDddHpRqwf2VsH2XB1fmLfhM",
      "subtype" : "PLATFORM_FEE",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRbsCAH2ChsLz6BTU4A7Xkzm"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDddHpRqwf2VsH2XB1fmLfhM"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRbsCAH2ChsLz6BTU4A7Xkzm/payment_instruments"
        },
        "parent" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
      }
    }, {
      "id" : "TRoE5Ns5hz9fsdKdwuZtUuCE",
      "amount" : 662154,
      "tags" : {
        "test" : "sale"
      },
      "state" : "SUCCEEDED",
      "trace_id" : "16e37d79-fd4e-43b9-b70b-304a9ce8f879",
      "currency" : "USD",
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
      "destination" : null,
      "ready_to_settle_at" : "2022-04-19T16:07:11.01Z",
      "externally_funded" : "UNKNOWN",
      "fee" : 0,
      "statement_descriptor" : "FNX*DUNDER MIFFLIN",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2022-04-19T16:06:48.25Z",
      "updated_at" : "2022-04-19T16:07:10.31Z",
      "idempotency_id" : null,
      "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
      "subtype" : "API",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE/payment_instruments"
        },
        "reversals" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE/reversals"
        },
        "fees" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE/fees"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRoE5Ns5hz9fsdKdwuZtUuCE/disputes"
        },
        "source" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers?limit=3"
    },
    "next" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers?limit=3&after_cursor=TRoE5Ns5hz9fsdKdwuZtUuCE"
    }
  },
  "page" : {
    "limit" : 3,
    "next_cursor" : "TRoE5Ns5hz9fsdKdwuZtUuCE"
  }
}

The request returns the three most recent transfers, regardless of the state or value saved in the response.

  • Pass after_cursor=TRt2F1j2ST3ijbsmPVXB6Ztf to get the transfers that are older than the TRt2F1j2ST3ijbsmPVXB6Ztf resource.
Copy
Copied
curl 'https://finix.sandbox-payments-api.com/transfers?limit=3&after_cursor=TRt2F1j2ST3ijbsmPVXB6Ztf' \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  • Pass before_cursor=TRt2F1j2ST3ijbsmPVXB6Ztf to get the transfers that were created after the TRt2F1j2ST3ijbsmPVXB6Ztf resource.
Copy
Copied
curl 'https://finix.sandbox-payments-api.com/transfers?limit=3&before_cursor=TRt2F1j2ST3ijbsmPVXB6Ztf' \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \