Links de pagamento

Visão geral

Um link de pagamento é uma URL que você compartilha com o cliente e que abre uma página de checkout hospedada pela PlugToPay. Não é preciso escrever frontend: você cria o link pela API, envia o endereço e o cliente paga.

Lojista (API key)              PlugToPay API             Cliente (navegador)
──────────────────             ─────────────             ───────────────────
POST /payment-links      →     cria e armazena
                         ←     link + checkout_url

                                                    abre o checkout_url
                                                    ↓
                                               GET  /p/{token}
                                                    → dados públicos do link
                                                    preenche nome, e-mail e CPF/CNPJ
                                                    ↓
                                               POST /p/{token}/session
                                                    → cria a sessão de checkout
                                               POST /checkout/payments/card|pix

Existem dois tipos de link:

Tipo	Cobrança	Métodos aceitos
`one_time`	Uma cobrança de valor fixo	Cartão e/ou PIX
`subscription`	Recorrente, atrelada a um plano	Somente cartão

Um link de assinatura nunca recebe amount — o valor vem do plano. O payment_method é forçado para card na criação.

Links de assinatura ainda não podem ser pagos. A criação e o gerenciamento funcionam, mas o pagamento pelo checkout hospedado está bloqueado até a cobrança recorrente ficar pronta no servidor. Use links avulsos por enquanto.

Duas URLs para o mesmo link

Formato	Quando funciona
`{CHECKOUT_URL}/pay/{token}`	Sempre
`{CHECKOUT_URL}/{company_slug}/{link_slug}`	Quando a empresa e o link têm `slug` definido

O campo checkout_url da resposta já entrega o endereço correto — prefira usá-lo em vez de montar a URL manualmente.

A página pública de um link nunca expõe cartões salvos: saved_cards volta sempre vazio, independentemente do e-mail ou CPF que o comprador anônimo digitar. A regra é aplicada no servidor, então ninguém consegue ver ou reutilizar o cartão de outra pessoa por um link público.

Criar um link

POST /api/v1/payment-links — requer X-Client-ID + X-API-Key.

Link avulso

POST /api/v1/payment-links
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...

{
  "title": "Curso Premium",
  "description": "Acesso vitalício ao curso premium.",
  "type": "one_time",
  "amount": 29900,
  "currency": "BRL",
  "payment_method": "card",
  "slug": "curso-premium",
  "items": [
    {
      "name": "Curso Premium",
      "description": "Acesso vitalício",
      "quantity": 1,
      "unit_price": 29900,
      "image_url": "https://meusite.com/curso.png"
    }
  ],
  "success_url": "https://meusite.com/obrigado",
  "cancel_url": "https://meusite.com/cancelado",
  "expires_at": "2026-12-31T23:59:59Z"
}

Link de assinatura

{
  "title": "Assinatura mensal",
  "description": "Acesso a todos os recursos por um mês.",
  "type": "subscription",
  "plan_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "currency": "BRL",
  "success_url": "https://meusite.com/bem-vindo",
  "cancel_url": "https://meusite.com/cancelado"
}

Campos

Campo	Tipo	Obrigatório	Descrição
`title`	string (max 255)	sim	Título exibido no checkout
`description`	string	não	Texto de apoio exibido abaixo do título
`type`	`one_time\|subscription`	sim	Imutável depois de criado
`amount`	inteiro (centavos, min 1)	só em `one_time`	Proibido em `subscription`
`plan_uuid`	uuid	só em `subscription`	Proibido em `one_time`; precisa existir
`currency`	string (3 letras)	não	Padrão `BRL`
`payment_method`	`card\|pix`	não	Omitir aceita ambos. Sempre `card` em assinaturas
`slug`	string (3–100)	não	Só minúsculas, números e hífens: `^[a-z0-9]+(?:-[a-z0-9]+)*$`. Único por empresa
`items`	array	não	Itens exibidos no resumo do pedido
`items[].name`	string (max 255)	sim (por item)	Nome do item
`items[].quantity`	inteiro (min 1)	sim (por item)	Quantidade
`items[].unit_price`	inteiro (centavos)	sim (por item)	Preço unitário
`items[].image_url`	URL	não	Miniatura do item
`success_url`	URL (max 2048)	não	Para onde o comprador vai depois de um pagamento aprovado
`cancel_url`	URL (max 2048)	não	Reservado para uma desistência explícita do comprador — ver o aviso abaixo
`is_active`	booleano	não	Padrão `true`
`expires_at`	data/hora	não	Precisa ser futura. Sem valor = nunca expira

