Links de pagamento
Criar um link de pagamento
Cria um payment link.
O valor de cada item e a soma de preço × quantidade devem caber em o teto da moeda (
Cenários de
Existem três formas válidas de descrever um item. Use a mais idiomática pro seu caso.
Quando o
Pra que o link seja recorrente, adicione
Depois de uma contagem de 1 a 60 segundos, com a confirmação e o botão
Redirecionar agora na tela:
Só quando o comprador clicar em Continuar:
999999999 na menor unidade em brl), antes de descontos e juros. Valores acima retornam 400 amount_too_large, com param indicando o campo ou a coleção de itens.
Cria um payment link — uma URL pública compartilhável. A cada clique de um comprador, uma nova checkout.session é materializada, copiando os line_items e metadata do link. Use pra bio do Instagram, e-mail marketing, QR codes, “comprar agora” em landing page.
Só line_items é obrigatório. O link é reutilizável e não expira:
nasce com is_active: true e só sai do ar quando você desativar ou deletar. A
marca vem da organização. O link pode
personalizar a experiência com template, checkout_experience,
optional_items e condições de pagamento próprias.
Para cobrar uma invoice existente, não crie um payment link: compartilhe
invoice.hosted_invoice_url, retornado pelos endpoints de invoices.
Autenticação
Aceita dois tipos de API key:
O valor do header
Organization deve ser uma organização conectada ativa vinculada à plataforma; caso contrário retorna 403.
Attributes
null aceita a indicação por cupom válido ou pelo último clique válido de uma afiliada. Omitir na criação também aceita indicação; omitir na atualização preserva a escolha atual. [] desliga a indicação e uma lista define os afiliados explicitamente.Comissões de afiliados para vínculos ativos: cada item contém affiliation (aff_*) e
affiliate_fee_rate, inteiro de 1 a 10000 pontos-base (3000 = 30%).
Os percentuais incidem em paralelo sobre o valor líquido da venda antes das
comissões de afiliados; a soma não pode ultrapassar 10000. Até 8 afiliados em venda
direta ou 7 com plataforma. Envie [] para remover a seleção.
Veja Comissões de afiliados.Quando
true, o checkout das sessões geradas por este link mostra o campo de
código de desconto e aceita o pré-preenchimento de código pela URL
(?prefilled_promo_code=…). Veja Parâmetros de
URL.Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe
price, title e call_to_action; aceita description, tag (recommended, special_offer ou null), product_name, image (arquivo com propósito order_bump_image) e compare_at_amount (em centavos, a menor unidade da moeda, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Não envie id na criação.Configuração da página. Omitir um campo preserva sua configuração;
banner: null desliga o banner. checkout_experience: null restaura a herança da apresentação, coleta e trackeamento, limpa a capa, a descrição personalizada e a mensagem de confirmação, remove o funil, volta o redirecionamento ao padrão da organização e desliga o banner, o rodapé expandido e a ancoragem de preço.Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, null herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.Por exemplo,
show_phone: true com require_phone: false exibe WhatsApp opcional. Com os dois em true, o comprador precisa preenchê-lo. Com os dois em false, o campo fica oculto. Campos obrigatórios continuam visíveis, mesmo com show_*: false.Os campos pertencem a checkout_experience. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é false. Cores, fonte e arquivo do logo continuam na marca da organização.Moeda do link. Ao omitir, o link usa a moeda comum dos itens. Um item ou oferta de outra moeda retorna
400 currency_mismatch.Aceita hoje: brl. Maiúsculas valem como minúsculas (BRL é lido como brl); outra moeda retorna 400 com code: "unsupported_currency". Veja Moedas.Quando
true, o comprador cobre a taxa da organização: o total é acrescido do
repasse para que a organização receba líquido o valor da venda. Vale para
qualquer método escolhido pelo comprador, somente em cobrança avulsa: um link
com item recorrente não aceita repasse e a criação retorna 400. Veja
Repassar a tarifa de venda ao comprador.Itens do link. Cada item aponta pra um preço do catálogo (
price_id) ou descreve um preço inline (price_data) — exatamente um dos dois; os dois juntos ou nenhum retorna 400.Restrições de integridade aplicadas em todo o array:- todos os itens compartilham a mesma
currency; - ou todos são recorrentes, ou nenhum é (não pode misturar);
- quando recorrentes, todos usam a mesma cadência: o mesmo
intervaleinterval_count; - quando
price_dataé usado, exatamente um entreproduct_ideproduct_datadeve acompanhá-lo — os dois juntos ou nenhum retorna 400.
Objeto chave-valor livre. Cada session gerada do link recebe esse
metadata
copiado. Padrão: {}.if_required deixa o comprador iniciar a assinatura sem informar forma de
pagamento — use junto de subscription_data.trial_period_days para oferecer
avaliação gratuita sem cartão. always sempre coleta. Só vale para link
recorrente; em link avulso retorna 400.Quem paga o juro do parcelamento nas vendas deste link, em
credit_card.installments.interest_payer: buyer comprador, organization
a própria organização — o comprador parcela o valor à vista e o juro sai do
líquido dela. Omitido ou null herda a configuração de checkout da
organização a cada clique. A quantidade de parcelas é escolha do comprador no
checkout — enviar plan aqui retorna 400. Diferente do repasse de taxa, vale
também para link de assinatura: cada renovação conserva a política da venda.Configuração da assinatura que o link vai criar. Copiada para cada session
gerada. Só vale para link recorrente; em link avulso retorna 400.
Estrutura de página única:
split, sidebar ou stacked.
null herda a configuração efetiva da organização, incluindo o padrão da
plataforma que a controla. A estrutura é resolvida e congelada na criação de
cada sessão. Alterar o link não muda sessões abertas nem o endereço público.Cenários de line_items
Existem três formas válidas de descrever um item. Use a mais idiomática pro seu caso.
(a) Preço do catálogo
Caminho mais curto — e também o menor request válido: sóline_items. Resolve produto, preço e (se for o caso) recorrência automaticamente a partir do price_id.
price_id referencia um preço cujo type = recurring, as sessões geradas nascem em mode: subscription sem nenhum campo extra.
(b) Produto do catálogo + preço ad-hoc
Reusa nome/descrição/imagem do produto cadastrado, mas usa um valor único pra esse link. Útil pra promoção pontual sem criar preço novo no catálogo.cURL
recurring em price_data:
(c) Produto e preço ad-hoc
Nada vem do catálogo — útil pra integrações headless que não cadastram produto.cURL
(d) Vários produtos no mesmo link
Adicione quantos itens a oferta precisar. O exemplo abaixo vende dois produtos na mesma compra. Se os preços forem recorrentes, os dois precisam ter a mesma cadência; preços mensais e anuais, por exemplo, ficam em links separados.cURL
(e) Link completo: retorno, repasse e correlação
Os cenários acima cobrem sóline_items. Um link de produção normalmente
também define para onde o comprador volta, se repassa taxas e a chave de
correlação com o seu sistema. Esses campos são opcionais.
cURL
(f) Link com desconto pré-aplicado
discount_id aplica o desconto direto no checkout, sem o comprador digitar
código. O desconto precisa estar ativo, dentro da validade e compatível com a
moeda dos itens — caso contrário a criação falha com 400.
cURL
(g) Link em que a organização paga os juros do parcelamento
payment_method_options.credit_card.installments.interest_payer fixa quem paga
o juro das parcelas nas vendas deste link — aqui organization: o comprador
parcela pelo valor à vista e o juro é descontado do líquido da organização.
buyer soma o juro ao total do comprador. Omitido, cada clique herda a
configuração de checkout da organização. Enviar plan retorna 400: a
quantidade de parcelas é escolha do comprador no checkout.
cURL
(h) Quando o comprador volta para a sua página
checkout_experience.success_redirect fixa no link quando o comprador segue
para a success_url. Sem o campo (ou com null), o link segue o padrão da
organização, inclusive quando ele mudar. Cada clique guarda o valor do momento.
Imediatamente, direto do checkout para a sua página, sem a confirmação:
cURL
cURL
cURL
Como plataforma (em nome de uma organização conectada)
Adicione o headerOrganization apontando pra organização conectada. O body é
idêntico aos cenários acima — só a chave (platform_admin) e o header
Organization mudam.
O que a Chargefy resolve sozinha
urlpública do link é gerada na criação — é só compartilhar. Cada clique materializa umacheckout.sessionnova copiandoline_itemsemetadata.is_activenascetruee o link não expira. Ele só para de aceitar cliques quando você desativa (update ou delete com histórico).modedas sessões geradas é derivado dos itens: qualquer item recorrente →subscription; nenhum →payment.- A experiência do checkout combina os padrões da organização e as opções do link. Em cada acesso, a nova Checkout Session conserva template, apresentação, banner, pós-venda, rastreamento, meios, campos e parcelamento resolvidos naquele momento. Marca, suporte e termos permanecem compartilhados pela organização.
Resposta
200 OK com o objeto canônico do payment link.
show_compare_at_amount habilita o valor de referência riscado, cadastrado no preço. Padrão false. O estilo offer destaca o produto em uma linha horizontal, com product_subtitle_source escolhendo descrição ou organização na segunda linha. cover_image_url é uma imagem de campanha independente acima do produto; product_image_mode controla somente a imagem do produto.
Configuração da página. banner é nulo quando desligado, ou contém variant, text, tone, tag, highlight, duration_minutes, duration_seconds, ends_at e background_color. O banner é copiado do link na criação da sessão; mudanças posteriores no link não alteram sessões abertas. A mensagem não modifica as condições de cobrança. confirmation_message é a mensagem personalizada exibida após a conclusão da compra, ou null; a sessão conserva o texto do momento de sua criação. funnel é a referência ao funil escolhido, ou null. A sessão conserva essa escolha; após pagamento elegível confirmado, o funil precede success_url. Desativar o funil impede novas ofertas e preserva a compra original. footer_expanded indica se o checkout exibe suporte e termos da organização; é copiado do link na criação da sessão. success_redirect informa quando o comprador segue para a success_url: { "delay_seconds": 10, "type": "automatic" } redireciona ao fim da contagem, delay_seconds: 0 leva direto do checkout sem a confirmação, e { "delay_seconds": null, "type": "manual" } espera o clique em Continuar. null segue o padrão da organização.true enquanto o link aceita cliques. Vira false quando desativado via
update ou delete com histórico, e cliques retornam 404. Sessões já
materializadas continuam vivas.Configuração da assinatura fixada no link.
{} quando o link não é recorrente
ou não configura nada.Erros comuns
Webhooks
Cada criação dispara o eventopayment.link.created para todos os endpoints de webhook ativos da organização dona e das plataformas vinculadas a ela. Payload é o mesmo objeto retornado pelo POST em data.object, dentro do payload Standard Webhooks ({ id, object: "event", created_at, data: { object }, livemode, organization, type }).
Define os destinos de conversão desta experiência.
mode aceita inherit (padrões da organização), custom (somente destinations) ou disabled (nenhum envio). custom exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. null restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.Máximo de parcelas oferecido ao comprador, entre 1 e 12;
1 permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. null restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva interest_payer e vice-versa. A sessão guarda o limite resolvido na criação.Meios oferecidos no checkout:
credit_card, pix e boleto. Envie uma lista não vazia, sem repetições; a ordem da lista é a ordem em que o comprador vê os meios, e o primeiro já vem selecionado. null herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.
