> ## 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.
# Invoice Payment Attempts
> An invoice's payment attempts, oldest first — the retry and settlement history, each with status, failure code, gateway reference, amount, and settled-at.
Returns the invoice's payment attempts, oldest first — its retry/settlement
history: a card's `failed` → `succeeded`, or an ACH debit's `initiated` →
`processing` → `succeeded` → `returned`. Each attempt carries its status,
failure code, gateway and payment-intent reference, amount, and settled-at.
Read this alongside the [status timeline](/api-reference/invoices/status-history)
(what the invoice's status did) and the
[journal entries](/api-reference/invoices/journal-entries) (what the ledger
recorded): a succeeded attempt is what produces the invoice's Code-3 payment
posting. See [Explain any number](/advanced/explain-any-number).
## Example Request
```bash theme={null}
curl "https://api.recurso.dev/v1/invoices/06c151de-8d3a-4b21-9c77-2f0e5a9b4d12/payment-attempts" \
-H "Authorization: Bearer $API_KEY"
```
## Example Response
```json theme={null}
{
"data": {
"invoice_id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12",
"attempts": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"invoice_id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12",
"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
},
{
"id": "c2d4e6f8-1a3b-4c5d-9e7f-8a9b0c1d2e3f",
"invoice_id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12",
"gateway": "stripe",
"method": "card",
"gateway_payment_intent_id": "pi_3PqR7sK2eZvKYlo2C0Xy1DeF",
"status": "succeeded",
"failure_code": "",
"amount": 118000,
"created_at": "2026-07-03T14:22:00Z",
"settled_at": "2026-07-03T14:22:10Z"
}
]
}
}
```
## Attempt Fields
| Field | Type | Description |
| --------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| `id` | string (uuid) | The attempt's id — fetch it with [Get Payment Attempt](/api-reference/payment-attempts/get) |
| `gateway` | string | The gateway that processed the attempt |
| `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. An existing invoice with no attempts returns an empty `attempts`
list; a missing or cross-tenant `id` returns `404`.
## OpenAPI
````yaml GET /v1/invoices/{id}/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/invoices/{id}/payment-attempts:
get:
tags:
- Invoices
summary: Invoice payment attempts (settlement history)
description: >
An invoice's payment attempts, oldest first — the retry/settlement
history: a card's failed → succeeded, or an ACH debit's initiated →
processing → succeeded → returned. Each attempt carries its status,
failure code, gateway + payment-intent reference, amount, and
settled-at. Read-only; an existing invoice with no attempts returns an
empty list.
operationId: getInvoicePaymentAttempts
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The invoice's payment attempts.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
invoice_id:
type: string
format: uuid
attempts:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
invoice_id:
type: string
format: uuid
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
'404':
description: Invoice not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````