Criar um link de pagamento

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_MSbm4BKVx7zTSvdm"
      }
    ]
  }'

{
  "id": "plink_ZB7ThNNYSCF5BQ3V",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description_mode": null,
    "product_image_mode": null,
    "product_subtitle_source": null,
    "require_billing_address": null,
    "require_document": null,
    "require_phone": null,
    "show_compare_at_amount": false,
    "summary_style": null,
    "tracking": {
      "destinations": [],
      "mode": "inherit"
    }
  },
  "created_at": "2026-05-02T18:31:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Bio do Instagram - Plano Pro",
  "line_items": [
    {
      "id": "pli_cxo2Vmc7HXAF3wGN",
      "adjustable_quantity": {
        "enabled": false,
        "maximum": null,
        "minimum": null
      },
      "amount_discount": 0,
      "amount_subtotal": 12990,
      "amount_tax": 0,
      "amount_total": 12990,
      "currency": "brl",
      "description": "Plano Pro",
      "metadata": {},
      "position": 0,
      "price": "price_miKnukWp4uvtPSW2",
      "price_data": null,
      "product": "prod_y6qPWGCcPUjaTf79",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 12990
    }
  ],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/obrigado",
  "template": null,
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

{
  "error": {
    "code": "invalid_request",
    "message": "all recurring line items must use the same interval and interval_count",
    "param": "line_items",
    "type": "invalid_request_error"
  }
}

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:

Token	Header	Comportamento
API key da organização (`write` ou `admin`)	`Authorization: Bearer {{API_KEY}}`	Cria para a própria organização da chave. O header `Organization` é proibido (400).
API key da plataforma (`platform_admin`)	`Authorization: Bearer {{API_KEY}}` + `Organization: <organization_id>`	Cria em nome da organização conectada indicada. Sem `Organization` → 403.

O valor do header Organization deve ser uma organização conectada ativa vinculada à plataforma; caso contrário retorna 403.

Attributes

boolean

padrão:"false"

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.

string

Pra onde o comprador é redirecionado se cancelar/abandonar o checkout.

