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
"page": {
"offset": 0,
"limit": 20,
"count": 1241393
}New
"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.
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-a62908e5b30eExample Response
{
"_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=TRt2F1j2ST3ijbsmPVXB6Ztfto get theTransfersthat were created after theTRt2F1j2ST3ijbsmPVXB6Ztfresource.
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=TRt2F1j2ST3ijbsmPVXB6Ztfto get theTransfersthat were created before theTRt2F1j2ST3ijbsmPVXB6Ztfresource.
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.