List payments
Returns a paginated list of payments visible to the caller. Merchant-scoped API keys are auto-restricted to their own merchant, and test/live mode is fixed by the authenticated key rather than a query parameter. Filters: merchantId, status. Uses cursor-based pagination — pass cursor from a previous response to fetch the next page. Default page size is 20, maximum 100.
Authorization
bearer In: header
Query Parameters
Filter by merchant ID. Merchant-scoped API keys are auto-restricted to their own merchant.
uuidFilter by payment lifecycle status (e.g. authorized, captured, failed).
"processing" | "requires_action" | "requires_capture" | "captured" | "succeeded" | "failed" | "canceled" | "refunded" | "partially_refunded"Filter failed payments by their stable errorCode (e.g. issuer_decline). Useful for drill-in from the dashboard top-failures card.
1 <= lengthFree-text search across payment id, merchant reference, customer email, and card BIN. Prefix-aware: pay_<hex> hits id, @ hits email, six digits hit BIN (when available), everything else matches merchant_reference via trigram similarity.
1 <= length <= 128Accepted for compatibility. Payments always belong to the caller mode.
"true" | "false"Pagination cursor returned from a previous list response.
uuidPage size. Default 20, maximum 100.
201 <= value <= 100Sort by createdAt. Defaults to descending (newest first).
"asc" | "desc"Response Body
application/json
curl -X GET "https://<api-host>/v1/payments"{
"data": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"livemode": true,
"status": "processing",
"merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
"amount": {
"currency": "string",
"valueMinor": 9007199254740991
},
"amountBreakdown": {
"authorized": {
"currency": "string",
"valueMinor": 9007199254740991
},
"captured": {
"currency": "string",
"valueMinor": 9007199254740991
},
"refunded": {
"currency": "string",
"valueMinor": 9007199254740991
},
"fee": {
"currency": "string",
"valueMinor": 9007199254740991
},
"net": {
"currency": "string",
"valueMinor": 9007199254740991
}
},
"captureMethod": "automatic",
"merchantReference": "string",
"checkoutSessionId": "e4b3bd08-5189-40bd-bc1b-0dd256297c90",
"paymentMethodType": "string",
"action": {
"type": "redirect",
"url": "http://example.com",
"data": {
"threeDSToken": "string",
"authenticationMethod": "string",
"displayMessage": "string",
"expiresIn": 0
}
},
"errorCode": "string",
"errorMessage": "string",
"approved": true,
"providerReference": "string",
"threeDSResult": {
"version": "1.0",
"status": "authenticated",
"statusReason": "string",
"eci": "string",
"cavv": "string",
"xid": "string",
"dsTransId": "string",
"enrolled": "Y",
"liabilityShift": true,
"challengeFlow": "frictionless",
"challenged": true,
"challengeCancelled": true,
"exemptionApplied": "low_value",
"messageVersion": "string",
"serverTransId": "string",
"acsTransId": "string"
},
"metadata": {
"property1": "string",
"property2": "string"
},
"createdAt": "string",
"updatedAt": "string"
}
],
"pagination": {
"nextCursor": "string",
"prevCursor": "string",
"hasMore": true,
"totalCount": 0
}
}Get payment by ID
Returns details for a single payment, including current lifecycle status, 3DS result (if applicable), and the latest provider response. Soft-deleted payments are not returned.
Resolve a payment amount mismatch
Idempotently accepts the provider-confirmed amount or retains the originally requested amount, then atomically finalizes the already provider-succeeded payment. Cross-currency reviews can only retain the requested amount. Operator/owner permission only.