Criar cobrança da subconta

Operação delegada (white-label)

Cria uma cobrança PIX em nome da subconta {{subaccount_id}}. A requisição é autenticada pela API Key do master (você), nunca por credencial da subconta.

Escopo: subaccounts:write
Pré-requisito: flag whiteLabelEnabled no master (sem ela todas as rotas /api/subaccounts/* respondem 404 — invisíveis).

Gates aplicados sobre a SUBCONTA

Os mesmos gates de POST /api/charges rodam, mas sobre a subconta (não sobre o master):

KYC da subconta deve estar APPROVED — senão 403 com requiresKyc: true. (KYC_PENDING na prática se manifesta aqui.)

Limite maxChargeAmount da subconta (se configurado).

Recursos desabilitados / pré-flight do adquirente (ex: PIX dinâmico só Treeal).

Body (idêntico a `POST /api/charges`)

Campo	Tipo	Obrigatório	Descrição
`value`	number	recomendado	Valor em REAIS (ex: `29.90`). Mín 0, máx 1.000.000. Se omitido ou `0` → cobrança com valor definido pelo pagador (PIX dinâmico, só Treeal).
`description`	string	não	Máx 255 chars. Aparece para o pagador.
`expiresIn`	int	não	Segundos até expirar. Mín 60, máx 86400 (24h). Default: 3600.
`customer.name`	string	não	2–100 chars.
`customer.taxID`	string	não	CPF (11 díg.) ou CNPJ (14 díg.). Apenas números. Aceita variações (`cpf`, `cnpj`, `document`...).
`customer.email`	string	não	Email válido.
`customer.phone`	string	não	E.164 (ex: `+5511999998888`).
`webhook_url`	string	não	URL HTTPS para esta cobrança específica.
`split`	array	não	Até 10 destinatários. PERCENT 0.01–100, FIXED em centavos.

correlationID não é aceito como entrada — o Dotfy gera e retorna na resposta.

Resposta `200 OK`

{ success: true, data: { id, chargeId, correlationID, correlationId, transactionID, qrCode, qrCodeImage, paymentLink, expiresAt, value, splits? } }

value retornado em CENTAVOS.

correlationID/correlationId — mesmo conteúdo (alias). Use em GET .../charges/{id}.

Sigilo (crítico): a resposta expõe apenas a taxa cheia (gatewayFee nas listagens/detalhe). A comissão do master e a decomposição taxa-base NUNCA aparecem aqui — são assunto exclusivo do extrato do próprio master.

Códigos de erro

Código HTTP	Quando
`400`	Body inválido (Zod). Ex: `value` negativo.
`401`	API Key ausente/inválida.
`403`	KYC da subconta não aprovado (`KYC_PENDING`) → `{ requiresKyc: true, kycStatus }`.
`404`	Master sem `whiteLabelEnabled`, subconta inexistente ou não pertence a você (anti-IDOR).
`429`	Rate limit de cobranças (por subconta).

Exemplo cURL

Rate limit: 100/min por subconta (429 ao exceder).

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

curl --location --globoff '/api/subaccounts/{{subaccount_id}}/charges' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "value": 29.90, "description": "Pedido #1234 - Plano Pro", "expiresIn": 3600, "customer": { "name": "Maria Silva", "taxID": "12345678901", "email": "maria@exemplo.com", "phone": "+5511999998888" }, "webhook_url": "https://seu-dominio.com/webhooks/dotfy" }'

{ "success": true, "data": { "id": "clsubcharge0001", "chargeId": "treeal_charge_a1b2c3", "correlationID": "dotfyt1714000000000abc12345", "correlationId": "dotfyt1714000000000abc12345", "transactionID": "E18236120202605071430s00abc12345", "qrCode": "00020126360014BR.GOV.BCB.PIX0114...", "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "paymentLink": "https://app.dotfy.com.br/checkout/clsubcharge0001", "expiresAt": "2026-05-07T15:30:00.000Z", "value": 2990 } }

Operação delegada (white-label)

Gates aplicados sobre a SUBCONTA

Body (idêntico a `POST /api/charges`)

Resposta `200 OK`

Códigos de erro

Exemplo cURL

Requisição

Respostas

Criar cobrança da subconta

Operação delegada (white-label)#

Gates aplicados sobre a SUBCONTA#

Body (idêntico a POST /api/charges)#

Resposta 200 OK#

Códigos de erro#

Exemplo cURL#

Requisição

Respostas

Operação delegada (white-label)

Gates aplicados sobre a SUBCONTA

Body (idêntico a `POST /api/charges`)

Resposta `200 OK`

Códigos de erro

Exemplo cURL