> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# List Payment Attempts
> The tenant-wide payments log — every gateway payment attempt, newest first, paginated, with an optional status filter and search.
Returns every gateway payment attempt for the tenant, newest first, paginated,
with an optional status filter. Each row carries its invoice number, so the
response reads as the operator's failed-payments log without a second lookup.
A payment *attempt* is one try at settling an invoice through a gateway — a
card charge, an ACH debit, a UPI mandate collection. An invoice can have several
(a card's `failed` → `succeeded`, or an ACH debit's `initiated` → `processing`
→ `succeeded` → `returned`); the invoice's own `amount_paid` reflects only the
ones that settled. See [Explain any number](/advanced/explain-any-number) for
how attempts relate to invoices and the ledger.
## Query Parameters
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | No | Filter to one status: `initiated`, `processing`, `succeeded`, `failed`, or `returned`. |
| `q` | string | No | Case-insensitive substring search on the attempt's `invoice_number` or gateway payment reference (tenant-scoped), newest first. Backs the command-palette payment lookup; the `status` filter is ignored on the search path. |
| `page` | integer | No | Page number. |
| `per_page` | integer | No | Rows per page. |
## Example Request
```bash theme={null}
curl -G https://api.recurso.dev/v1/payment-attempts \
-H "Authorization: Bearer $API_KEY" \
-d status=failed \
-d per_page=25
```
## Response
```json theme={null}
{
"data": [
{
"id": "c2d4e6f8-1a3b-4c5d-9e7f-8a9b0c1d2e3f",
"invoice_id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12",
"invoice_number": "REC/2026/0042",
"currency": "USD",
"gateway": "stripe",
"method": "card",
"gateway_payment_intent_id": "pi_3PqR7sK2eZvKYlo2C0Xy1AbC",
"status": "failed",
"failure_code": "insufficient_funds",
"amount": 118000,
"created_at": "2026-07-02T09:00:00Z",
"settled_at": null
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 1,
"total_pages": 1
}
}
```
## Attempt Fields
| Field | Type | Description |
| ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| `id` | string (uuid) | The attempt's id — fetch it with [Get Payment Attempt](/api-reference/payment-attempts/get) |
| `invoice_id` / `invoice_number` | uuid / string | The invoice the attempt tried to settle |
| `currency` | string | The invoice's currency |
| `gateway` | string | The gateway that processed the attempt (e.g. `stripe`, `razorpay`) |
| `method` | string | The payment method used |
| `gateway_payment_intent_id` | string | The gateway's reference for the attempt |
| `status` | string | `initiated`, `processing`, `succeeded`, `failed`, or `returned` |
| `failure_code` | string | Gateway failure or return code; empty when the attempt succeeded |
| `amount` | integer (int64) | Minor units |
| `created_at` | string (date-time) | When the attempt was made |
| `settled_at` | string (date-time), nullable | When funds settled; `null` until then |
Read-only. Offline payments recorded by hand live under
[List Offline Payments](/api-reference/payments/list-offline), not here.
## OpenAPI
````yaml GET /v1/payment-attempts
openapi: 3.1.0
info:
title: Recurso API
version: 1.0.0
description: |
The Recurso billing engine REST API.
Authenticate by passing your API key as a bearer token:
Authorization: Bearer
Obtain an API key by registering a tenant via `POST /auth/register`.
All authenticated endpoints live under the `/v1` prefix. Mutating
endpoints support idempotency via the `Idempotency-Key` header.
license:
name: MIT
identifier: MIT
servers:
- url: https://billing.example.com
description: >-
Example deployment — substitute the base URL of your own Recurso
deployment.
security:
- bearerAuth: []
tags:
- name: System
description: Health, version, and API metadata
- name: Auth
description: Tenant registration
- name: Plans
description: Product catalog plans
- name: Customers
description: Customer management
- name: Subscriptions
description: Subscription lifecycle
- name: Invoices
description: Invoices, PDFs, and Indian GST e-invoicing
- name: Coupons
description: Discounts
- name: Usage
description: Metered usage events
- name: Credit Notes
description: Customer credits
- name: Quotes
description: Quote-to-invoice lifecycle
- name: Webhooks
description: Webhook endpoint management and event feed
- name: Analytics
description: Revenue analytics
- name: Checkout
description: Public hosted checkout for invoices
- name: Payments
description: Payment order creation
- name: Inbound Webhooks
description: Receivers for payment-gateway callbacks (Razorpay, Stripe)
- name: Customer Portal
description: Customer-facing portal — magic-link auth and session-scoped data
- name: Developer
description: API key management
- name: Account
description: Tenant account settings
- name: Finance
description: Ledger accounts, entries, reconciliation, and revenue recognition
- name: Settings
description: Tax (GST) and e-invoicing (IRP) configuration
- name: Consents
description: Consent records for RBI-compliant recurring billing
- name: Referrals
description: Customer referral program
- name: Gifts
description: Gift subscriptions
- name: Mandates
description: UPI Autopay mandates
- name: Offline Payments
description: Virtual accounts and manually recorded payments
- name: Organizations
description: Multi-entity organizations grouping several tenants
- name: Accounting
description: QuickBooks / Xero accounting integrations
- name: Churn
description: Churn risk scoring and alerts
- name: Cancel Flows
description: Configurable retention flows shown at cancellation time
- name: Dunning
description: Dunning analytics and multi-channel dunning campaigns
paths:
/v1/payment-attempts:
get:
tags:
- Payments
summary: Payments log (tenant-wide payment attempts)
description: >
Every gateway payment attempt for the tenant, newest first, paginated,
with an optional status filter (initiated/processing/succeeded/failed/
returned). Each row carries its invoice number. The operator's failed-
payments log. Read-only.
operationId: listPaymentAttempts
parameters:
- name: status
in: query
required: false
schema:
type: string
enum:
- initiated
- processing
- succeeded
- failed
- returned
- name: q
in: query
required: false
description: >-
Case-insensitive substring search on the attempt's invoice_number or
gateway payment reference (tenant-scoped), newest first. Backs the
command-palette payment lookup; the status filter is ignored on the
search path.
schema:
type: string
- name: page
in: query
required: false
schema:
type: integer
- name: per_page
in: query
required: false
schema:
type: integer
responses:
'200':
description: The payments log page.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
invoice_id:
type: string
format: uuid
invoice_number:
type: string
currency:
type: string
gateway:
type: string
method:
type: string
gateway_payment_intent_id:
type: string
status:
type: string
enum:
- initiated
- processing
- succeeded
- failed
- returned
failure_code:
type: string
amount:
type: integer
format: int64
created_at:
type: string
format: date-time
settled_at:
type: string
format: date-time
nullable: true
pagination:
type: object
properties:
page:
type: integer
per_page:
type: integer
total:
type: integer
total_pages:
type: integer
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````