> ## Documentation Index > Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cobrar assinatura inadimplente > Cobre o ciclo atual, ou todos os ciclos em aberto, de uma assinatura de cartão inadimplente no cartão salvo. Disponível só para contas liberadas para a política `retry_then_unpaid`, e só para assinaturas de cartão em `unpaid`. A cobrança usa o cartão salvo na assinatura e passa pelas mesmas verificações da renovação automática. **Escolher os ciclos.** `cycles` é obrigatório. Uma assinatura pode ter vários ciclos em aberto quando ficou `unpaid` por mais de um período. * `current` cobra um ciclo, o que cobre o dia de hoje, e perdoa os ciclos em aberto mais antigos. * `all` cobra todos os ciclos em aberto numa transação só, no valor do ciclo vezes o número de ciclos em aberto. A taxa repassada ao comprador incide sobre esse total. Nos dois casos, a cobrança aprovada avança a assinatura no calendário original: uma assinatura que vence no dia 31 continua vencendo no último dia de cada mês. Ela volta para `active` quando o ciclo pago ainda cobre o momento em que a cobrança é aplicada; confira `subscription.status` na resposta. Com um ciclo em aberto, as duas opções cobram o mesmo. `GET /v2/subscriptions/{id}` devolve os ciclos em aberto em `nextManualCharge`: `openCycles`, o ciclo que cobre o dia de hoje (`currentPeriodStart`, `currentPeriodEnd`), o valor base de um ciclo (`cycleAmount`) e o de cobrar todos (`allCyclesAmount`), em centavos. A troca de plano agendada é aplicada antes da cobrança, então os dois valores já saem pelo preço do plano novo. A resposta e o `subscription.renewed` trazem `cyclesCharged` e `cyclesForgiven` (`cycles_charged` e `cycles_forgiven` no webhook). **Cobrança recusada.** A assinatura continua `unpaid` e sai o `subscription.payment_failed`. Depois de uma recusa, a próxima cobrança da mesma assinatura só é aceita após 24 horas. Quando o cartão é recusado em definitivo, a resposta é `PAYMENT_METHOD_REPLACEMENT_REQUIRED`, e o cartão precisa ser trocado antes de cobrar de novo. **Cobrar os ciclos que você mostrou.** Envie `expected_period_start` com o início do ciclo em aberto mais antigo que você mostrou ou confirmou, e `expected_open_cycles` com quantos ciclos em aberto você mostrou, normalmente o `nextManualCharge.periodStart` e o `nextManualCharge.openCycles` de `GET /v2/subscriptions/{id}`. Se outra cobrança (outra tela, outra integração) já encerrou o ciclo mais antigo, ou se um ciclo novo abriu depois da leitura, a resposta é `409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED` e nada é cobrado; leia a assinatura de novo para ver os ciclos em aberto agora. Sem os campos, são cobrados os ciclos em aberto no momento do pedido. **Repetições.** Envie `idempotency_key` para repetir com segurança: a mesma chave devolve o resultado do primeiro pedido em vez de cobrar de novo. A resposta `SUBSCRIPTION_CHARGE_INDETERMINATE` significa que a cobrança ainda não teve resultado: a assinatura continua `unpaid` e novas cobranças são recusadas enquanto ela estiver em aberto. Se ela se resolver como paga, esse pagamento não é aplicado à assinatura sozinho: novas cobranças respondem `MANUAL_CHARGE_PENDING_RESOLUTION`, para o mesmo ciclo nunca ser cobrado duas vezes, até o suporte resolver esse pagamento. ## OpenAPI ````yaml api-reference/openapi-v2.json POST /v2/subscriptions/{id}/charge openapi: 3.1.0 info: title: Pagou API - v2 description: API for Pagou.ai Gateway version: 2.0.0 contact: name: Support url: https://pagou.ai email: support@pagou.ai servers: - url: https://api.pagou.ai description: Production server - url: https://api.sandbox.pagou.ai description: Sandbox server for testing security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] paths: /v2/subscriptions/{id}/charge: post: tags: - Subscriptions summary: Charge an Unpaid Subscription description: >- Charge an `unpaid` subscription on its saved card, through the same checks as a renewal. With `cycles: "current"` it charges the cycle that covers today and forgives the older open cycles; with `cycles: "all"` it charges every open cycle in one transaction. Either way a paid charge moves the subscription along its original billing calendar and emits `subscription.renewed` with `cycles_charged` and `cycles_forgiven`; it returns to `active` when the paid cycle still covers the moment the charge is applied, so read `subscription.status` in the response. A declined charge leaves it `unpaid` and emits `subscription.payment_failed`. Send `idempotency_key` to make retries safe: the same key returns the outcome of the first request. Send `expected_period_start` and `expected_open_cycles` with the open cycles you showed or confirmed: if another charge already settled the oldest one, or a new cycle opened since, the request answers 409 `SUBSCRIPTION_CHARGE_CYCLE_CHANGED` and charges nothing. operationId: postSubscriptionsByIdCharge parameters: - schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true description: Public subscription id (UUID). requestBody: required: true content: application/json: schema: type: object properties: cycles: type: string enum: - current - all description: >- Which open cycles to charge. `current` charges the cycle that covers today and forgives the older open cycles; `all` charges every open cycle in one transaction. With one open cycle both charge the same. idempotency_key: type: string minLength: 1 maxLength: 255 expected_period_start: description: >- Start of the oldest open cycle you showed or confirmed (`nextManualCharge.periodStart` from GET by id). When another charge already settled it, the request is refused with 409 `SUBSCRIPTION_CHARGE_CYCLE_CHANGED` and nothing is charged. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ expected_open_cycles: description: >- Number of open cycles you showed or confirmed (`nextManualCharge.openCycles` from GET by id). When a new cycle opened since then, the request is refused with 409 `SUBSCRIPTION_CHARGE_CYCLE_CHANGED` and nothing is charged. type: integer minimum: 1 maximum: 3660 required: - cycles responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean requestId: type: string data: type: object properties: subscription: type: object properties: id: type: string description: Public subscription id (UUID). customerId: type: string description: >- Public customer id (UUID) the subscription belongs to. status: type: string enum: - incomplete - trialing - active - past_due - unpaid - cancel_scheduled - canceled description: Current subscription status. paymentMethod: type: string enum: - credit_card - pix_automatic description: How each cycle is paid. billingModel: type: string enum: - merchant_initiated - provider_initiated description: >- `provider_initiated` when each cycle is debited automatically under a recurring authorization the customer approved. billingDayOfMonth: nullable: true description: Day of month cycles are billed, when fixed. type: integer minimum: 1 maximum: 31 interval: type: string enum: - day - week - month description: Billing interval unit. intervalCount: type: integer minimum: 1 maximum: 365 description: Number of interval units per billing cycle. amount: type: integer minimum: 0 maximum: 100000000 description: Billing amount in cents. currency: type: string enum: - BRL - MXN - COP - CLP - ARS - PEN - USD - GTQ - CRC - NIO - PYG - UYU - BOB - PHP - RUB - INR - SAR - AED - KWD - QAR - OMR - KHR - SGD - IDR - KRW - THB - MYR - HKD - CNY - EGP - EUR - GBP - BHD - MAD - AUD - CAD - CHF - NZD - PLN - KZT - UZS - JPY - GLC description: Billing currency. trialEnd: nullable: true description: Trial end timestamp, when applicable. type: string format: date-time currentPeriodStart: description: Start of the current billing period. type: string format: date-time currentPeriodEnd: description: End of the current billing period. type: string format: date-time cancelAtPeriodEnd: type: boolean description: Whether cancellation is scheduled at period end. canceledAt: nullable: true description: Cancellation timestamp, when canceled. type: string format: date-time failurePolicy: type: string enum: - immediate_cancel - retry_then_cancel - retry_then_unpaid description: Behavior on a failed billing attempt. retryOffsetsDays: type: array items: type: integer minimum: 1 maximum: 30 description: Days after a failed attempt to retry. cancellationReason: nullable: true description: >- Reason for cancellation, when canceled. `completed` when the last of `maxCycles` charges was paid. type: string enum: - user_requested - payment_failure - chargeback - system - admin_requested - completed cycleCount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Current billing cycle, starting at 1. Without a trial it equals the number of paid charges. maxCycles: nullable: true description: >- Number of paid charges after which the subscription ends, or null when it has no end. type: integer minimum: 2 maximum: 120 customerEmail: type: string description: Email of the subscriber. cardLast4: nullable: true description: >- Last four digits of the billing card, for card subscriptions. type: string metadata: nullable: true description: Custom metadata. type: object additionalProperties: {} informations: nullable: true description: >- Custom key/value metadata you attached on create, echoed back. maxItems: 50 type: array items: type: object properties: key: type: string minLength: 1 maxLength: 64 description: Key of the additional information entry. value: type: string minLength: 1 maxLength: 255 description: Value of the additional information entry. required: - key - value additionalProperties: false products: type: array items: type: object properties: name: type: string maxLength: 255 description: Catalog product name. price: type: integer minimum: 0 maximum: 100000000 description: Unit price in cents. quantity: type: integer minimum: 1 maximum: 999999 description: Quantity included in the subscription. tangible: type: boolean description: Whether the product is a tangible good. sku: description: Optional SKU. type: string maxLength: 255 required: - name - price - quantity - tangible additionalProperties: false description: Snapshot of catalog products billed each cycle. productId: description: >- Public id of the catalog product billed by this subscription. Included on GET and LIST. nullable: true type: string productFamilyId: description: >- Public id of the product family the plan belongs to. Included on GET and LIST. nullable: true type: string pendingChange: description: >- Scheduled plan change, when one is pending. Included on GET and LIST. nullable: true type: object properties: productId: type: string description: >- Public id of the plan that takes effect at the period end. amount: type: integer minimum: 0 maximum: 100000000 description: >- Amount in cents that the renewal will bill: the scheduled plan plus whatever is billed alongside it. effectiveAt: description: When the scheduled plan takes effect. type: string format: date-time required: - productId - amount - effectiveAt additionalProperties: false authorization: description: >- Pending customer authorization for PIX automatic subscriptions. type: object properties: type: type: string enum: - pix_qr qr_code: type: string description: >- PIX copy-and-paste code the customer uses to authorize the recurring debit. payment_link_url: description: >- Hosted page where the customer can authorize, when provided. type: string expires_at: nullable: true description: >- When the authorization code expires, when known. type: string format: date-time status: type: string enum: - awaiting_customer required: - type - qr_code - expires_at - status additionalProperties: false recurringAuthorization: nullable: true description: >- Recurring debit authorization, for subscriptions whose cycles are debited automatically. type: object properties: status: type: string enum: - pending - approved - rejected - cancel_pending - canceled description: >- State of the customer's recurring debit authorization. lastDebit: description: >- Most recent debit attempt. Included on GET by id. nullable: true type: object properties: status: type: string enum: - succeeded - failed failureCode: nullable: true type: string enum: - debit_rejected at: nullable: true type: string format: date-time required: - status - failureCode - at additionalProperties: false required: - status additionalProperties: false transactions: description: >- Transactions billed under this subscription. Included on GET by id. type: array items: type: object properties: id: type: string description: Public transaction id. status: type: string description: Transaction status. amount: type: integer minimum: 0 maximum: 100000000 description: Transaction amount in cents. paidAmount: type: integer minimum: 0 maximum: 100000000 description: Amount paid in cents. refundedAmount: type: integer minimum: 0 maximum: 100000000 description: Amount refunded in cents. currency: type: string enum: - BRL - MXN - COP - CLP - ARS - PEN - USD - GTQ - CRC - NIO - PYG - UYU - BOB - PHP - RUB - INR - SAR - AED - KWD - QAR - OMR - KHR - SGD - IDR - KRW - THB - MYR - HKD - CNY - EGP - EUR - GBP - BHD - MAD - AUD - CAD - CHF - NZD - PLN - KZT - UZS - JPY - GLC description: Transaction currency. externalRef: nullable: true description: External reference, when provided. type: string createdAt: description: Transaction creation timestamp. type: string format: date-time paidAt: nullable: true description: Payment confirmation timestamp. type: string format: date-time required: - id - status - amount - paidAmount - refundedAmount - currency - externalRef - createdAt - paidAt additionalProperties: false nextManualCharge: description: >- Open cycles a manual charge settles now. Included on GET by id while the subscription is `unpaid`. type: object properties: periodStart: description: >- Start of the oldest open cycle. Send it as `expected_period_start`. type: string format: date-time periodEnd: description: >- End of that cycle, on the subscription's original billing calendar. type: string format: date-time openCycles: type: integer minimum: 1 maximum: 9007199254740991 description: >- Open cycles up to the one that covers today, on the original billing calendar. currentPeriodStart: description: Start of the open cycle that covers today. type: string format: date-time currentPeriodEnd: description: End of the open cycle that covers today. type: string format: date-time cycleAmount: type: integer minimum: 0 maximum: 9007199254740991 description: >- Base amount in cents of one cycle, before any fee passed to the buyer. A scheduled plan change applies first, so it is the new plan's price. allCyclesAmount: type: integer minimum: 0 maximum: 9007199254740991 description: >- Base amount in cents of charging every open cycle: `cycleAmount` times `openCycles`. required: - periodStart - periodEnd - openCycles - currentPeriodStart - currentPeriodEnd - cycleAmount - allCyclesAmount additionalProperties: false createdAt: description: Subscription creation timestamp. type: string format: date-time updatedAt: nullable: true description: Last update timestamp. type: string format: date-time required: - id - customerId - status - paymentMethod - billingModel - billingDayOfMonth - interval - intervalCount - amount - currency - trialEnd - currentPeriodStart - currentPeriodEnd - cancelAtPeriodEnd - canceledAt - failurePolicy - retryOffsetsDays - cancellationReason - cycleCount - maxCycles - customerEmail - cardLast4 - metadata - informations - products - recurringAuthorization - createdAt - updatedAt additionalProperties: false charge: type: object properties: transactionId: type: string description: Public id of the paid transaction. status: type: string enum: - paid periodStart: description: >- Start of what this charge paid: the cycle that covers today, or the oldest open cycle with `all`. type: string format: date-time periodEnd: description: >- End of the cycle that covers today, where the subscription now stands. type: string format: date-time cyclesCharged: type: integer minimum: 1 maximum: 9007199254740991 description: Cycles this charge paid. cyclesForgiven: type: integer minimum: 0 maximum: 9007199254740991 description: Older open cycles settled without charge. required: - transactionId - status - periodStart - periodEnd - cyclesCharged - cyclesForgiven additionalProperties: false required: - subscription - charge additionalProperties: false required: - success - requestId - data additionalProperties: false example: success: true requestId: 0190a2b4-18a7-7de0-9a43-69b7cf261201 data: subscription: id: string customerId: string status: incomplete paymentMethod: credit_card billingModel: merchant_initiated billingDayOfMonth: 1 interval: day intervalCount: 1 amount: 0 currency: BRL trialEnd: '2026-07-14T12:00:00.000Z' currentPeriodStart: '2026-07-14T12:00:00.000Z' currentPeriodEnd: '2026-07-14T12:00:00.000Z' cancelAtPeriodEnd: false canceledAt: '2026-07-14T12:00:00.000Z' failurePolicy: immediate_cancel retryOffsetsDays: - 1 cancellationReason: user_requested cycleCount: 1 maxCycles: 2 customerEmail: string cardLast4: string metadata: {} informations: - key: string value: string products: - name: string price: 0 quantity: 1 tangible: false recurringAuthorization: status: pending createdAt: '2026-07-14T12:00:00.000Z' updatedAt: '2026-07-14T12:00:00.000Z' charge: transactionId: string status: paid periodStart: '2026-07-14T12:00:00.000Z' periodEnd: '2026-07-14T12:00:00.000Z' cyclesCharged: 1 cyclesForgiven: 0 '402': description: HTTP 402 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '404': description: HTTP 404 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '409': description: HTTP 409 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '422': description: HTTP 422 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' '503': description: HTTP 503 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} default: description: RFC 7807 Problem Details error response content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] components: schemas: ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string code: type: string additionalProperties: true additionalProperties: true ProblemDetails: type: object description: RFC 7807 Problem Details object. properties: type: type: string format: uri-reference title: type: string status: type: number detail: type: string instance: type: string format: uri-reference required: - type - title - status - detail additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: apiKey BasicAuth: type: http scheme: basic description: Use Basic auth with username `token` and password `x`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.