array

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 (centavos, 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.

object | null

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 e a mensagem de confirmação, remove o funil 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.

Campo	Valores
`summary_style`	`product`, `subscription`, `offer` ou `null`
`product_image_mode`	`hidden`, `thumbnail`, `hero` ou `null`
`product_subtitle_source`	`description`, `organization` ou `null`; `null` herda o padrão da organização
`cover_image_url`	URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa
`product_description_mode`	`hidden`, `summary`, `full` ou `null`
`order_summary_mode`	`expanded`, `collapsible`, `compact`, `hidden` ou `null`
`installment_teaser_mode`	`hidden`, `maximum_installment`, `lowest_installment` ou `null`
`header_shows_logo`	Booleano ou `null`
`require_document`, `require_phone`, `require_billing_address`	Booleano ou `null`

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.

Mostrar Configuração da experiência

string | null

Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou null remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.

string | null

Funil ativo e pronto da mesma organização e ambiente. null remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna 409.

boolean

Exibe o preço de referência riscado acima do valor cobrado. Padrão false. O valor vem de compare_at_amount no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas.

boolean

Exibe suporte e termos cadastrados na organização. Padrão false; false também desliga o rodapé. Não exige aceite do comprador.

object | null

Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.

Mostrar Campos do banner

string | null

Cor de fundo em hexadecimal de 6 dígitos, como #27272a. null usa o tom escolhido. A cor do texto é ajustada para manter o contraste.

string

obrigatório

strip, highlight, countdown ou marquee.

string

obrigatório

Mensagem entre 1 e 500 caracteres, exibida como texto.

string

padrão:"neutral"

neutral, urgent ou success; usa as cores do design system.

string | null

Etiqueta opcional, até 40 caracteres.

string | null

Trecho em destaque, até 120 caracteres.

string | null

Instante ISO 8601 com fuso horário, obrigatório para countdown. Ao terminar, somente o banner desaparece.

string

ID de um desconto a aplicar automaticamente em todas as sessões geradas.

boolean

padrão:"false"

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.

string

Nome interno do link (visível só pra organização). Não aparece pro comprador.

array

obrigatório

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 interval e interval_count;
quando price_data é usado, exatamente um entre product_id e product_data deve acompanhá-lo — os dois juntos ou nenhum retorna 400.

Mostrar line_items[]

object

Deixa o comprador mudar a quantidade deste item durante o checkout. Ausente equivale a desligado: o item cobra exatamente a quantity enviada.

Mostrar adjustable_quantity

boolean

obrigatório

true libera o ajuste no checkout.

integer

Quantidade máxima que o comprador pode escolher. Padrão 99, teto 999999. Precisa ser >= quantity.

integer

Quantidade mínima que o comprador pode escolher. Padrão 0. Em checkout de item único o piso efetivo é 1 — o comprador não remove a única coisa que a sessão cobra.

string

Descrição livre — sobrescreve o nome do produto na exibição do checkout.

object

Metadata livre do item, ecoada no snapshot de line_items da sessão.

object

Preço ad-hoc — não persiste no catálogo, vive só nas sessões geradas a partir do link. Mutuamente exclusivo com price_id.

Mostrar price_data

string

obrigatório

Código ISO de 3 letras (ex.: brl).

object

Produto ad-hoc. Obrigatório se product_id não foi enviado.

Mostrar product_data

string

Descrição livre.

string

obrigatório

Nome do produto exibido no checkout.

string

ID de produto existente do catálogo. Obrigatório se product_data não foi enviado.

object

Quando presente, marca o item como recorrente — sessões geradas nascem em modo subscription.

Mostrar recurring

string

obrigatório

Intervalo de recorrência.

Valor	Descrição
`day`	Cobrança diária.
`week`	Cobrança semanal.
`month`	Cobrança mensal.
`year`	Cobrança anual.

integer

Quantos intervalos por ciclo. Padrão 1. Máximo por unidade: day=1460, week=208, month=48, year=4. Trimestral é month + 3; semestral é month + 6.

integer

obrigatório

Valor unitário em centavos (ex.: 19990 = R$ 199,90). Aceita zero e qualquer inteiro positivo. O mínimo da cobrança vale para o total final, depois dos descontos.

string

ID de um preço já cadastrado no catálogo da org alvo. Mutuamente exclusivo com price_data.

integer

Padrão 1. Inteiro >= 1.

object

Objeto chave-valor livre. Cada session gerada do link recebe esse metadata copiado. Padrão: {}.

string

padrão:"always"

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.

object | null

padrão:"null"

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.

object

Configuração da assinatura que o link vai criar. Copiada para cada session gerada. Só vale para link recorrente; em link avulso retorna 400.

Mostrar subscription_data

object

Metadata aplicada à assinatura criada.

integer

Dias de avaliação gratuita antes da primeira cobrança. Inteiro >= 1. Link não aceita trial_end: ele é reutilizável e não expira, então um instante fixo valeria para todo comprador e um dia estaria no passado.

object

O que acontece quando a avaliação termina sem forma de pagamento no arquivo.

Mostrar trial_settings

object

obrigatório

Mostrar end_behavior

string

obrigatório

Valor	Efeito no fim da avaliação
`create_invoice`	Padrão. Gera a fatura do ciclo normalmente.
`pause`	Pausa a assinatura até o cliente cadastrar uma forma de pagamento.
`cancel`	Cancela a assinatura.

string

Pra onde o comprador é redirecionado após pagamento aprovado.

string | null

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.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_MSbm4BKVx7zTSvdm"
      }
    ]
  }'

Quando o 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

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_id": "prod_EBJFKiR9A95nAeYo",
          "unit_amount": 12990
        }
      }
    ]
  }'

Pra que o link seja recorrente, adicione recurring em price_data:

{
  "price_data": {
    "currency": "brl",
    "product_id": "prod_EBJFKiR9A95nAeYo",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "unit_amount": 12990
  }
}

(c) Produto e preço ad-hoc

Nada vem do catálogo — útil pra integrações headless que não cadastram produto.

cURL

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_data": {
            "name": "Consultoria avulsa"
          },
          "unit_amount": 4990
        }
      }
    ]
  }'

(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

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "price_id": "price_MSbm4BKVx7zTSvdm", "quantity": 1 },
      { "price_id": "price_QW2nSe8M5UjR3xKP", "quantity": 1 }
    ]
  }'