success_url e cancel_url precisam usar https e não podem apontar para localhost, domínios .local ou IPs privados. Qualquer um desses casos devolve 422.

Um cartão recusado não redireciona. A página hospedada mostra o motivo da recusa e um botão de tentar de novo, em vez de mandar o comprador para a cancel_url — uma recusa quase sempre se resolve com outro cartão, e tirar o comprador da página encerraria a venda. Hoje só um pagamento aprovado leva à success_url; a cancel_url fica guardada para uma desistência explícita, que a página ainda não oferece.

Resposta 201:

{
  "token": "pl_live_a1b2c3d4e5f6...",
  "slug": "curso-premium",
  "title": "Curso Premium",
  "description": "Acesso vitalício ao curso premium.",
  "type": "one_time",
  "amount": 29900,
  "currency": "BRL",
  "payment_method": "card",
  "plan_id": null,
  "plan_uuid": null,
  "items": [
    {
      "name": "Curso Premium",
      "description": "Acesso vitalício",
      "quantity": 1,
      "unit_price": 29900,
      "image_url": "https://meusite.com/curso.png"
    }
  ],
  "success_url": "https://meusite.com/obrigado",
  "cancel_url": "https://meusite.com/cancelado",
  "is_active": true,
  "expires_at": "2026-12-31T23:59:59+00:00",
  "checkout_url": "https://checkout.plugtopay.com/minha-empresa/curso-premium",
  "created_at": "2026-07-09T12:00:00+00:00"
}

O slug da empresa é gerado a partir do nome no cadastro e pode ser alterado depois em PUT /user/company.

Gerenciar links

Todas as rotas abaixo aceitam X-Client-ID + X-API-Key.

Listar

GET /api/v1/payment-links?per_page=20&page=1

Resposta paginada no formato { "data": [...], "meta": { ... } }.

Buscar um link

GET /api/v1/payment-links/pl_live_a1b2c3d4e5f6

Atualizar

Todos os campos são opcionais. type não pode ser alterado. O slug pode ser definido pela primeira vez ou trocado — é assim que se muda a checkout_url do formato por token para o formato legível.

PUT /api/v1/payment-links/pl_live_a1b2c3d4e5f6
Content-Type: application/json

{
  "title": "Curso Premium — turma 2",
  "slug": "curso-premium-2",
  "is_active": false,
  "expires_at": "2026-09-01T00:00:00Z"
}

Resposta 200 com o mesmo formato da criação.

Em links de assinatura, payment_method continua aceitando pix na atualização, mas o checkout só processa cartão. Mantenha card.

Remover

DELETE /api/v1/payment-links/pl_live_a1b2c3d4e5f6

Resposta 204 sem corpo. É uma remoção lógica: quem abrir a checkout_url depois disso recebe 404.

Rotas públicas (sem autenticação)

São as rotas que a página de checkout usa. Não exigem chave de API — o token do link já é o segredo.

Dados públicos do link

curl https://api.plugtopay.com/api/v1/p/pl_live_a1b2c3d4e5f6

Ou pelo par de slugs:

curl https://api.plugtopay.com/api/v1/p/minha-empresa/curso-premium

Resposta 200 — link avulso:

{
  "token": "pl_live_a1b2c3d4e5f6...",
  "title": "Curso Premium",
  "description": "Acesso vitalício ao curso premium.",
  "type": "one_time",
  "amount": 29900,
  "currency": "BRL",
  "payment_method": "card",
  "items": [...],
  "plan": null
}

Resposta 200 — link de assinatura:

{
  "token": "pl_live_a1b2c3d4e5f6...",
  "title": "Assinatura mensal",
  "type": "subscription",
  "amount": null,
  "currency": "BRL",
  "payment_method": "card",
  "items": null,
  "plan": {
    "name": "Básico mensal",
    "amount": 4990,
    "interval": "monthly",
    "interval_count": 1,
    "trial_period_days": 0
  }
}

