Create a Payment Link

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_123"
      }
    ]
  }'

{
  "id": "plink_demo_z2kkA78c1aCGhiEj",
  "object": "payment_link",
  "allow_discount_codes": true,
  "cancel_url": null,
  "created_at": "2026-05-02T18:31:00Z",
  "discount": null,
  "is_active": true,
  "label": "Bio do Instagram - Plano Pro",
  "line_items": [
    {
      "amount_discount": 0,
      "amount_subtotal": 12990,
      "amount_tax": 0,
      "amount_total": 12990,
      "currency": "brl",
      "description": "Plano Pro",
      "metadata": {},
      "position": 0,
      "price": "price_456",
      "price_data": null,
      "product": "prod_321",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 12990
    }
  ],
  "livemode": true,
  "metadata": {},
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "has_interest": true,
        "max_count": 12
      }
    }
  },
  "require_billing_address": false,
  "require_document": true,
  "require_phone": false,
  "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. 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 ch_live_...`	Cria para a própria organização da chave. O header `Organization` é proibido (400).
API key da plataforma (`platform_admin`)	`Authorization: Bearer ch_live_...` + `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

allow_discount_codes

boolean

default:"true"

Se o comprador pode inserir cupom no checkout.

cancel_url

string

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

discount_id

string

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

label

string

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

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[]

description

string

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

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

product_data

object

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

Show product_data

description

string

Descrição livre.

name

string

required

Nome do produto exibido no checkout.

product_id

string

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

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. Padrão 1.

unit_amount

integer

required

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

price_id

string

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

quantity

integer

Padrão 1. Inteiro >= 1.

metadata

object

Objeto chave-valor livre. Cada session gerada do link recebe esse metadata copiado.

payment_method_options

object

Opções por método de pagamento. Quando omitido, aplicam-se os padrões da organização.

Show Campos de payment_method_options

credit_card

object

Opções do cartão de crédito.

Show Campos de credit_card

installments

object

Configuração do parcelamento.

Show Campos de installments

has_interest

boolean

true quando o comprador paga o acréscimo do parcelamento; false quando o lojista absorve o acréscimo. Quando omitido, usa o padrão da organização.

max_count

integer

Número máximo de parcelas oferecidas (1–12). Quando omitido, usa o padrão da organização.

require_billing_address

boolean

Quando true, endereço de cobrança é obrigatório no checkout. Quando omitido, herda a política de checkout da organização. Boleto sempre exige.

require_document

boolean

Quando true, o documento (CPF/CNPJ) do comprador é obrigatório no checkout. Quando omitido, herda a política da organização (padrão true). Boleto sempre exige documento.

require_phone

boolean

Quando true, o telefone do comprador é obrigatório no checkout. Quando omitido, herda a política da organização (padrão false).

success_url

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. 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_123"
      }
    ]
  }'

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_123",
          "unit_amount": 12990
        }
      }
    ]
  }'

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

{
  "price_data": {
    "currency": "brl",
    "product_id": "prod_123",
    "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
        }
      }
    ]
  }'

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.

Resposta

200 OK com o objeto canônico do payment link.

string

Identificador, prefixo plink_.

object

string

Sempre payment_link.

allow_discount_codes

boolean

Se cupons são permitidos no checkout.

cancel_url

string

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

created_at

string

ISO 8601.

discount

string | null

ID do desconto auto-aplicado, ou null.

is_active

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.

label

string

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

line_items

array

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

livemode

boolean

Indica se o link foi criado em modo live.

metadata

object

Metadata configurada.

payment_method_options

object

Opções por método. credit_card.installments.has_interest (boolean) indica se o comprador paga o acréscimo do parcelamento; credit_card.installments.max_count (integer 1–12) é o número máximo de parcelas.

require_billing_address

boolean

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

require_document

boolean

Se o documento (CPF/CNPJ) é obrigatório. Boleto sempre exige.

require_phone

boolean

Se o telefone do comprador é obrigatório.

success_url

string

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

updated_at

string

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

url

string

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

{
  "id": "plink_demo_z2kkA78c1aCGhiEj",
  "object": "payment_link",
  "allow_discount_codes": true,
  "cancel_url": null,
  "created_at": "2026-05-02T18:31:00Z",
  "discount": null,
  "is_active": true,
  "label": "Bio do Instagram - Plano Pro",
  "line_items": [
    {
      "amount_discount": 0,
      "amount_subtotal": 12990,
      "amount_tax": 0,
      "amount_total": 12990,
      "currency": "brl",
      "description": "Plano Pro",
      "metadata": {},
      "position": 0,
      "price": "price_456",
      "price_data": null,
      "product": "prod_321",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 12990
    }
  ],
  "livemode": true,
  "metadata": {},
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "has_interest": true,
        "max_count": 12
      }
    }
  },
  "require_billing_address": false,
  "require_document": true,
  "require_phone": false,
  "success_url": "https://meusite.com/obrigado",
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

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`	O header `Organization` enviado com chave de organização (chave já trava na própria org).
`403`	Token de plataforma sem header `Organization`.
`403`	O header `Organization` aponta pra org que não é organização conectada ativa da 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 envelope Standard Webhooks ({ id, object: "event", created_at, data: { object }, livemode, organization, type }).

Get a Payment LinkRetorna um payment link pelo 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_123"
      }
    ]
  }'

{
  "id": "plink_demo_z2kkA78c1aCGhiEj",
  "object": "payment_link",
  "allow_discount_codes": true,
  "cancel_url": null,
  "created_at": "2026-05-02T18:31:00Z",
  "discount": null,
  "is_active": true,
  "label": "Bio do Instagram - Plano Pro",
  "line_items": [
    {
      "amount_discount": 0,
      "amount_subtotal": 12990,
      "amount_tax": 0,
      "amount_total": 12990,
      "currency": "brl",
      "description": "Plano Pro",
      "metadata": {},
      "position": 0,
      "price": "price_456",
      "price_data": null,
      "product": "prod_321",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 12990
    }
  ],
  "livemode": true,
  "metadata": {},
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "has_interest": true,
        "max_count": 12
      }
    }
  },
  "require_billing_address": false,
  "require_document": true,
  "require_phone": false,
  "success_url": "https://meusite.com/obrigado",
  "updated_at": null,
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

​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

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

​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

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

Resposta

Erros comuns

Webhooks