(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

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_url": "https://meusite.com/checkout/cancelado",
    "has_surcharge": false,
    "label": "Campanha de lançamento",
    "line_items": [
      { "price_id": "price_MSbm4BKVx7zTSvdm", "quantity": 2 }
    ],
    "metadata": {},
    "payment_method_collection": "always",
    "subscription_data": {},
    "success_url": "https://meusite.com/checkout/obrigado"
  }'

(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

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_id": "disc_9ojtq5iDfgtEH21v",
    "line_items": [
      { "price_id": "price_MSbm4BKVx7zTSvdm" }
    ]
  }'

(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

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "price_id": "price_MSbm4BKVx7zTSvdm" }
    ],
    "payment_method_options": {
      "credit_card": {
        "installments": { "interest_payer": "organization" }
      }
    }
  }'

Como plataforma (em nome de uma organização conectada)

Adicione o header Organization 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

url pública do link é gerada na criação — é só compartilhar. Cada clique materializa uma checkout.session nova copiando line_items e metadata.
is_active nasce true e o link não expira. Ele só para de aceitar cliques quando você desativa (update ou delete com histórico).
mode das 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.

string

Identificador, prefixo plink_.

string

Sempre payment_link.

string | null

URL de cancelamento configurada. null se não enviado.

object

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, 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.

string

ISO 8601.

string | null

ID do desconto auto-aplicado, ou null.

boolean

true quando o comprador cobre a taxa da organização.

boolean

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.

string

Nome interno (visível só pra organização). null se não enviado.

array

Itens fixados. Cada session gerada do link copia 1:1.

boolean

Indica se o link foi criado em modo live.

object

Metadata configurada.

string

always ou if_required. Cada session gerada nasce com esse valor.

object

Configuração da assinatura fixada no link. {} quando o link não é recorrente ou não configura nada.

string | null

URL de sucesso configurada. null se não enviado.

string | null

ISO 8601 da última edição, ou null se nunca editado.

string

URL pública pra compartilhar com compradores. Cada clique materializa uma checkout.session.

{
  "id": "plink_ZB7ThNNYSCF5BQ3V",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description_mode": null,
    "product_image_mode": null,
    "product_subtitle_source": null,
    "require_billing_address": null,
    "require_document": null,
    "require_phone": null,
    "show_compare_at_amount": false,
    "summary_style": null,
    "tracking": {
      "destinations": [],
      "mode": "inherit"
    }
  },
  "created_at": "2026-05-02T18:31:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Bio do Instagram - Plano Pro",
  "line_items": [
    {
      "id": "pli_cxo2Vmc7HXAF3wGN",
      "adjustable_quantity": {
        "enabled": false,
        "maximum": null,
        "minimum": null
      },
      "amount_discount": 0,
      "amount_subtotal": 12990,
      "amount_tax": 0,
      "amount_total": 12990,
      "currency": "brl",
      "description": "Plano Pro",
      "metadata": {},
      "position": 0,
      "price": "price_miKnukWp4uvtPSW2",
      "price_data": null,
      "product": "prod_y6qPWGCcPUjaTf79",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 12990
    }
  ],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/obrigado",
  "template": null,
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

{
  "error": {
    "code": "invalid_request",
    "message": "all recurring line items must use the same interval and interval_count",
    "param": "line_items",
    "type": "invalid_request_error"
  }
}

Erros comuns

