Redirecionamento após o pagamento

Configure uma URL de retorno para direcionar o cliente ao seu site após concluir o pagamento na interface do Asaas.

O recurso pode ser utilizado em cobranças, Links de Pagamento e assinaturas.

Quando utilizar

Utilize a URL de retorno quando:

• o pagamento for concluído em uma página hospedada pelo Asaas;
• o cliente precisar voltar ao seu site ou aplicativo;
• sua integração utilizar a Fatura ou um Link de Pagamento;
• você quiser direcionar o cliente para uma página de confirmação ou continuidade da jornada.

Antes de começar

Defina:

• a página para a qual o cliente será direcionado;
• se o retorno será automático;
• como sua aplicação confirmará o pagamento;
• quais Webhooks serão utilizados.

A URL deve pertencer ao mesmo domínio cadastrado nos dados comerciais da conta, disponível em:

Configurações da conta → Informações

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Criar cobrança, assinatura ou Link de Pagamento"] --> B["Informar o objeto callback"]
    B --> C["Direcionar o cliente para a página do Asaas"]
    C --> D["Cliente conclui o pagamento"]
    D --> E{"autoRedirect está habilitado?"}

    E --> ESim(("Sim"))
    E --> ENao(("Não"))

    ESim --> F["Redirecionar automaticamente para successUrl"]
    ENao --> G["Exibir o botão: Ir para o site"]

    F --> H["Cliente retorna ao seu site"]
    G --> H

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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

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

    class ESim respostaSim
    class ENao respostaNao

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

Escolha o tipo de retorno

Configure o comportamento no objeto callback:

O redirecionamento automático é aplicável às formas de pagamento com confirmação imediata, como Pix, cartão de crédito e cartão de débito pela Fatura.

1. Configure uma cobrança

Envie o objeto callback durante a criação da cobrança:

POST /v3/payments

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 2000.00,
  "dueDate": "2027-01-15",
  "callback": {
    "successUrl": "https://seusite.com/redirect",
    "autoRedirect": true
  }
}

Consulte o endpoint: Criar nova cobrança.

Resultado esperado

A API retornará o campo invoiceUrl.

Direcione o cliente para essa URL. Após a confirmação do pagamento, ele será encaminhado para o endereço informado em successUrl.

Caso autoRedirect seja false, o retorno dependerá do clique do cliente no botão Ir para o site.

Atualize uma cobrança

Para adicionar ou alterar o redirecionamento de uma cobrança existente, envie o objeto callback em:

PUT /v3/payments/{id}

Consulte o endpoint: Atualizar cobrança existente.

2. Configure um Link de Pagamento

Envie o mesmo objeto durante a criação do Link de Pagamento:

POST /v3/paymentLinks

{
  "name": "Meu Link de Pagamento",
  "billingType": "UNDEFINED",
  "value": 2000.00,
  "chargeType": "DETACHED",
  "callback": {
    "successUrl": "https://seusite.com/redirect",
    "autoRedirect": false
  }
}

Consulte o endpoint: Criar um Link de Pagamento.

Resultado esperado

A API retornará o campo url.

Direcione o cliente para esse endereço. Após o pagamento, ele será redirecionado automaticamente ou verá o botão de retorno, conforme a configuração escolhida.

Para alterar a configuração posteriormente, utilize:

PUT /v3/paymentLinks/{id}

Consulte o endpoint: Atualizar um Link de Pagamento.

Configure em assinaturas

O objeto callback também pode ser enviado durante a criação de uma assinatura.

Consulte o endpoint: Criar nova assinatura.

O retorno será aplicado às páginas de pagamento das cobranças geradas pela assinatura, conforme a forma de pagamento utilizada.

Acesso posterior à Fatura

Depois que o pagamento for concluído, um novo acesso à invoiceUrl normalmente exibirá apenas a Fatura paga, sem repetir o redirecionamento.

Para solicitar o redirecionamento ao acessar novamente a Fatura, adicione:

?autoRedirect=true

Exemplo:

https://www.asaas.com/i/IDENTIFICADOR?autoRedirect=true

Confirme o pagamento por Webhook

Consulte:

• Configure Webhooks
• Eventos de cobranças

Erros comuns

Caso o redirecionamento não funcione, verifique se:

• successUrl pertence ao domínio cadastrado na conta;
• o objeto callback foi enviado corretamente;
• autoRedirect possui um valor booleano;
• a forma de pagamento permite confirmação imediata;
• o pagamento foi efetivamente confirmado;
• a cobrança ou o Link de Pagamento foi atualizado com sucesso.

Próximos passos

• Crie uma nova cobrança
• Crie um Link de Pagamento
• Crie uma assinatura
• Configure Webhooks