Endpoint utilizado para consultar os detalhes de uma instrução de pagamento específica de Pix Automático.

A instrução representa o processo de execução de um pagamento automático relacionado a uma cobrança recorrente. Por meio desta consulta, a integração pode acompanhar o status atual da instrução, identificar a autorização vinculada, localizar a cobrança relacionada e verificar se houve recusa no processamento.

Quando utilizar

Utilize este endpoint quando sua integração precisar consultar uma instrução de pagamento específica de Pix Automático.

Alguns cenários comuns incluem:

• acompanhar o processamento de uma cobrança automática;
• validar se uma instrução foi agendada, concluída, cancelada ou recusada;
• investigar falhas de pagamento automático;
• consultar o motivo de recusa de uma instrução;
• relacionar uma instrução à autorização de Pix Automático correspondente;
• relacionar uma instrução à cobrança vinculada;
• atualizar o status interno de uma cobrança recorrente no sistema de origem;
• complementar o tratamento de eventos recebidos por Webhook.

Quando não utilizar

Não utilize este endpoint para:

• criar uma nova instrução de pagamento;
• criar uma autorização de Pix Automático;
• cancelar uma autorização;
• criar uma cobrança recorrente;
• alterar uma cobrança vinculada;
• tentar executar novamente uma instrução recusada;
• substituir o uso de Webhooks em fluxos assíncronos.

Caso precise criar uma cobrança recorrente com Pix Automático, utilize o endpoint de criação de cobrança informando a autorização correspondente.

Permissão necessária

Para utilizar este endpoint, a chave de API deve possuir permissão de leitura para Pix Automático:

PIX_AUTOMATIC:READ

Caso a chave utilizada não possua permissão para essa operação, a requisição poderá retornar erro de autorização.

Parâmetro da requisição

Este endpoint utiliza apenas o identificador da instrução de pagamento no path da requisição.

Exemplo de identificador:

cbfdf6ef-9bd8-48ba-b8cd-efd61a9f614c

O id deve corresponder a uma instrução de pagamento existente na conta Asaas autenticada.

Este endpoint não exige envio de parâmetros no corpo da requisição.

Dependências da instrução de pagamento

Uma instrução de pagamento de Pix Automático está relacionada a outros recursos do fluxo recorrente.

Antes de utilizar esta consulta, considere que:

• deve existir uma autorização de Pix Automático vinculada à instrução;
• a autorização precisa estar relacionada ao pagador que concedeu o consentimento;
• a cobrança recorrente precisa ter sido criada com vínculo à autorização;
• a instrução é enviada para processamento conforme a cobrança vinculada;
• o campo paymentId permite relacionar a instrução à cobrança correspondente;
• o campo authorization.id permite relacionar a instrução à autorização correspondente.

Fluxo recomendado

Em uma integração típica, a consulta de uma instrução de pagamento faz parte do seguinte fluxo:

Criar autorização de Pix Automático
↓
Cliente realiza o pagamento inicial e autoriza a recorrência
↓
Autorização fica ACTIVE
↓
Integração cria uma cobrança recorrente vinculada à autorização
↓
Asaas gera a instrução de pagamento
↓
Banco pagador processa a instrução
↓
Integração acompanha eventos por Webhook
↓
Integração consulta a instrução específica, quando necessário

Exemplo de chamada

curl --request GET \
  --url https://api-sandbox.asaas.com/v3/pix/automatic/paymentInstructions/cbfdf6ef-9bd8-48ba-b8cd-efd61a9f614c \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Exemplo de resposta

Em caso de sucesso, a API retorna os detalhes da instrução de pagamento.

{
  "id": "d1c9c4b2-6a97-4573-9d6d-26bb64f04c28",
  "endToEndIdentifier": "E00416968202111161635q5bk0brYk2C",
  "authorization": {
    "id": "35363f6e-93e2-11ec-b9d9-96f4053b1bd4",
    "endToEndIdentifier": "RR1234567820240115abcdefghijk",
    "customerId": "cus_000005735721"
  },
  "dueDate": "2020-01-31",
  "status": "SCHEDULED",
  "paymentId": "pay_tsp88gie3b5e6o2p",
  "refusalReason": null
}

Informações retornadas

Ao recuperar uma instrução de pagamento, é possível verificar informações como:

Status da instrução de pagamento

O campo status indica o estado atual da instrução de pagamento.

Os principais status retornados são:

Como interpretar os status

