POST /v1/payment-links

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.

Autenticação

Aceita dois tipos de API key:

Token	Header	Comportamento
Organization API key (`write` ou `admin`)	`Authorization: Bearer ch_live_...`	Cria pra própria org da key. Header `Organization` é proibido (400).
Platform API key (`platform_admin`)	`Authorization: Bearer ch_live_...` + `Organization: <organization_id>`	Cria em nome da sub-org indicada. Sem `Organization` → 403.

O valor do header Organization deve ser uma sub-org ativa vinculada à platform; caso contrário retorna 403.

Corpo da Requisição

line_items

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

Show line_items[]

price_id

string

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

price_data

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

currency

string

required

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

unit_amount

integer

required

Valor unitário em centavos (ex.: 19990 = R$ 199,90).

product_id

string

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

product_data

object

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

Show product_data

name

string

required

Nome do produto exibido no checkout.

description

string

Descrição livre.

recurring

object

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

Show recurring

interval

string

required

day, week, month ou year.

interval_count

integer

Quantos intervalos por ciclo. Default 1.

quantity

integer

Default 1. Inteiro >= 1.

description

string

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

label

string

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

success_url

string

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

cancel_url

string

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

allow_discount_codes

boolean

default:"true"

Se o comprador pode inserir cupom no checkout.

discount_id

string

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

require_billing_address

boolean

default:"false"

Quando true, endereço de cobrança é obrigatório no checkout.

no_fees_installments

boolean

default:"false"

Quando true, parcelas são oferecidas sem juros pro comprador.

metadata

object

Objeto chave-valor livre. Cada session gerada do link recebe esse metadata copiado. Em conflito com utm_* ou reference_id da URL do clique, o valor do link prevalece.

recurring_interval

string

Atalho — quando enviado (month ou year), resolve pro plano recorrente seedado da org. Mutuamente exclusivo com billing_plan_id.

Resposta

201 Created com o objeto canônico do payment link.

string

Identificador, prefixo plink_.

organization_id

string

Org dona do link. Em chamadas de plataforma, é a sub-org indicada no header Organization.

label

string

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

url

string

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

active

boolean

true enquanto o link aceita cliques. Vira false após arquivamento — cliques retornam 404, mas sessões já materializadas continuam vivas.

livemode

boolean

true quando criado por chave ch_live_*; false por chave ch_test_*. JWT do dashboard sempre true.

success_url

string

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

cancel_url

string

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

allow_discount_codes

boolean

Se cupons são permitidos no checkout.

discount_id

string

ID do desconto auto-aplicado, ou null.

require_billing_address

boolean

Se endereço de cobrança é obrigatório.

no_fees_installments

boolean

Se parcelas saem sem juros.

metadata

object

Metadata configurado.

created_at

string

ISO 8601.

modified_at

string

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

line_items

array

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

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. Resolve produto, preço e (se for o caso) recorrência automaticamente a partir do price_id.

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": "id_456", "quantity": 1 }
    ],
    "label": "Bio do Instagram - Plano Pro",
    "success_url": "https://meusite.com/obrigado"
  }'

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": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "brl",
          "unit_amount": 12990,
          "product_id": "id_123"
        }
      }
    ],
    "success_url": "https://meusite.com/obrigado"
  }'

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

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

(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": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "brl",
          "unit_amount": 4990,
          "product_data": {
            "name": "Consultoria avulsa",
            "description": "Sessão de 1h por videoconferência"
          }
        }
      }
    ],
    "success_url": "https://meusite.com/obrigado"
  }'

Como plataforma (em nome de uma sub-org)

Adicione o header Organization apontando pra sub-org. O body é idêntico aos cenários acima.

cURL

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: id_123" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "price_id": "id_456", "quantity": 1 }
    ],
    "success_url": "https://plataforma.com/sucesso"
  }'

Resposta de exemplo

Resposta do cenário (a):

{
  "id": "id_789",
  "organization_id": "id_123",
  "label": "Bio do Instagram - Plano Pro",
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5...",
  "active": true,
  "livemode": true,
  "success_url": "https://meusite.com/obrigado",
  "cancel_url": null,
  "allow_discount_codes": true,
  "discount_id": null,
  "require_billing_address": false,
  "no_fees_installments": false,
  "metadata": {},
  "created_at": "2026-05-02T18:31:00Z",
  "modified_at": null,
  "line_items": [
    {
      "price_id": "id_456",
      "price_data": null,
      "product_id": "id_321",
      "quantity": 1,
      "currency": "brl",
      "unit_amount": 12990,
      "amount_subtotal": 12990,
      "amount_discount": 0,
      "amount_tax": 0,
      "amount_total": 12990,
      "description": "Plano Pro",
      "metadata": {},
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "position": 0
    }
  ]
}

Erros comuns

HTTP	Razão
`400`	`line_items` ausente, vazio ou item sem `price_id` nem `price_data`.
`400`	Item com `price_id` e `price_data` enviados juntos (envie exatamente um).
`400`	`price_data` enviado sem `product_id` nem `product_data` — ou com ambos. Envie exatamente um.
`400`	`price_data.recurring.interval` inválido (use `day`, `week`, `month` ou `year`).
`400`	Mistura de itens recorrentes e únicos no mesmo link. Ou todos são recorrentes, ou nenhum.
`400`	Currency divergente entre os items.
`400`	`price_id` / `product_id` não pertence à org alvo.
`400`	Header `Organization` enviado com chave de organização (chave já trava na própria org).
`403`	Token de plataforma sem header `Organization`.
`403`	Header `Organization` aponta pra org que não é sub-org ativa da plataforma.

Webhooks

Cada criação dispara o evento payment_link.created pra todos os endpoints de webhook ativos da org dona (e das plataformas-pai dela). Payload é o mesmo objeto retornado pelo POST, embrulhado em envelope Standard Webhooks ({ type, id, created_at, data }).

General

Core API

Customer Portal API

Webhook Events

POST /v1/payment-links

Autenticação

Corpo da Requisição

Resposta

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

Como plataforma (em nome de uma sub-org)

Resposta de exemplo

Erros comuns

Webhooks

General

Core API

Customer Portal API

Webhook Events

Documentation Index

​Autenticação

​Corpo da Requisição

​Resposta

​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

​Como plataforma (em nome de uma sub-org)

​Resposta de exemplo

​Erros comuns

​Webhooks

Autenticação

Corpo da Requisição

Resposta

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

Como plataforma (em nome de uma sub-org)

Resposta de exemplo

Erros comuns

Webhooks