Assinaturas com Pix Automático

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

Crie o cliente com POST /v2/customers, informando CPF ou CNPJ.
Crie a assinatura com payment_method: "pix_automatic". Não há token de cartão.
Mostre authorization.qr_code ao pagador.
O pagador autoriza o débito recorrente no app do banco.
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.

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:

{
  "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:

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:

{
  "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:

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 (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.

Cobrança recorrente

Como funciona

Pré-requisitos

Criar assinatura sem período de teste

Criar assinatura com período de teste

Campos da requisição

Intervalos de cobrança

Exibir o QR code

O que armazenar

Status e webhooks

Débitos com falha

Cancelamento

Limitações

Erros

Sandbox

Leia a seguir

​Como funciona

​Pré-requisitos

​Criar assinatura sem período de teste

​Criar assinatura com período de teste

​Campos da requisição

​Intervalos de cobrança

​Exibir o QR code

​O que armazenar

​Status e webhooks

​Débitos com falha

​Cancelamento

​Limitações

​Erros

​Sandbox

​Leia a seguir

Como funciona

Pré-requisitos

Criar assinatura sem período de teste

Criar assinatura com período de teste

Campos da requisição

Intervalos de cobrança

Exibir o QR code

O que armazenar

Status e webhooks

Débitos com falha

Cancelamento

Limitações

Erros

Sandbox

Leia a seguir