> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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](https://scaleup-c34c4386.mintlify.site/guides/parent-marketplace-suborganizations.md).

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

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

```bash cURL theme={null}
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"
    }
  }'
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const link = await chargefy.checkoutLinks.create({
  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

```json theme={null}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.