A interpretação do status deve orientar a próxima ação da integração.

Motivos de recusa

Quando a instrução retornar status REFUSED, o campo refusalReason pode indicar o motivo da recusa.

Alguns exemplos de motivos de recusa incluem:

Comportamentos importantes

Ao utilizar este endpoint, considere os seguintes comportamentos:

• a consulta retorna apenas os dados de uma instrução específica;
• o endpoint não altera o estado da instrução;
• o endpoint não cria novas cobranças;
• o endpoint não reprocessa instruções recusadas;
• o endpoint não substitui o acompanhamento por Webhooks;
• o campo paymentId deve ser usado para consultar a cobrança vinculada;
• o campo authorization.id deve ser usado para consultar a autorização vinculada;
• uma instrução recusada deve ser tratada conforme o motivo retornado em refusalReason;
• se houver dúvida sobre o estado da cobrança, consulte também o pagamento vinculado pelo paymentId.

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• a instrução de pagamento deve existir no Asaas;
• o id informado deve pertencer à conta autenticada;
• a requisição deve ser autenticada com uma API Key válida;
• a API Key deve possuir permissão PIX_AUTOMATIC:READ;
• a instrução deve estar vinculada a uma autorização de Pix Automático;
• a instrução deve estar vinculada a uma cobrança recorrente;
• a autorização vinculada deve ser acompanhada durante todo o ciclo de vida;
• cobranças recorrentes de Pix Automático devem ser criadas pela integração;
• a instrução de pagamento deve respeitar a janela operacional de criação definida para o Pix Automático;
• alterações de status devem ser acompanhadas preferencialmente por Webhooks.

Impactos operacionais

A consulta de uma instrução de pagamento pode impactar diretamente a forma como sua integração atualiza cobranças recorrentes.

Alguns impactos importantes:

• uma instrução DONE pode indicar que o fluxo de pagamento automático avançou com sucesso;
• uma instrução REFUSED pode exigir comunicação ao cliente, nova tentativa ou encerramento do ciclo, conforme o motivo da recusa;
• uma instrução CANCELLED pode indicar que aquele ciclo não deve mais ser cobrado automaticamente;
• uma instrução SCHEDULED ainda não deve ser tratada como pagamento concluído;
• inconsistências entre status, paymentId e registros internos podem gerar divergências de conciliação;
• depender apenas de consultas periódicas pode atrasar a atualização do status da aplicação.

Por isso, combine Webhooks com consultas pontuais para manter a integração sincronizada.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Boas práticas

Para uma implementação mais segura, recomenda-se:

• armazenar o id da instrução de pagamento quando ele for retornado pela API ou por Webhook;
• armazenar também o authorization.id e o paymentId;
• utilizar Webhooks para acompanhar mudanças de status;
• consultar este endpoint quando precisar confirmar o estado atual de uma instrução específica;
• tratar REFUSED com base no campo refusalReason;
• não considerar SCHEDULED como pagamento concluído;
• não reprocessar automaticamente instruções recusadas sem avaliar o motivo;
• consultar a cobrança vinculada pelo paymentId quando houver divergência;
• consultar a autorização vinculada quando houver suspeita de cancelamento, expiração ou mudança de status;
• responder Webhooks de forma idempotente e evitar duplicidade no sistema de origem;
• testar cenários de sucesso, cancelamento e recusa em Sandbox antes de operar em Produção.

Cuidados em Sandbox

Este endpoint pode ser utilizado em Sandbox para validar o acompanhamento de instruções de pagamento de Pix Automático.

Durante os testes, recomenda-se validar:

• consulta de uma instrução existente;
• consulta com id inválido;
• consulta sem permissão adequada;
• chamada GET com body vazio;
• correlação entre authorization.id, paymentId e registros internos;
• tratamento de status SCHEDULED, DONE, CANCELLED e REFUSED;
• tratamento de refusalReason quando houver recusa;
• atualização do sistema de origem após eventos de Webhook.

Esses testes ajudam a garantir que sua integração acompanhe corretamente o ciclo de vida das cobranças recorrentes via Pix Automático.

Conteúdos relacionados

Consulte também:

• Pix Automático;
• Implementação do Pix Automático;
• Criar autorização de Pix Automático;
• Listar autorizações;
• Recuperar uma única autorização;
• Criar cobrança com Pix Automático;
• Listar instruções de pagamento;
• Motivos de recusa;
• Fluxos de Webhook do Pix Automático;
• FAQ do Pix Automático.