List Intents & Withdrawals

Cursor-paginated reconciliation listings with time range, status filters, and opaque cursors.

Status lookup endpoints are for a single record. When you need time-windowed listing for nightly reconciliation or backfill, use the two endpoints below. Both share the same contract: cursor-paginated and newest-first.

List deposit intents

GET /api/v1/external/intents

Filter parameters are optional.

APPROVED deposits from the last 24 hours

curl "$PIENTEGRA_API_BASE/external/intents?createdFrom=2026-04-27T00:00:00Z&status=APPROVED&limit=100" \
  -H "Authorization: Bearer $PIENTEGRA_API_KEY"

List withdrawals

GET /api/v1/external/withdrawals

Same contract.

SENT + RETURNED withdrawals in a window

curl "$PIENTEGRA_API_BASE/external/withdrawals?createdFrom=2026-04-27T00:00:00Z&createdTo=2026-04-28T00:00:00Z&status=SENT,RETURNED" \
  -H "Authorization: Bearer $PIENTEGRA_API_KEY"

Query parameters

Parameter	Type	Description
`createdFrom`	ISO 8601	Lower bound, inclusive. If omitted, the range is unbounded into the past.
`createdTo`	ISO 8601	Upper bound, exclusive. If omitted, the range continues through the current time.
`status`	comma-separated	One or more statuses. Unknown values return `validation_failed`.
`cursor`	opaque string	Returned from the previous response's `nextCursor` field.
`limit`	int	1..100, default 50.

Allowed status values:

Surface	Statuses
`intents`	`RESERVED`, `PENDING_REVIEW`, `APPROVED`, `REJECTED`, `AUTO_CANCELLED`, `LATE_ARRIVAL`
`withdrawals`	`PENDING_REVIEW`, `APPROVED`, `SENT`, `REJECTED`, `RETURNED`

Response shape

{
  "data": [
    {
      "intentId": "01927b3c-...",
      "referenceNo": "5MDLZBFDY7",
      "status": "APPROVED",
      "requestedAmount": "100000",
      "amount": "100000",
      "currency": "TRY",
      "approvedAt": "2026-04-28T13:00:00.000Z",
      "rejectedAt": null,
      "rejectedReason": null
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0wNC0yOFQxMjo1OToyMC4xMTJaIiwiaSI6IjAxOWRk..."
}

nextCursor is opaque. Partners must not parse it; send it back unchanged as the cursor parameter on the next request. If nextCursor is null, the range is exhausted.

Pagination example

Iterate everything in a window

async function* iterateIntents(from: string, to: string) {
  let cursor: string | null = null;
  while (true) {
    const url = new URL(`${process.env.PIENTEGRA_API_BASE}/external/intents`);
    url.searchParams.set('createdFrom', from);
    url.searchParams.set('createdTo', to);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.PIENTEGRA_API_KEY!}` },
    });
    const body = await res.json();
    for (const intent of body.data) yield intent;
    if (!body.nextCursor) return;
    cursor = body.nextCursor;
  }
}

Reconciliation pattern

Webhook delivery is the primary channel; list endpoints are secondary. Recommended usage:

Write every event from the webhook handler to the partner database.
Once per hour or day, pull the same time window from this endpoint and diff the records.
If records are missing because the handler was temporarily unavailable, process them according to their current status. You can also request replay for webhook events through the Events Surface.

Status changes arrive by webhook. This list always reflects the latest state, so intermediate states may be missed. If you maintain partner balance accounting, webhook events are the more reliable ledger input.