Status	`code`	Quando
`400`	`invalid_request`	`line_items` ausente, vazio ou item sem `price_id` nem `price_data`.
`400`	`invalid_request`	Item com `price_id` e `price_data` enviados juntos.
`400`	`invalid_request`	`price_data` sem `product_id` nem `product_data`, ou com ambos.
`400`	`invalid_request`	`price_data.recurring.interval` inválido ou `interval_count` não-inteiro, < 1 ou acima do teto da unidade.
`400`	`invalid_request`	Mistura de itens recorrentes e únicos, moedas divergentes ou recurso fora da organização atuante.
`400`	`invalid_request`	Itens recorrentes com `interval` ou `interval_count` diferentes no mesmo link.
`400`	`invalid_request`	`adjustable_quantity` sem `enabled` booleano, com faixa invertida (`maximum` < `minimum`) ou com faixa que não comporta a `quantity` enviada.
`400`	`invalid_request`	`subscription_data` ou `payment_method_collection` em link avulso — os dois só valem em link recorrente.
`400`	`invalid_request`	`subscription_data.trial_period_days` não-inteiro ou < 1, `trial_end` enviado, ou `trial_settings.end_behavior.missing_payment_method` fora de cancel/create_invoice/pause.
`400`	`invalid_request`	`has_surcharge: true` com item recorrente — o repasse de taxa vale só para cobrança avulsa.
`400`	`parameter_unknown`	`plan` dentro de `payment_method_options.credit_card.installments` — a quantidade de parcelas é escolha do comprador; a oferta declara só `interest_payer`.
`400`	`invalid_request`	Header `Organization` enviado com API key de organização.
`403`	`permission_denied`	API key de plataforma sem header `Organization`.
`403`	`permission_denied`	Organização indicada não está conectada e ativa sob a plataforma.

Webhooks

Cada criação dispara o evento payment.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 }).

object | null

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.

integer | null

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.

array | null

Meios oferecidos no checkout: credit_card, pix e boleto. Envie uma lista não vazia, sem repetições. null herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_MSbm4BKVx7zTSvdm"
      }
    ]
  }'

{
  "id": "plink_ZB7ThNNYSCF5BQ3V",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description_mode": null,
    "product_image_mode": null,
    "product_subtitle_source": null,
    "require_billing_address": null,
    "require_document": null,
    "require_phone": null,
    "show_compare_at_amount": false,
    "summary_style": null,
    "tracking": {
      "destinations": [],
      "mode": "inherit"
    }
  },
  "created_at": "2026-05-02T18:31:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Bio do Instagram - Plano Pro",
  "line_items": [
    {
      "id": "pli_cxo2Vmc7HXAF3wGN",
      "adjustable_quantity": {
        "enabled": false,
        "maximum": null,
        "minimum": null
      },
      "amount_discount": 0,
      "amount_subtotal": 12990,
      "amount_tax": 0,
      "amount_total": 12990,
      "currency": "brl",
      "description": "Plano Pro",
      "metadata": {},
      "position": 0,
      "price": "price_miKnukWp4uvtPSW2",
      "price_data": null,
      "product": "prod_y6qPWGCcPUjaTf79",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 12990
    }
  ],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/obrigado",
  "template": null,
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

{
  "error": {
    "code": "invalid_request",
    "message": "all recurring line items must use the same interval and interval_count",
    "param": "line_items",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Criar um link de pagamento

Autenticação

Attributes

Cenários de `line_items`

(a) Preço do catálogo

(b) Produto do catálogo + preço ad-hoc

(c) Produto e preço ad-hoc

(d) Vários produtos no mesmo link

(e) Link completo: retorno, repasse e correlação

(f) Link com desconto pré-aplicado

(g) Link em que a organização paga os juros do parcelamento

Como plataforma (em nome de uma organização conectada)

O que a Chargefy resolve sozinha

Resposta

Erros comuns

Webhooks

​Autenticação

​Attributes

​Cenários de line_items

​(a) Preço do catálogo

​(b) Produto do catálogo + preço ad-hoc

​(c) Produto e preço ad-hoc

​(d) Vários produtos no mesmo link

​(e) Link completo: retorno, repasse e correlação

​(f) Link com desconto pré-aplicado

​(g) Link em que a organização paga os juros do parcelamento

​Como plataforma (em nome de uma organização conectada)

​O que a Chargefy resolve sozinha

​Resposta

​Erros comuns

​Webhooks

Autenticação

Attributes

Cenários de `line_items`

(a) Preço do catálogo

(b) Produto do catálogo + preço ad-hoc

(c) Produto e preço ad-hoc

(d) Vários produtos no mesmo link

(e) Link completo: retorno, repasse e correlação

(f) Link com desconto pré-aplicado

(g) Link em que a organização paga os juros do parcelamento

Como plataforma (em nome de uma organização conectada)

O que a Chargefy resolve sozinha

Resposta

Erros comuns

Webhooks