> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # Retry Payment > Charge the customer's saved payment method again for an unpaid invoice. The invoice must be in status `ISSUED` or `PAYMENT_FAILED`, auto-charge must be on for its subscription, and the invoice must have a payment session. If not, the response is 400. The response status tells you the result. Only 200 means that the charge succeeded. Every other response from this operation that has a `retry_payment_result` body has `success: false`, and `error.code` gives the reason: | Status | `error.code` | Meaning | | --- | --- | --- | | 200 | — | The charge succeeded, the provider had already collected it, or no amount is unpaid. | | 202 | `processing` | The provider accepted the charge. It settles later (for example, a bank debit). | | 402 | a decline code, for example `card_declined`, `insufficient_funds`, `do_not_honor`, `authentication_required` | The provider declined the payment method. | | 409 | `concurrent_attempt` | Another payment attempt for this invoice is in progress. | | 409 | `PAYMENT_SESSION_EXPIRED` | The payment link expired (after 30 days). Create a new link with `POST /v2/invoices/{id}/payment` and `method: hosted_link`, then retry. If the customer also has no usable saved payment method, the response is 422 instead. | | 409 | another value, or no `code` | The payment session cannot be charged in its current state (for example `session_unusable`, `non_confirmable`, `PAYMENT_PROCESSING`, `PAYMENT_ALREADY_COMPLETED`). Read `error.message` for the cause. | | 422 | `no_payment_method` | The customer has no usable saved payment method. Send a payment link instead. | | 502 | `provider_unavailable` or none | The payment provider did not answer, or the provider failed the charge for a reason that is not known. Retry later. | A 500 response has the standard error body, not `retry_payment_result`. It is an internal error, and a retry does not fix it. An invoice that does not exist returns 403, the same as an invoice of another merchant. This operation is rate limited to one call each minute for each invoice. ## OpenAPI ````yaml /openapi.json post /v2/invoices/{id}/retryPayment openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). - name: Webhooks description: >- Endpoints for setting up webhook integrations and administering webhook settings paths: /v2/invoices/{id}/retryPayment: post: tags: - Invoices V2 summary: Retry Payment description: >- Charge the customer's saved payment method again for an unpaid invoice. The invoice must be in status `ISSUED` or `PAYMENT_FAILED`, auto-charge must be on for its subscription, and the invoice must have a payment session. If not, the response is 400. The response status tells you the result. Only 200 means that the charge succeeded. Every other response from this operation that has a `retry_payment_result` body has `success: false`, and `error.code` gives the reason: | Status | `error.code` | Meaning | | --- | --- | --- | | 200 | — | The charge succeeded, the provider had already collected it, or no amount is unpaid. | | 202 | `processing` | The provider accepted the charge. It settles later (for example, a bank debit). | | 402 | a decline code, for example `card_declined`, `insufficient_funds`, `do_not_honor`, `authentication_required` | The provider declined the payment method. | | 409 | `concurrent_attempt` | Another payment attempt for this invoice is in progress. | | 409 | `PAYMENT_SESSION_EXPIRED` | The payment link expired (after 30 days). Create a new link with `POST /v2/invoices/{id}/payment` and `method: hosted_link`, then retry. If the customer also has no usable saved payment method, the response is 422 instead. | | 409 | another value, or no `code` | The payment session cannot be charged in its current state (for example `session_unusable`, `non_confirmable`, `PAYMENT_PROCESSING`, `PAYMENT_ALREADY_COMPLETED`). Read `error.message` for the cause. | | 422 | `no_payment_method` | The customer has no usable saved payment method. Send a payment link instead. | | 502 | `provider_unavailable` or none | The payment provider did not answer, or the provider failed the charge for a reason that is not known. Retry later. | A 500 response has the standard error body, not `retry_payment_result`. It is an internal error, and a retry does not fix it. An invoice that does not exist returns 403, the same as an invoice of another merchant. This operation is rate limited to one call each minute for each invoice. operationId: retryInvoicePayment parameters: - in: path name: id required: true schema: type: string description: The invoice ID requestBody: content: application/json: schema: type: object properties: reason: type: string description: Optional reason for the manual retry (for audit logging) responses: '200': description: >- The charge succeeded, the provider had already collected it, or the invoice has no unpaid amount. `success` is `true`. content: application/json: schema: $ref: '#/components/schemas/RetryPaymentResponse' example: object: retry_payment_result success: true invoiceId: inv_a1b2c3d4e5f6g7h8 paymentIntentId: pi_1234567890abcdef '202': description: >- The provider accepted the charge and it settles later. `error.code` is `processing`. The invoice changes to `PAID` when the payment settles. content: application/json: schema: $ref: '#/components/schemas/RetryPaymentResponse' example: object: retry_payment_result success: false invoiceId: inv_a1b2c3d4e5f6g7h8 paymentIntentId: pi_1234567890abcdef error: message: 'Payment is settling asynchronously: processing' code: processing '400': $ref: '#/components/responses/BadRequest' '402': description: >- The provider declined the payment method. `error.code` and `error.declineCode` give the reason. content: application/json: schema: $ref: '#/components/schemas/RetryPaymentResponse' example: object: retry_payment_result success: false invoiceId: inv_a1b2c3d4e5f6g7h8 paymentIntentId: pi_1234567890abcdef error: message: 'Payment failed: card_declined' type: card_error code: card_declined declineCode: insufficient_funds '403': $ref: '#/components/responses/Forbidden' '409': description: >- The payment session cannot be charged now. `error.code` gives the reason when one is known: `concurrent_attempt` (another attempt is in progress), `PAYMENT_SESSION_EXPIRED` (the payment link expired; create a new link first), or another value such as `session_unusable`, `non_confirmable`, `PAYMENT_PROCESSING` or `PAYMENT_ALREADY_COMPLETED`. `error.code` can be absent; then read `error.message`. content: application/json: schema: $ref: '#/components/schemas/RetryPaymentResponse' example: object: retry_payment_result success: false invoiceId: inv_a1b2c3d4e5f6g7h8 error: message: Payment session has expired code: PAYMENT_SESSION_EXPIRED '422': description: >- The customer has no usable saved payment method. `error.code` is `no_payment_method`. Send a payment link instead. content: application/json: schema: $ref: '#/components/schemas/RetryPaymentResponse' example: object: retry_payment_result success: false invoiceId: inv_a1b2c3d4e5f6g7h8 error: message: 'Cannot retry payment: no usable stored payment method' code: no_payment_method '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' '502': description: >- The payment provider did not answer, or the provider failed the charge for a reason that is not known. Retry later. content: application/json: schema: $ref: '#/components/schemas/RetryPaymentResponse' example: object: retry_payment_result success: false invoiceId: inv_a1b2c3d4e5f6g7h8 error: message: >- Cannot retry payment: the payment provider did not answer. Try again later. code: provider_unavailable components: schemas: RetryPaymentResponse: type: object required: - object - success - invoiceId properties: object: type: string enum: - retry_payment_result description: The object type success: type: boolean description: >- True only when the charge succeeded or no amount is unpaid. The response status is 200 only when this is true. invoiceId: type: string description: The invoice ID paymentIntentId: type: string description: >- The provider's payment reference for the charge, when the provider has one. error: $ref: '#/components/schemas/RetryPaymentError' description: Present when `success` is false. description: >- The result of a payment retry. Every response status of the retry operation that is not an error envelope uses this shape. Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found RetryPaymentError: type: object properties: message: type: string description: Human-readable message. Do not parse it; use `code`. type: type: string description: Error category, for example `card_error` or `processing`. code: type: string description: >- Machine-readable reason. See the operation description for the values. declineCode: type: string description: The card decline code from the provider, when one is available. required: - message description: Why a payment retry did not collect the money. ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format responses: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.