Skip to main content
Um link de pagamento é uma página de checkout reutilizável: você define itens (preços), formas de pagamento e opções, e a Upag gera uma url para compartilhar. Cada compra inicia uma sessão de checkout.

Estrutura

As referências a outras entidades usam o nome da entidade (checkoutLayout, product, price) e trazem o UUID.

Atributos

Soma dos totais dos itens ativos, em centavos. Bumps não entram na soma.
URL pública do checkout do link. Pode vir null se a URL de checkout não estiver configurada no ambiente.
Lista com pix e/ou card (mínimo 1). Padrão: ["pix", "card"].
auto (padrão), required ou none.
couponEnabled (padrão false) permite o comprador aplicar cupons. active (padrão true): link inativo recusa novas compras (410, PAYMENT_LINK_INACTIVE).
Preços vendidos pelo link: id, product, price, quantity e amount (preço × quantidade, em centavos). Mínimo 1 item; o mesmo preço não pode repetir.
Ofertas adicionais (order bump): id, product, price, quantity, amount (centavos), title e description.
Configuração de período de teste (trial) das assinaturas criadas pelos itens recorrentes. trial é { interval: "day" | "week" | "month", intervalCount } (até 730 dias: day ≤ 730, week ≤ 104, month ≤ 24) ou null. trialSettings.endBehavior.missingPaymentMethod: create_invoice (padrão; cobra o primeiro período por Pix) ou cancel. paymentMethodCollection: always (padrão; exige método de pagamento mesmo sem cobrar hoje) ou if_required. Veja Teste grátis.

Regras de consistência

  • Todos os preços (itens e bumps) devem ter a mesma moeda — PAYMENT_LINK_CURRENCY_MISMATCH.
  • Itens recorrentes devem ter o mesmo interval e intervalCount — PAYMENT_LINK_RECURRING_INTERVAL_MISMATCH.
  • Não repita o mesmo preço em itens — PAYMENT_LINK_DUPLICATE_PRICE.
  • Um trial exige pelo menos um item recorrente — PAYMENT_LINK_TRIAL_REQUIRES_RECURRING_ITEM.
  • Com trial e paymentMethodCollection: "always", card precisa estar em paymentMethods — PAYMENT_LINK_TRIAL_REQUIRES_CARD.
Todas essas violações retornam 400.

Endpoints

Todos exigem chave secreta (sk_). Não há endpoint para excluir um link; desative-o com active: false.