Link de Pagamento Recorrente

O Link de Pagamento Recorrente permite criar uma assinatura através de um checkout hospedado pela Barte. Ao acessar o link, o cliente realiza a contratação e os pagamentos passam a ocorrer de forma recorrente, conforme o plano configurado.

Esse tipo de link é indicado para planos, mensalidades, serviços contínuos e cobranças recorrentes, sem a necessidade de checkout próprio.

⚠️ Para criar um link de pagamento recorrente, antes é preciso criar um plano de assinatura. Veja mais em: Criando Plano de Assinatura

---

Quando usar Link de Pagamento Recorrente?

Utilize esse recurso quando:

• A cobrança for recorrente

• Você trabalha com planos ou mensalidades

• Deseja simplificar a contratação de assinaturas

• Precisa enviar links por WhatsApp, e-mail ou redes sociais

• Quer um checkout pronto e hospedado pela Barte

---

Fluxo de pagamento

Link de pagamento recorrente é criado
                ↓
Link é enviado ao cliente
                ↓
Cliente acessa o checkout Barte
                ↓
Assinatura é contratada
                ↓
Cobranças recorrentes são processadas
                ↓
Webhooks são enviados a cada alteração de status

💡 A confirmação e atualização da assinatura deve ser feita via webhook.

---

Criando um Link de Pagamento Recorrente

Endpoint

POST /v2/payment-links

---

Headers obrigatórios

Header	Valor
X-Token-Api	Sua chave de API
Content-Type	application/json

---

Body da requisição (exemplo)

{
  "type": "SUBSCRIPTION",
  "scheduledDate": "2026-01-30",
  "uuidSellerClient": "123e4567-e89b-12d3-a456-426614174000",
  "paymentSubscription": {
    "idPlan": "123e4567-e89b-12d3-a456-426614174000",
    "type": "MONTHLY",
    "valuePerMonth": 100
  },
  "paymentMethods": [
    "PIX",
    "CREDIT_CARD_EARLY_BUYER",
    "BANK_SLIP"
  ]
}

---

Resposta da API

Após a criação, a API retorna os dados do link de pagamento recorrente.

Exemplo de resposta

{
  "id": 9450,
  "uuid": "a1b33060-6fc3-4057-bcd2-19a253c7b90e",
  "type": "SUBSCRIPTION",
  "url": "https://sandbox-checkout.barte.com/payment-link/a1b33060-6fc3-4057-bcd2-19a253c7b90e",
  "scheduledDate": "2026-01-30",
  "paymentSubscription": {
    "idPlan": "123e4567-e89b-12d3-a456-426614174000",
    "type": "MONTHLY",
    "value": 100,
    "valuePerMonth": 100
  },
  "processed": 0,
  "enableAnchoring": false,
  "allowedPaymentMethods": {
    "pixMethod": {},
    "bankSlipMethod": {},
    "creditCardMethod": {
      "type": "EARLY_BUYER"
    }
  },
  "paymentMethods": [
    "PIX",
    "BANK_SLIP",
    "CREDIT_CARD_EARLY_BUYER"
  ],
  "enableBankSlip": true,
  "enableCreditCard": true,
  "enablePixPayment": true,
  "subSellerResponse": [],
  "idSeller": 2890
}

Campo mais importante da resposta

• url → link de pagamento recorrente que deve ser enviado ao cliente

---

Atualizações da assinatura via webhook

Durante o ciclo de vida da assinatura, webhooks são enviados sempre que houver:

• Criação da assinatura

• Pagamento confirmado

• Falha de pagamento

• Cancelamento

• Alteração de status

💡 Utilize os webhooks de Subscriptions como fonte de verdade.

---

Boas práticas

• Garanta que o plano esteja configurado antes de criar o link

• Utilize webhooks para controlar o ciclo da assinatura

• Armazene o uuid do link para rastreabilidade

• Trate falhas de pagamento corretamente

---

O que não fazer

• Criar link recorrente sem plano configurado

• Confirmar assinatura sem webhook

• Ignorar eventos de falha de pagamento