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,
  "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": {},
  "payment_method_collection": "always",
  "subscription_data": {},
  "success_url": "https://meusite.com/obrigado",
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

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 experiência do checkout vem do Checkout Builder da organização, não do payload do link. 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

default:"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.

string

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

boolean

default:"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

required

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

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

Show adjustable_quantity

boolean

required

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

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.

Show price_data

string

required

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

object

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

Show product_data

string

Descrição livre.

string

required

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.

Show recurring

string

required

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

required

Valor unitário em centavos (ex.: 19990 = R

199,90). Valor positivo tem mínimo `500` (R

5,00).

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

default:"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

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

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

Show trial_settings

object

required

Show end_behavior

string

required

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.

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 -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 -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) 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 -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"
  }'

(e) 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 -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" }
    ]
  }'

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.
Aparência e comportamento do checkout vêm da única configuração atual da organização e não são copiados para o link.

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.

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,
  "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": {},
  "payment_method_collection": "always",
  "subscription_data": {},
  "success_url": "https://meusite.com/obrigado",
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

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`	`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`	`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 }).

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,
  "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": {},
  "payment_method_collection": "always",
  "subscription_data": {},
  "success_url": "https://meusite.com/obrigado",
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

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) Link completo: retorno, repasse e correlação

(e) Link com desconto pré-aplicado

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) Link completo: retorno, repasse e correlação

​(e) Link com desconto pré-aplicado

​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) Link completo: retorno, repasse e correlação

(e) Link com desconto pré-aplicado

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

O que a Chargefy resolve sozinha

Resposta

Erros comuns

Webhooks