Migrating to Cursor Pagination

Learn how to enable cursor pagination for response from Finix's API.

To migrate your requests to use Cursor Pagination:

Send a versioning header with your requests. For more info about including a versioning header, see Versioning .
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/json" \
        -H 'Finix-Version: 2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Example Response

Copy

Copied

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TRtLhSEAHak7isKjZu9x7Gjh",
      "created_at" : "2022-10-10T04:16:27.47Z",
      "updated_at" : "2022-10-10T04:17:05.03Z",
      "additional_buyer_charges" : null,
      "additional_healthcare_data" : null,
      "address_verification" : null,
      "amount" : 100,
      "amount_requested" : 100,
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "currency" : "USD",
      "destination" : "PIe2YvpcjvoVJ6PzoRPBK137",
      "externally_funded" : "UNKNOWN",
      "failure_code" : null,
      "failure_message" : null,
      "fee" : 0,
      "idempotency_id" : null,
      "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
      "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
      "messages" : [ ],
      "raw" : null,
      "ready_to_settle_at" : "2022-10-10T04:17:05.04Z",
      "security_code_verification" : null,
      "source" : null,
      "state" : "SUCCEEDED",
      "statement_descriptor" : "FNX*FINIX FLOWERS",
      "subtype" : "API",
      "tags" : {
        "test" : "refund"
      },
      "trace_id" : "e200c5b9-3ac9-4a21-a69e-cd0ffb6c2490",
      "type" : "REVERSAL",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRtLhSEAHak7isKjZu9x7Gjh"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRtLhSEAHak7isKjZu9x7Gjh/payment_instruments"
        },
        "parent" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRacB6Q6GcW6yvFUKawSnMEP"
        },
        "destination" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
      }
    }, {
      "id" : "TR2fXt8wHuHxjVPZ1MvrnSU8",
      "created_at" : "2022-10-10T03:55:09.70Z",
      "updated_at" : "2022-10-10T03:56:04.68Z",
      "additional_buyer_charges" : null,
      "additional_healthcare_data" : null,
      "address_verification" : null,
      "amount" : 100,
      "amount_requested" : 100,
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "currency" : "USD",
      "destination" : "PIe2YvpcjvoVJ6PzoRPBK137",
      "externally_funded" : "UNKNOWN",
      "failure_code" : null,
      "failure_message" : null,
      "fee" : 0,
      "idempotency_id" : null,
      "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
      "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
      "messages" : [ ],
      "raw" : null,
      "ready_to_settle_at" : "2022-10-10T03:56:04.69Z",
      "security_code_verification" : null,
      "source" : null,
      "state" : "SUCCEEDED",
      "statement_descriptor" : "FNX*FINIX FLOWERS",
      "subtype" : "API",
      "tags" : {
        "test" : "refund"
      },
      "trace_id" : "7260b6d8-9974-49c8-aee5-ecbdacfaca3a",
      "type" : "REVERSAL",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR2fXt8wHuHxjVPZ1MvrnSU8"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TR2fXt8wHuHxjVPZ1MvrnSU8/payment_instruments"
        },
        "parent" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRacB6Q6GcW6yvFUKawSnMEP"
        },
        "destination" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
        },
        "fee_profile" : {
          "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
      }
    }, {
      "id" : "TRuzk139AayVqe1K9eyz18q9",
      "created_at" : "2022-10-10T03:52:06.46Z",
      "updated_at" : "2022-10-10T03:52:06.46Z",
      "additional_buyer_charges" : null,
      "additional_healthcare_data" : null,
      "address_verification" : null,
      "amount" : 30,
      "amount_requested" : 30,
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "currency" : "USD",
      "destination" : null,
      "externally_funded" : "FALSE",
      "failure_code" : null,
      "failure_message" : null,
      "fee" : 0,
      "fee_type" : "ACH_FIXED",
      "idempotency_id" : null,
      "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
      "merchant_identity" : "IDddHpRqwf2VsH2XB1fmLfhM",
      "messages" : [ ],
      "raw" : null,
      "ready_to_settle_at" : "2022-10-10T03:52:07.08Z",
      "security_code_verification" : null,
      "source" : null,
      "state" : "SUCCEEDED",
      "statement_descriptor" : null,
      "subtype" : "PLATFORM_FEE",
      "tags" : { },
      "trace_id" : "4c7c8ecc-2914-4fe4-8565-985870e532ff",
      "type" : "FEE",
      "_links" : {
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRuzk139AayVqe1K9eyz18q9"
        },
        "merchant_identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDddHpRqwf2VsH2XB1fmLfhM"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRuzk139AayVqe1K9eyz18q9/payment_instruments"
        },
        "parent" : {
          "href" : "https://finix.sandbox-payments-api.com/transfers/TRrfaQBfXkc4wopWK6pcrnoR"
        },
        "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=TRuzk139AayVqe1K9eyz18q9"
    }
  },
  "page" : {
    "limit" : 3,
    "next_cursor" : "TRuzk139AayVqe1K9eyz18q9"
  }
}

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 were created after the TRt2F1j2ST3ijbsmPVXB6Ztf resource.

Copy

Copied

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

Pass before_cursor=TRt2F1j2ST3ijbsmPVXB6Ztf to get the Transfers that were created before the TRt2F1j2ST3ijbsmPVXB6Ztf resource.

Copy

Copied

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

Filters

Cursor-based pagination only supports filters on the following endpoints:

/transfers
/authorizations
/payment_instruments
/identities

For a list of the filters available on the above endpoints, review the relevant LIST request:

We're actively working on bringing all filters across all endpoints to cursor pagination. Feel free to reach out to the Finix Support Team if you have any questions.