Recover and reconcile state

Store every resource ID Gnosis Pay returns. But requests can still be interrupted: a timeout, a crash, or a dropped connection can leave you not knowing whether a resource was created. Design a recovery path for each step, so you can find out what exists before you retry.

Find existing resources

Resource	How to find it
KYC profile	`GET /kyc/profiles?external_reference={your_user_reference}`
Account	`GET /accounts?external_reference={your_account_reference}`
Cardholders	`GET /cardholders?account_id={account_id}`
Cards	`GET /cards?account_id={account_id}`
Card transaction	`GET /card-transactions?account_id={account_id}`, then `GET /card-transactions/{card_transaction_id}`
Deposit	`GET /deposits?account_id={account_id}`, then `GET /deposits/{deposit_id}`
Withdrawal	`GET /withdrawals?account_id={account_id}`, then `GET /withdrawals/{withdrawal_id}`

Retrying a create request can make a duplicate. Look the resource up first, and only retry if it doesn’t exist. See Errors and idempotency for which requests are safe to retry.

Page through results

List endpoints use cursor pagination. While pagination.has_next is true, request the next page by passing pagination.next_page_cursor as the page_cursor parameter.

TypeScript

async function listAll<T>(path: string): Promise<T[]> {
  const items: T[] = [];
  let cursor: string | undefined;

  do {
    const url = new URL(`${PARTNER_API_BASE_URL}${path}`);
    if (cursor) url.searchParams.set("page_cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    const page = await response.json();

    items.push(...page.data);
    cursor = page.pagination.has_next
      ? page.pagination.next_page_cursor
      : undefined;
  } while (cursor);

  return items;
}

Reconcile account activity

The Partner API does not provide one combined statement. Reconcile each resource independently:

List card transactions with GET /card-transactions?account_id={account_id}, then read a specific lifecycle with GET /card-transactions/{card_transaction_id}.
List deposits with GET /deposits?account_id={account_id}, then confirm one with GET /deposits/{deposit_id}.
List withdrawals with GET /withdrawals?account_id={account_id}, then confirm one with GET /withdrawals/{withdrawal_id}.

Store the resource IDs and reconcile against the latest API state after processing webhook events. Card transaction records can change as a payment clears, reverses, is cancelled, or is declined; compare updated_at, status, and the current amounts instead of treating the first response as final. If your product needs a single account timeline, page through the three list endpoints independently, merge the results in your backend, and sort them by created_at. A pagination cursor is valid only for the endpoint and filters that produced it.

Next step

Errors and idempotency

Handle errors, retries, and asynchronous operations safely.

Getting started

Manage Accounts

Manage Cards

Webhooks

Operations

Recover and reconcile state

Find existing resources

Page through results

Reconcile account activity

Next step

Errors and idempotency

​Find existing resources

​Page through results

​Reconcile account activity

​Next step

Errors and idempotency

Find existing resources

Page through results

Reconcile account activity

Next step