> ## 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. # Assinaturas com Pix Automático > Cobre um cliente de forma recorrente com Pix Automático: o pagador autoriza uma vez pelo QR code e o banco dele debita cada ciclo. No Pix Automático, o pagador autoriza o débito recorrente uma vez, no app do banco, lendo um QR code. A partir daí, o banco do pagador debita cada ciclo e a Pagou informa o resultado pelos webhooks de assinatura. ## Como funciona 1. Crie o cliente com `POST /v2/customers`, informando CPF ou CNPJ. 2. Crie a assinatura com `payment_method: "pix_automatic"`. Não há token de cartão. 3. Mostre `authorization.qr_code` ao pagador. 4. O pagador autoriza o débito recorrente no app do banco. 5. O banco do pagador debita cada ciclo. Acompanhe autorização, pagamentos, falhas e cancelamento pelos webhooks de assinatura. O que muda em relação à assinatura com cartão: | | Cartão | Pix Automático | | ----------------------------- | -------------------------------------------------------------------- | --------------------------------------- | | Status logo depois da criação | `active` ou `trialing` | `incomplete`, até o pagador autorizar | | Quem inicia cada cobrança | a Pagou | o banco do pagador | | Cancelamento | no fim do período (`cancel_scheduled`), emite `subscription.updated` | imediato, emite `subscription.canceled` | | Troca de plano | disponível | indisponível | ## Pré-requisitos * Assinaturas precisam estar habilitadas na sua conta (`403` se não estiverem), e o Pix Automático também (`422` se não estiver). Veja **Erros**. * O cliente precisa existir em `/v2/customers` com CPF ou CNPJ em `document`. Endereço e telefone são opcionais. * `currency` precisa ser `BRL`. ## Criar assinatura sem período de teste Sem `trial_end`, o mesmo QR code autoriza o débito recorrente **e** paga o primeiro ciclo. ```bash theme={null} curl --request POST \ --url https://api.pagou.ai/v2/subscriptions \ --header "Authorization: Bearer SEU_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "customer_id": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101", "payment_method": "pix_automatic", "amount": 4900, "currency": "BRL", "interval": "month", "interval_count": 1, "billing_day_of_month": 10, "comment": "Plano Pro", "failure_policy": "retry_then_cancel", "metadata": { "plan": "pro" } }' ``` Resposta `201`: ```json theme={null} { "success": true, "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201", "data": { "id": "019e5d23-6ec8-73de-9c95-06093c62ba00", "customerId": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101", "status": "incomplete", "paymentMethod": "pix_automatic", "billingModel": "provider_initiated", "billingDayOfMonth": 10, "interval": "month", "intervalCount": 1, "amount": 4900, "currency": "BRL", "trialEnd": null, "currentPeriodStart": "2026-09-23T14:00:00.000Z", "currentPeriodEnd": "2026-10-23T14:00:00.000Z", "cancelAtPeriodEnd": false, "canceledAt": null, "failurePolicy": "retry_then_cancel", "retryOffsetsDays": [1, 2, 3, 4, 5], "cancellationReason": null, "customerEmail": "buyer@example.com", "cardLast4": null, "metadata": { "plan": "pro" }, "informations": null, "products": [], "authorization": { "type": "pix_qr", "qr_code": "00020101021226870014br.gov.bcb.pix2565qr.example.com/rec/019e5d236ec85204000053039865802BR6304A1B2", "expires_at": "2026-09-24T14:00:00.000Z", "status": "awaiting_customer" }, "recurringAuthorization": { "status": "pending" }, "createdAt": "2026-09-23T14:00:00.000Z", "updatedAt": "2026-09-23T14:00:00.000Z" } } ``` A assinatura fica `incomplete` até o pagador autorizar **e** o primeiro débito ser pago. Nesse momento ela passa para `active` e você recebe `subscription.started` com `previous_status: "incomplete"`. Este fluxo **não** envia `subscription.created`. ## Criar assinatura com período de teste Envie `trial_end` (ISO 8601, no futuro) e o QR code só autoriza o débito recorrente. Nada é cobrado antes do fim do teste. O período de teste depende da configuração da sua conta. Quando não está disponível, a requisição retorna `422` com `PIX_AUTOMATIC_TRIAL_NOT_SUPPORTED` e nada é criado. Onde o período de teste está disponível, envie também `billing_day_of_month`. O primeiro débito é agendado para a primeira ocorrência desse dia a partir da data do cadastro, e essa data precisa cair em `trial_end` ou depois e pelo menos 3 dias completos (72 horas) depois do momento do cadastro. Sem `billing_day_of_month`, o dia de cobrança é o dia do cadastro, então o primeiro débito cairia antes do fim do teste e a requisição é recusada. Quando as datas não se encaixam, a requisição retorna `422` com `PIX_AUTHORIZATION_FAILED` e um `detail` explicando o motivo. Neste exemplo a assinatura é criada em 23 de setembro, com `trial_end` em 7 de outubro e `billing_day_of_month: 10`, então o primeiro débito fica agendado para 10 de outubro: ```bash theme={null} curl --request POST \ --url https://api.pagou.ai/v2/subscriptions \ --header "Authorization: Bearer SEU_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "customer_id": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101", "payment_method": "pix_automatic", "amount": 4900, "currency": "BRL", "interval": "month", "interval_count": 1, "billing_day_of_month": 10, "trial_end": "2026-10-07T00:00:00.000Z" }' ``` Resposta `201`: ```json theme={null} { "success": true, "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261202", "data": { "id": "019e5d23-7a10-7c4e-8f21-3b5d8e0a1c02", "customerId": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101", "status": "incomplete", "paymentMethod": "pix_automatic", "billingModel": "provider_initiated", "billingDayOfMonth": 10, "interval": "month", "intervalCount": 1, "amount": 4900, "currency": "BRL", "trialEnd": "2026-10-07T00:00:00.000Z", "currentPeriodStart": "2026-09-23T14:00:00.000Z", "currentPeriodEnd": "2026-10-07T00:00:00.000Z", "cancelAtPeriodEnd": false, "canceledAt": null, "failurePolicy": "retry_then_cancel", "retryOffsetsDays": [1, 2, 3, 4, 5], "cancellationReason": null, "customerEmail": "buyer@example.com", "cardLast4": null, "metadata": null, "informations": null, "products": [], "authorization": { "type": "pix_qr", "qr_code": "00020101021226870014br.gov.bcb.pix2565qr.example.com/rec/019e5d237a107c4e5204000053039865802BR6304C3D4", "expires_at": null, "status": "awaiting_customer" }, "recurringAuthorization": { "status": "pending" }, "createdAt": "2026-09-23T14:00:00.000Z", "updatedAt": "2026-09-23T14:00:00.000Z" } } ``` Quando o pagador aprova a autorização, a assinatura passa para `trialing` e você recebe `subscription.created` (com `latest_transaction: null`). Três dias antes de `trial_end` você recebe `subscription.trial_will_end`, se a assinatura já estiver `trialing` nesse momento. O primeiro débito depois do teste leva a assinatura para `active` e envia `subscription.started`. ## Campos da requisição | Campo | Obrigatório | Observações | | --------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | sim | id público do cliente. O cliente precisa ter CPF ou CNPJ. | | `payment_method` | sim | `"pix_automatic"`. Não envie `token`: a requisição é recusada. | | `amount` | sim | centavos, cobrados em cada ciclo. Algumas contas exigem no mínimo `100` (R\$ 1,00). | | `interval` / `interval_count` | sim / não | veja **Intervalos de cobrança**. `interval_count` tem padrão `1`. | | `billing_day_of_month` | não | de `1` a `31`. Valores acima de `27` são tratados como `27`. Sem período de teste, é uma preferência, não uma data de débito garantida. Com período de teste, envie: ele agenda o primeiro débito (veja **Criar assinatura com período de teste**). | | `comment` | não | até 140 caracteres. Pode ser exibido ao pagador, dependendo da configuração da sua conta. | | `trial_end` | não | veja **Criar assinatura com período de teste**. | | `failure_policy` | não | `retry_then_cancel` (padrão) ou `immediate_cancel`. Veja **Débitos com falha**. | | `metadata`, `informations`, `idempotency_key` | não | mesmo comportamento da assinatura com cartão. | ### Intervalos de cobrança | `interval` | `interval_count` | Disponibilidade | | ---------- | ---------------- | ------------------------------------ | | `week` | `1` | disponível | | `month` | `1`, `6`, `12` | disponível | | `month` | `3` | depende da configuração da sua conta | | `day` | qualquer | nunca disponível | Qualquer outra combinação, ou uma que a sua conta não suporte, retorna `422` com `PIX_AUTHORIZATION_FAILED` e um `detail` dizendo que o intervalo não é suportado. ## Exibir o QR code O bloco `authorization` traz o que o pagador precisa: | Campo | Significado | | ------------------ | -------------------------------------------------------------------------------- | | `type` | sempre `pix_qr` | | `qr_code` | código Pix copia e cola. Renderize como QR code ou ofereça para copiar. | | `payment_link_url` | página hospedada onde o pagador pode autorizar, quando disponível. Pode não vir. | | `expires_at` | quando o código expira, quando conhecido. Pode ser `null`. | | `status` | `awaiting_customer` | `GET /v2/subscriptions/{id}` só devolve `authorization` enquanto a autorização está pendente. Depois que o pagador aprova ou recusa, o bloco some. Se o pagador nunca autorizar, o resultado depende da configuração da sua conta: a assinatura fica `incomplete`, ou é cancelada quando o código expira e você recebe `subscription.canceled`. Para parar de esperar, cancele você mesmo (veja **Cancelamento**). `recurringAuthorization.status` diz em que ponto a autorização está: `pending`, `approved`, `rejected`, `cancel_pending` ou `canceled`. No `GET` por id, `recurringAuthorization.lastDebit` mostra a tentativa de débito mais recente. ## O que armazenar * `id` da assinatura * `id` do cliente * `status` atual * `authorization.qr_code`, enquanto a autorização está pendente * `recurringAuthorization.status` * `latest_transaction.id` dos webhooks, quando existir ## Status e webhooks | Momento | Status | Webhook (`data.event_type`) | | ------------------------------------------------------------------------------------------ | -------------------------- | --------------------------------------------- | | assinatura criada, sem teste | `incomplete` | nenhum | | pagador autorizou e o primeiro débito foi pago, sem teste | `active` | `subscription.started` | | assinatura criada, com teste | `incomplete` | nenhum | | pagador autorizou, com teste | `trialing` | `subscription.created` | | 3 dias antes de `trial_end`, se já estiver `trialing` | `trialing` | `subscription.trial_will_end` | | primeiro débito pago depois do teste | `active` | `subscription.started` | | pagador recusou a autorização, ou deixou expirar (dependendo da configuração da sua conta) | `canceled` | `subscription.canceled`, com `failure_reason` | | um ciclo seguinte foi pago | `active` | `subscription.renewed` | | um débito falhou | veja **Débitos com falha** | `subscription.payment_failed` | | assinatura cancelada | `canceled` | `subscription.canceled` | Ao tratar esses eventos: * As cobranças do Pix Automático são informadas **só** por eventos `subscription.*`. Você não recebe webhooks `transaction.*` para elas. * `latest_transaction.method` é `"pix"`. O payload não diz qual meio de pagamento a assinatura usa, então identifique as assinaturas de Pix Automático pelo `id` que você guardou, ou leia `paymentMethod` com `GET /v2/subscriptions/{id}`. * `failure_reason` é informativo. Não crie lógica sobre valores específicos. ## Débitos com falha O banco do pagador pode tentar um débito mais de uma vez. Essas tentativas intermediárias não geram eventos. Quando não restam tentativas, você recebe `subscription.payment_failed` com `attempt_number` e `failure_reason`. * Se foi o primeiro débito de uma assinatura **sem** período de teste, a assinatura continua `incomplete`. * Nos outros casos (o primeiro débito depois do teste, ou um ciclo seguinte), com `failure_policy: retry_then_cancel` a assinatura passa para `past_due` e você recebe `subscription.past_due`. Num ciclo seguinte, um débito pago depois a devolve para `active` e envia `subscription.renewed`. * Um débito com falha não cria transação nova. Em `subscription.payment_failed` e `subscription.past_due`, `latest_transaction` é a transação mais recente da assinatura, normalmente a do ciclo pago anterior. * `retry_offsets_days` é aceito, mas não tem efeito: o intervalo entre tentativas segue as regras do Pix Automático e não é configurável. * Qualquer outro efeito de `failure_policy` no Pix Automático depende da configuração da sua conta. `subscription.canceled` é a única confirmação de que a assinatura terminou. ## Cancelamento `POST /v2/subscriptions/{id}/cancel` funciona enquanto a assinatura está `incomplete`, `trialing`, `active` ou `past_due`. No Pix Automático o cancelamento é **imediato**: nunca fica para o fim do período, o status nunca passa por `cancel_scheduled` e o webhook é `subscription.canceled`, não `subscription.updated`. A resposta vem em uma de duas formas, dependendo da configuração da sua conta: * **Já cancelada:** `status` é `canceled` e `recurringAuthorization.status` é `canceled`. * **Aguardando confirmação:** `status` mantém o valor atual e `recurringAuthorization.status` é `cancel_pending`. A assinatura passa para `canceled` quando o cancelamento é confirmado, e aí você recebe `subscription.canceled`. Nos dois casos, trate `subscription.canceled` como a fonte da verdade. Repetir a chamada numa assinatura `canceled`, ou com cancelamento aguardando confirmação, retorna `200` sem mudança. Duas chamadas simultâneas na mesma assinatura podem retornar `409` com `SUBSCRIPTION_CANCEL_IN_PROGRESS`; tente de novo depois de alguns instantes. ## Limitações * **Troca de plano indisponível.** `PATCH /v2/subscriptions/{id}` com `product_id` retorna `422` e o plano não muda: `PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD` quando a assinatura está vinculada a um plano do catálogo, ou `SUBSCRIPTION_HAS_NO_CATALOG_PLAN` / `PRODUCT_NOT_FOUND` quando não está. Para levar o pagador a outro plano, cancele a assinatura e crie uma nova, que exige nova autorização. * **Intervalos de cobrança** limitados à tabela em **Campos da requisição**. * **Período de teste** depende da configuração da sua conta. * **Espaçamento das retentativas** não é configurável: `retry_offsets_days` é ignorado. * **A data do débito não é garantida.** Acompanhe os webhooks em vez de esperar cobrança num dia fixo. ## Erros | Situação | HTTP | `code` | | ----------------------------------------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Assinaturas não estão habilitadas na sua conta | `403` | `FORBIDDEN` | | Pix Automático não está habilitado na sua conta | `422` | `UNSUPPORTED_PAYMENT_METHOD`, `PIX_AUTOMATIC_ACCOUNT_NOT_ELIGIBLE` ou `PIX_AUTOMATIC_SUBACCOUNT_REQUIRED` | | Pix Automático não está configurado na sua conta | `400` | `BAD_REQUEST` | | O cliente não tem CPF nem CNPJ | `400` | `BAD_REQUEST` | | `customer_id` desconhecido | `404` | `NOT_FOUND` | | `trial_end` indisponível na sua conta | `422` | `PIX_AUTOMATIC_TRIAL_NOT_SUPPORTED` | | Intervalo não suportado, valor abaixo do mínimo da sua conta, ou datas do teste que não se encaixam em `billing_day_of_month` | `422` | `PIX_AUTHORIZATION_FAILED` | | A autorização não pôde ser gerada. A assinatura é criada como `canceled`. | `422` | `PIX_AUTHORIZATION_FAILED` | | Troca de plano solicitada | `422` | `PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD`, ou `SUBSCRIPTION_HAS_NO_CATALOG_PLAN` / `PRODUCT_NOT_FOUND` quando a assinatura não está vinculada a um plano do catálogo | | Cancelamento já em andamento na mesma assinatura | `409` | `SUBSCRIPTION_CANCEL_IN_PROGRESS` | Quando o Pix Automático não está habilitado ou configurado, fale com o suporte para habilitá-lo na sua conta. ## Sandbox No sandbox (`https://api.sandbox.pagou.ai`) não existe banco do pagador do outro lado: ninguém escaneia o QR code e nada é debitado sozinho. Você faz o papel do banco do pagador com `POST /v2/subscriptions/{id}/simulate`. A assinatura muda exatamente como mudaria em produção, e você recebe os mesmos webhooks. Crie o cliente e a assinatura como descrito acima, com o seu token de sandbox. Depois envie um evento por chamada: ```bash theme={null} curl --request POST \ --url https://api.sandbox.pagou.ai/v2/subscriptions/019e5d23-6ec8-73de-9c95-06093c62ba00/simulate \ --header "Authorization: Bearer SEU_TOKEN_SANDBOX" \ --header "Content-Type: application/json" \ --data '{ "event": "authorize" }' ``` A resposta é `200` com a assinatura atualizada, no mesmo formato de `GET /v2/subscriptions/{id}`. | `event` | Aceito enquanto `recurringAuthorization.status` é | Sem período de teste | Com período de teste | | ----------- | ------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `authorize` | `pending` | o pagador autoriza e o 1º ciclo é pago: `active`, `subscription.started` | o pagador autoriza: `trialing`, `subscription.created` | | `reject` | `pending` | o pagador recusa: `canceled`, `subscription.canceled` com `failure_reason` | igual | | `pay` | `approved` | o próximo ciclo é pago: `subscription.renewed` | o 1º débito é pago: `active`, `subscription.started`; depois, `subscription.renewed` | | `fail` | `approved` | o débito falha: `subscription.payment_failed`, e em seguida veja abaixo | igual | Depois de `fail`, com `failure_policy: retry_then_cancel` a assinatura passa a `past_due` e você recebe `subscription.past_due`; num ciclo seguinte, um `pay` a deixa `active` de novo com `subscription.renewed`. Com `immediate_cancel` ela passa a `canceled` e você recebe `subscription.canceled`. Com trial, um `fail` antes de o primeiro débito ser pago deixa a assinatura `past_due` e nenhum `pay` a recupera: cancele e crie outra para continuar testando. O que saber sobre o sandbox: * Uma chamada é um evento. Cada `pay` paga um ciclo na hora, qualquer que seja o intervalo de cobrança. * A assinatura só muda quando você chama o endpoint. Não conte com eventos disparados por tempo, como `subscription.trial_will_end`, no sandbox. * Um evento que não cabe na autorização ou no status atual responde `409` com `SUBSCRIPTION_SIMULATION_NOT_APPLICABLE` e não muda nada: por exemplo, `pay` antes de `authorize`, ou `authorize` duas vezes. * `authorization.qr_code` tem o formato do Pix, mas não cria uma autorização recorrente de verdade: não escaneie esse código com um app de banco, use `authorize`. `expires_at` é `null` e a autorização nunca expira sozinha: use `reject` para simular uma autorização recusada. * O sandbox aceita `trial_end` sem conferir as datas com `billing_day_of_month`, e o 1º débito acontece quando você envia `pay`. Em produção, o período de teste depende da configuração da sua conta e as datas precisam se encaixar (veja **Criar assinatura com período de teste**). * Os intervalos de cobrança são `week` × `1` e `month` × `1`, `6` ou `12`. `month` × `3` é recusado, assim como um valor abaixo de `100`. * O cancelamento responde já `canceled`. * Não use `PUT /v2/transactions/{id}` numa cobrança do Pix Automático: ele muda a transação, mas não a assinatura. * Os valores de Pix da página [Dados de teste](/pt/start-here/test-data) (documentos e o valor `7300`) não valem para o Pix Automático. * A rota só existe no sandbox. Em produção ela responde `404`. ## Leia a seguir * [Visão geral de assinaturas](/pt/subscriptions/overview) * [Ciclo de vida da assinatura](/pt/subscriptions/lifecycle) * [Webhooks de assinatura](/pt/subscriptions/webhooks) * [API: Criar assinatura](/pt/api-reference/subscriptions/create) * [API: Cancelar assinatura](/pt/api-reference/subscriptions/cancel) * [API: Simular evento do Pix Automático](/pt/api-reference/subscriptions/simulate)