Criando um link de pagamentos

Crie um Link de Pagamento

Crie um Link de Pagamento para disponibilizar uma página hospedada pelo Asaas e gerar cobranças a partir dos dados informados pelo pagador.

O mesmo link pode ser utilizado para cobranças avulsas, parceladas ou recorrentes.

Antes de começar

Defina:

o tipo de cobrança;
as formas de pagamento disponíveis;
o valor, quando for fixo;
as regras específicas de parcelamento ou recorrência;
se os clientes criados pelo link receberão notificações.

Não é necessário cadastrar o cliente antes de disponibilizar o link. O cadastro é criado quando o pagador conclui o preenchimento e a cobrança é gerada.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Definir o tipo de cobrança"] --> B["Criar o Link de Pagamento"]
    B --> C["Compartilhar o link"]
    C --> D["Pagador informa os dados"]
    D --> E["Asaas gera a cobrança"]
    E --> F["Receber os Webhooks"]
    F --> G["Conciliar o pagamento"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,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

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

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Escolha o tipo de cobrança

O campo chargeType define o comportamento do link:

`chargeType`	Comportamento	Configuração relacionada
`DETACHED`	Gera uma cobrança avulsa a cada preenchimento	—
`INSTALLMENT`	Permite pagamento parcelado	`maxInstallmentCount`
`RECURRENT`	Cria uma assinatura	`subscriptionCycle`

Se value não for informado, o pagador poderá definir o valor no momento do pagamento.

Consulte o endpoint Criar um link de pagamentos.

2. Crie o Link de Pagamento

Utilize:

POST /v3/paymentLinks

Cobrança avulsa

Use chargeType = DETACHED para gerar uma nova cobrança a cada preenchimento do link.

{
  "name": "Venda de livros",
  "description": "Qualquer livro por apenas R$: 50,00",
  "value": 50.00,
  "billingType": "UNDEFINED",
  "chargeType": "DETACHED",
  "dueDateLimitDays": 10
}

Com billingType = UNDEFINED, o pagador poderá escolher entre as formas de pagamento disponíveis.

Sempre que o link permitir pagamento via boleto, informe dueDateLimitDays. Esse campo define quantos dias úteis o boleto poderá ser pago após sua geração.

O link permanece ativo para novos pagamentos até ser desabilitado ou removido.

Cobrança parcelada

Use chargeType = INSTALLMENT e defina a quantidade máxima de parcelas em maxInstallmentCount.

{
  "billingType": "CREDIT_CARD",
  "chargeType": "INSTALLMENT",
  "name": "Venda de eletrônicos",
  "description": "Qualquer produto em até 10x de R$ 50,00",
  "value": 500.00,
  "maxInstallmentCount": 10,
  "notificationEnabled": false
}

Nesse exemplo, o pagador poderá escolher até 10 parcelas.

Como o link aceita apenas cartão de crédito, dueDateLimitDays não é necessário.

notificationEnabled = false desabilita as notificações para os clientes cadastrados por esse link. Se o campo não for informado, o valor padrão é true.

Consulte as Notificações.

Cobrança recorrente

Use chargeType = RECURRENT para que o preenchimento do link crie uma assinatura.

{
  "billingType": "CREDIT_CARD",
  "chargeType": "RECURRENT",
  "name": "Assinatura de livros",
  "description": "Receba um livro todo mês por R$: 50,00",
  "value": 50.00,
  "subscriptionCycle": "MONTHLY"
}

Nesse fluxo, subscriptionCycle define a periodicidade da assinatura.

Os demais valores aceitos estão disponíveis na referência de criação do Link de Pagamento.

Resultado esperado

Com uma requisição válida, a API retorna HTTP 200 e o Link de Pagamento pode ser disponibilizado ao pagador.

Armazene o identificador do link para futuras consultas, alterações e inclusão de imagens.

3. Acompanhe as cobranças geradas

As cobranças criadas pelo Link de Pagamento seguem o fluxo normal de eventos de cobrança.

No payload do Webhook:

paymentLink identifica o Link de Pagamento que originou a cobrança;
customer identifica o cliente criado durante o preenchimento.

Consulte os Eventos para cobranças.

Se precisar recuperar os dados do cliente gerado, utilize:

Consulte o endpoint Recuperar um único cliente.

👍
Recomendado
Utilize Webhooks como mecanismo principal para acompanhar as cobranças geradas.
Evite polling frequente para verificar alterações de status. Consultas à API consomem a cota da conta e podem retornar HTTP 429 Too Many Requests quando os limites aplicáveis são atingidos.
Consulte Limites da API.

🚧
Duplicação de clientes em links de pagamento
No Asaas, é possível criar clientes com CPF/CNPJ duplicados. Pelo link de pagamento, como o cliente é sempre criado no momento da geração da cobrança, caso ele já exista no Asaas, o cliente será cadastrado novamente, aparecendo duas ou mais vezes (a depender da quantidade de vezes que gerou a cobrança).

4. Adicione imagens

É possível adicionar até 5 imagens ao Link de Pagamento.

Utilize:

POST /v3/paymentLinks/{id}/images

Envie o arquivo com:

Content-Type: multipart/form-data

Para definir a imagem enviada como principal, informe:

main = true

Consulte o endpoint Adicionar uma imagem a um link de pagamentos.

Próximos passos

Updated 18 days ago

Did this page help you?