Esse recurso é um subconjunto seguro: não devolve company_id, as URLs de redirecionamento nem o slug do link.

Criar a sessão de checkout

POST /api/v1/p/pl_live_a1b2c3d4e5f6/session
Content-Type: application/json

{
  "full_name": "Maria Silva",
  "email": "maria.silva@example.com",
  "cpf_cnpj": "12345678909",
  "coupon_code": "PROMO10"
}

Campo	Obrigatório	Descrição
`full_name`	sim	Nome completo do comprador
`email`	sim	E-mail válido
`cpf_cnpj`	sim	CPF (11 dígitos) ou CNPJ (14 dígitos)
`coupon_code`	não	Cupom de desconto; só se aplica a links de assinatura

Resposta 201 com o mesmo formato de uma sessão de checkout comum, incluindo success_url, cancel_url e expires_at. Guarde o token: ele é o X-Checkout-Token do passo seguinte.

A sessão é de uso único. Uma tentativa recusada consome o token — crie outra sessão para a próxima tentativa.

Submeter o pagamento

Com o token da sessão em mãos, o fluxo é exatamente o do checkout: POST /api/v1/checkout/payments/card ou /pix com o header X-Checkout-Token. A sessão trava amount, currency e merchant_order_id, e o método também é respeitado: se o link foi criado apenas para cartão, enviar para a rota de PIX devolve 422.

Quando um link fica indisponível

As rotas públicas devolvem 404 em qualquer um destes casos:

Condição	Resultado
`is_active` é `false`	Indisponível
`expires_at` já passou	Indisponível
Link removido	Não encontrado

Formato do token

O token tem o prefixo pl_live_ seguido de 56 caracteres hexadecimais:

pl_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Referência rápida de rotas

Método	Rota	Auth
`POST`	`/api/v1/payment-links`	`X-Client-ID` + `X-API-Key`
`GET`	`/api/v1/payment-links`	`X-Client-ID` + `X-API-Key`
`GET`	`/api/v1/payment-links/{token}`	`X-Client-ID` + `X-API-Key`
`PUT`	`/api/v1/payment-links/{token}`	`X-Client-ID` + `X-API-Key`
`DELETE`	`/api/v1/payment-links/{token}`	`X-Client-ID` + `X-API-Key`
`GET`	`/api/v1/p/{token}`	pública
`POST`	`/api/v1/p/{token}/session`	pública
`GET`	`/api/v1/p/{companySlug}/{linkSlug}`	pública
`POST`	`/api/v1/p/{companySlug}/{linkSlug}/session`	pública

As mesmas rotas de gerenciamento existem sob /api/v1/user/payment-links para uso do painel, autenticadas com Authorization: Bearer <jwt> em vez da chave de API.

Introdução

Orquestração

Pagamentos

Assinaturas

Recursos

Links de pagamento

Visão geral

Duas URLs para o mesmo link

Criar um link

Link avulso

Link de assinatura

Campos

Gerenciar links

Listar

Buscar um link

Atualizar

Remover

Rotas públicas (sem autenticação)

Dados públicos do link

Criar a sessão de checkout

Submeter o pagamento

Quando um link fica indisponível

Formato do token

Referência rápida de rotas

​Visão geral

​Duas URLs para o mesmo link

​Criar um link

​Link avulso

​Link de assinatura

​Campos

​Gerenciar links

​Listar

​Buscar um link

​Atualizar

​Remover

​Rotas públicas (sem autenticação)

​Dados públicos do link

​Criar a sessão de checkout

​Submeter o pagamento

​Quando um link fica indisponível

​Formato do token

​Referência rápida de rotas

Visão geral

Duas URLs para o mesmo link

Criar um link

Link avulso

Link de assinatura

Campos

Gerenciar links

Listar

Buscar um link

Atualizar

Remover

Rotas públicas (sem autenticação)

Dados públicos do link

Criar a sessão de checkout

Submeter o pagamento

Quando um link fica indisponível

Formato do token

Referência rápida de rotas