LostChurn Docs

Query failed payments, retrieve payment details, and trigger manual retries via the LostChurn REST API.

The Payments API lets you list failed payments, retrieve details for a specific payment, and manually trigger retries.

Endpoints

Method	Path	Description
`GET`	`/v1/payments`	List payments
`GET`	`/v1/payments/:id`	Get a payment
`POST`	`/v1/payments/:id/retry`	Retry a payment

List Payments

Retrieve a paginated list of payments, optionally filtered by status, customer, date range, or decline category.

GET /v1/payments

Query Parameters

Parameter	Type	Default	Description
`status`	`string`	all	Filter by status: `pending`, `retrying`, `recovered`, `terminal`, `communication_pending`
`customer_id`	`string`	--	Filter by customer ID
`decline_category`	`string`	--	Filter by category: `soft_retry`, `hard_customer`, `terminal`, `unknown`
`psp`	`string`	--	Filter by payment processor: `stripe`, `braintree`, etc.
`currency`	`string`	--	Filter by ISO currency code
`amount_min`	`integer`	--	Minimum amount in smallest currency unit
`amount_max`	`integer`	--	Maximum amount in smallest currency unit
`created_after`	`string`	--	ISO 8601 datetime. Return payments created after this time
`created_before`	`string`	--	ISO 8601 datetime. Return payments created before this time
`sort`	`string`	`created_at`	Sort field: `created_at`, `amount`, `status`
`order`	`string`	`desc`	Sort order: `asc`, `desc`
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`20`	Results per page (max: 100)

Example Request

curl "https://api.lostchurn.com/v1/payments?status=pending&decline_category=soft_retry&per_page=5" \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": [
    {
      "id": "pay_abc123",
      "customer_id": "cus_def456",
      "subscription_id": "sub_ghi789",
      "amount": 4999,
      "currency": "usd",
      "status": "pending",
      "decline_code": "insufficient_funds",
      "decline_category": "soft_retry",
      "decline_subcategory": "balance",
      "psp": "stripe",
      "psp_payment_id": "pi_3ABC123DEF456",
      "retry_count": 0,
      "max_retries": 4,
      "next_retry_at": "2025-03-10T06:00:00Z",
      "created_at": "2025-03-08T14:30:00Z",
      "updated_at": "2025-03-08T14:30:00Z"
    },
    {
      "id": "pay_jkl012",
      "customer_id": "cus_mno345",
      "subscription_id": "sub_pqr678",
      "amount": 9900,
      "currency": "usd",
      "status": "pending",
      "decline_code": "generic_decline",
      "decline_category": "soft_retry",
      "decline_subcategory": "generic",
      "psp": "stripe",
      "psp_payment_id": "pi_3XYZ789GHI012",
      "retry_count": 1,
      "max_retries": 3,
      "next_retry_at": "2025-03-10T12:00:00Z",
      "created_at": "2025-03-07T09:15:00Z",
      "updated_at": "2025-03-08T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "page": 1,
    "per_page": 5,
    "total_pages": 10
  }
}

Get a Payment

Retrieve details for a single payment, including its full retry history.

GET /v1/payments/:id

Example Request

curl https://api.lostchurn.com/v1/payments/pay_abc123 \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": {
    "id": "pay_abc123",
    "customer_id": "cus_def456",
    "subscription_id": "sub_ghi789",
    "amount": 4999,
    "currency": "usd",
    "status": "recovered",
    "decline_code": "insufficient_funds",
    "decline_category": "soft_retry",
    "decline_subcategory": "balance",
    "psp": "stripe",
    "psp_payment_id": "pi_3ABC123DEF456",
    "retry_count": 2,
    "max_retries": 4,
    "created_at": "2025-03-08T14:30:00Z",
    "recovered_at": "2025-03-10T06:12:00Z",
    "updated_at": "2025-03-10T06:12:00Z",
    "customer": {
      "id": "cus_def456",
      "email": "customer@example.com",
      "name": "Jane Smith"
    },
    "retries": [
      {
        "attempt": 1,
        "status": "failed",
        "decline_code": "insufficient_funds",
        "attempted_at": "2025-03-09T06:00:00Z"
      },
      {
        "attempt": 2,
        "status": "succeeded",
        "decline_code": null,
        "attempted_at": "2025-03-10T06:12:00Z"
      }
    ]
  }
}

Retry a Payment

Manually trigger an immediate retry for a failed payment. The payment must be in pending or communication_pending status.

POST /v1/payments/:id/retry

Example Request

curl -X POST https://api.lostchurn.com/v1/payments/pay_abc123/retry \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -H "Content-Type: application/json"

Example Response (Retry Initiated)

{
  "data": {
    "id": "pay_abc123",
    "status": "retrying",
    "retry_count": 3,
    "retry_initiated_at": "2025-03-08T15:00:00Z",
    "message": "Retry submitted to payment processor."
  }
}

Example Response (Cannot Retry)

{
  "error": {
    "code": "state_conflict",
    "message": "Payment pay_abc123 is in 'terminal' status and cannot be retried.",
    "request_id": "req_9876543210"
  }
}

Manual retries count toward your plan's monthly recovery attempt limit. Use them judiciously for specific cases rather than as a bulk recovery strategy.

Retry Rules

Current Status	Can Retry?
`pending`	Yes
`retrying`	No (retry already in progress)
`communication_pending`	Yes
`recovered`	No (already recovered)
`terminal`	No (permanently failed)

Payment Object

Field	Type	Description
`id`	`string`	LostChurn payment ID
`customer_id`	`string`	Customer ID from your PSP
`subscription_id`	`string`	Subscription ID from your PSP
`amount`	`integer`	Amount in smallest currency unit
`currency`	`string`	ISO 4217 currency code
`status`	`string`	Current status (see table above)
`decline_code`	`string`	Raw decline code from PSP
`decline_category`	`string`	LostChurn category
`decline_subcategory`	`string`	LostChurn subcategory
`psp`	`string`	Payment processor name
`psp_payment_id`	`string`	Payment ID in your PSP
`retry_count`	`integer`	Number of retries attempted
`max_retries`	`integer`	Maximum retries allowed for this decline
`next_retry_at`	`string \| null`	Scheduled time for next retry
`recovered_at`	`string \| null`	Timestamp of successful recovery
`created_at`	`string`	When the payment failure was recorded
`updated_at`	`string`	Last update timestamp

Next Steps

Customers API -- query customer data and payment history
Campaigns API -- manage dunning campaigns
Decline Codes -- complete decline code reference

Payments API

On this page