Implementação

Um guia de implementação para auxiliar na integração com a API de autorizações na jornada 3.

A implementação do Pix Automático é composta por duas etapas principais:

criar a autorização da recorrência;
criar as cobranças recorrentes vinculadas à autorização.

A autorização representa o consentimento concedido pelo pagador para que futuras cobranças possam ser realizadas automaticamente via Pix.

Somente após essa autorização estar ativa é que novas cobranças poderão ser vinculadas a ela.

Fluxo completo da implementação

Uma integração típica segue a seguinte jornada:

Criar autorização
        ↓
Gerar QR Code
        ↓
Pagador realiza o primeiro pagamento
        ↓
Autorização passa para ACTIVE
        ↓
Criar cobranças recorrentes
        ↓
Receber Webhooks
        ↓
Acompanhar pagamentos

Cada etapa possui uma finalidade específica e depende da conclusão da etapa anterior.

1. Criar uma autorização com QR Code imediato

A criação da autorização é o primeiro passo da integração.

Nesse momento, sua aplicação solicita ao Asaas a criação de uma autorização contendo um QR Code responsável tanto pelo primeiro pagamento quanto pelo consentimento da recorrência.

Veja a referência completa do endpoint:

Criar autorização com QR Code imediato

Ao consumir esse endpoint serão retornados, entre outras informações:

o QR Code para pagamento imediato;
o código copia e cola (payload);
o identificador da autorização (id);
o conciliationIdentifier da cobrança inicial.

Campos importantes

Durante esse fluxo, alguns campos possuem papel fundamental:

Campo	Finalidade
`payload`	Código Pix utilizado pelo pagador para realizar o primeiro pagamento.
`id`	Identificador único da autorização. Será utilizado nas cobranças recorrentes futuras.
`conciliationIdentifier`	Permite relacionar a autorização com a cobrança gerada pelo primeiro pagamento.

📘
Importante
Armazene o id da autorização em sua aplicação.
Esse identificador será obrigatório para criar as cobranças recorrentes posteriormente.

Quando a autorização passa para ACTIVE?

Após a criação da autorização, ela ainda não está apta para receber cobranças recorrentes.

A autorização somente passa para o status ACTIVE quando:

o pagador realiza o pagamento utilizando o QR Code gerado;
o primeiro Pix é liquidado com sucesso;
o processo de autorização é concluído.

Somente após esse momento sua aplicação deve iniciar a criação das cobranças recorrentes.

Caso o pagamento inicial não seja concluído ou a autorização seja recusada, novas cobranças não poderão ser vinculadas a essa autorização.

Webhooks

Durante todo o ciclo de vida da autorização, o Asaas envia Webhooks para informar alterações de status e demais eventos relacionados ao Pix Automático.

❗️
Importante
Recomenda-se utilizar os Webhooks para acompanhar o status da autorização.
Evite depender exclusivamente de consultas periódicas na API para identificar quando a autorização passou para ACTIVE.
Consulte os eventos disponíveis em:
Fluxos de Webhook do Pix Automático

2. Criar as cobranças recorrentes

Com a autorização em status ACTIVE, sua aplicação já pode criar as cobranças recorrentes.

Para isso, utilize a API de criação de cobranças informando o campo:

pixAutomaticAuthorizationId

com o identificador da autorização obtido na etapa anterior.

Veja a referência completa do endpoint:

Criar cobrança com Pix Automático

Campo importante

Campo	Finalidade
`pixAutomaticAuthorizationId`	Relaciona a cobrança à autorização previamente concedida pelo pagador.

Sem esse identificador, a cobrança será criada como uma cobrança Pix convencional.

Intervalo para criação da cobrança

📘
Importante
A instrução de pagamento deve ser criada entre 2 e 10 dias úteis antes do vencimento.
Caso a cobrança seja criada fora dessa janela, a API retornará uma exceção.

Comportamentos importantes

Durante a implementação, considere que:

uma autorização somente pode receber cobranças após atingir o status ACTIVE;
cada cobrança deve referenciar uma autorização existente;
o pagamento inicial não cria automaticamente as cobranças futuras;
as cobranças recorrentes precisam ser criadas pela integração conforme a periodicidade desejada;
recusas, cancelamentos ou revogações da autorização impedem novas cobranças automáticas.

Possíveis dificuldades

Os problemas mais comuns durante a implementação são:

Tentar criar cobranças antes da autorização estar ativa

A autorização somente poderá receber cobranças após o primeiro pagamento ser liquidado.

Não armazenar o identificador da autorização

O id retornado na criação da autorização será utilizado durante toda a vida útil da recorrência.

Criar cobranças fora da janela permitida

A criação da instrução deve respeitar o intervalo de 2 a 10 dias úteis antes do vencimento.

Não acompanhar os Webhooks

Utilizar apenas consultas periódicas pode atrasar a atualização do status da autorização na aplicação.

Próximos passos

Após implementar o fluxo, recomendamos consultar:

Fluxos de Webhook do Pix Automático.
Motivos de Recusa.
FAQ do Pix Automático.
Quando utilizar Pix Automático ou Assinaturas.