Implemente o Pix Automático

Crie a autorização do Pix Automático, acompanhe sua ativação e configure como as cobranças dos próximos ciclos serão geradas.

Antes de começar

Antes de implementar:

• confirme que a conta está elegível para utilizar Pix Automático;
• cadastre o cliente e armazene seu ID;
• configure os Webhooks que acompanharão a autorização e as cobranças.

Para entender a jornada antes de implementar, consulte Pix Automático.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Definir paymentCreationMode"] --> B["Criar autorização"]
    B --> C["Apresentar o QR Code"]
    C --> D["Pagador realiza o primeiro pagamento"]
    D --> E["Aguardar autorização ACTIVE"]
    E --> F{"Como as cobranças serão criadas?"}

    F --> FManual(("MANUAL"))
    F --> FAutomatico(("SUBSCRIPTION"))

    FManual --> G["Aplicação cria cada cobrança"]
    FAutomatico --> H["Assinatura gera as cobranças"]

    G --> I["Acompanhar os eventos por Webhook"]
    H --> I

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    classDef respostaManual fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaAutomatico fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class F decisao
    class B,C,D,E,G,H validacao
    class I sucesso

    class FManual respostaManual
    class FAutomatico respostaAutomatico

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#8B5CF6,stroke-width:4px
    linkStyle 6 stroke:#22C55E,stroke-width:4px

1. Escolha o modo de criação das cobranças

Defina paymentCreationMode durante a criação da autorização.

MANUAL é o valor padrão.

Para utilizar SUBSCRIPTION, informe também value na autorização.

Exemplo de configuração manual:

{
  "paymentCreationMode": "MANUAL"
}

Exemplo de configuração automática:

{
  "paymentCreationMode": "SUBSCRIPTION",
  "value": 100.00
}

2. Crie a autorização

Inicie o fluxo criando uma autorização com QR Code imediato:

POST /v3/pix/automatic/authorizations

O objeto immediateQrCode representa o primeiro pagamento e será utilizado para registrar o consentimento do pagador.

Consulte o endpoint Criar uma autorização.

Resultado esperado

A resposta disponibiliza o QR Code do primeiro pagamento e o id da autorização.

Armazene o id. Ele será utilizado para:

• consultar o status da autorização;
• correlacionar eventos;
• criar cobranças no modo MANUAL.

3. Aguarde a ativação

Apresente o QR Code ao pagador e aguarde a conclusão do primeiro pagamento.

Após a confirmação do pagamento e a conclusão da autorização, o status passa para ACTIVE.

Acompanhe essa mudança por Webhook.

Consulte os Fluxos de Webhook do Pix Automático.

4. Processe as cobranças recorrentes

O comportamento depende do paymentCreationMode escolhido.

MANUAL

Com a autorização em ACTIVE, sua aplicação deve criar cada cobrança do ciclo:

POST /v3/payments

Informe o ID da autorização em pixAutomaticAuthorizationId:

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 100.00,
  "dueDate": "AAAA-MM-DD",
  "pixAutomaticAuthorizationId": "ID_DA_AUTORIZACAO"
}

Consulte o endpoint Criar nova cobrança.

SUBSCRIPTION

Nesse modo, o Asaas utiliza uma assinatura para gerar automaticamente as cobranças vinculadas à autorização.

Não crie manualmente uma nova cobrança para cada ciclo.

O campo value é obrigatório na autorização quando paymentCreationMode for SUBSCRIPTION.

Consulte os campos e regras disponíveis em Criar uma autorização.

5. Acompanhe o processamento

Independentemente do modo escolhido, acompanhe por Webhook:

• o status da autorização;
• a criação e o processamento das instruções;
• a confirmação das cobranças;
• recusas e cancelamentos.

Consulte Fluxos de Webhook do Pix Automático.

Para recusas, consulte Motivos de Recusa.

Próximos passos

• Acompanhe os Fluxos de Webhook
• Conheça os Motivos de Recusa
• Implemente o processo de retentativas
• Compare Pix Automático e Assinaturas
• Consulte o FAQ do Pix Automático