POST /api/v1/checkout-links/

Cria um novo link de checkout compartilhável

Cria um link de checkout que pode ser compartilhado com clientes. Ao acessar o link, uma sessão de checkout é criada automaticamente.

​

Autenticação

Requer Organization Access Token (OAT) via header Authorization: Bearer.

​

Organização pai (marketplace) e produto da sub-organização

Se o token é da organização pai e existe relação direta em organization_relationships com a org dona do produto, você pode criar o link sem usar o OAT do filho. O corpo usa product_id e product_price_id do produto da sub-organização; a organization_id persistida no link será a do produto (filho).

curl -s -X POST "https://api.chargefy.io/api/v1/checkout-links" \
  -H "Authorization: Bearer $PARENT_OAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"product_id\": \"<UUID_PRODUTO_SUB_ORG>\",
    \"product_price_id\": \"<UUID_PRECO>\",
    \"success_url\": \"https://meusite.com/obrigado\",
    \"custom_price_amount\": null
  }"

Mais cenários (listagem agregada, CSV, clientes) em Marketplace: OAT da organização pai e sub-organizações.

​

Corpo da Requisição

Use produto único (campos product_id + product_price_id) ou múltiplos produtos (campo products) — apenas um dos dois formatos deve ser enviado.

​

Produto único

product_id · string · required

ID do produto a ser associado ao link.

product_price_id · string · required

ID do preço do produto.

​

Múltiplos produtos

products · array

Lista de produtos e preços. Use no lugar de product_id + product_price_id quando quiser associar mais de um produto ao link.

Show products[]

product_id · string · required

ID do produto.

product_price_id · string · required

ID do preço do produto.

​

Campos comuns

organization_id · string

Sessão de usuário: obrigatório para definir a organização do link.

OAT: opcional — a organização é inferida automaticamente do produto.

success_url · string

URL de redirecionamento após pagamento bem-sucedido.

cancel_url · string

URL de redirecionamento quando o comprador abandona ou cancela o checkout gerado por este link.

label · string

Nome identificador do link (visível apenas para a organização).

allow_discount_codes · boolean · default: "false"

Permite que o comprador insira cupons de desconto no checkout.

discount_id · string

ID de um desconto a ser aplicado automaticamente ao checkout criado a partir deste link.

require_billing_address · boolean · default: "false"

Quando true, torna o endereço de cobrança obrigatório durante o checkout.

no_fees_installments · boolean · default: "false"

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

custom_price_amount · number

Valor personalizado em centavos (ex: 4990 para R$ 49,90). Quando definido, substitui o preço padrão do produto para todos os checkouts gerados por este link.

payment_processor · string

Identificador do processador de pagamento (valor conforme contrato da API no ambiente).

recurrence_billing · string

Estratégia de cobrança recorrente para produtos com assinatura. Valores: zoop (padrão — cobrança automática via plano no gateway) ou manual (Chargefy gerencia as renovações). Se omitido, assume zoop.

metadata · object

Metadados personalizados em formato chave-valor. São mesclados nos metadados de cada checkout criado via este link.

​

Resposta

Retorna 201 Created com o objeto completo do checkout link criado.

id · string

ID único do checkout link.

url · string

URL compartilhável do checkout link.

client_secret · string

Segredo para acesso ao endpoint público de redirecionamento.

products · array

Lista de produtos associados ao link.

allow_discount_codes · boolean

Se cupons de desconto são permitidos.

discount_id · string

ID do desconto configurado (se houver).

success_url · string

URL de sucesso configurada.

require_billing_address · boolean

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

no_fees_installments · boolean

Se parcelas são oferecidas sem juros.

custom_price_amount · number

Valor personalizado em centavos (se configurado).

metadata · object

Metadados configurados.

organization_id · string

ID da organização dona do link.

payment_processor · string

Processador de pagamento.

created_at · string

Data/hora de criação no formato ISO 8601.

​

Exemplo

cURL

curl -X POST https://api.chargefy.io/api/v1/checkout-links/ \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_123",
    "product_price_id": "price_abc",
    "label": "Link Plano Pro - Campanha Março",
    "discount_id": "disc_abc",
    "success_url": "https://meusite.com/obrigado",
    "no_fees_installments": true,
    "metadata": {
      "source": "email-marketing"
    }
  }'

​

Resposta de Exemplo

{
  "id": "clink_def456",
  "label": "Link Plano Pro - Campanha Março",
  "url": "https://pay.chargefy.io/clink_def456",
  "client_secret": "cs_live_abc123",
  "products": [
    {
      "id": "prod_123",
      "name": "Plano Pro",
      "description": null,
      "organization_id": "org_xyz",
      "is_archived": false
    }
  ],
  "discount_id": "disc_abc",
  "allow_discount_codes": false,
  "success_url": "https://meusite.com/obrigado",
  "require_billing_address": false,
  "no_fees_installments": true,
  "custom_price_amount": null,
  "metadata": {
    "source": "email-marketing"
  },
  "organization_id": "org_xyz",
  "payment_processor": "default",
  "created_at": "2026-03-12T10:00:00Z"
}