Criar cobrança PIX
POST
{{base_url}}/api/charges
Autenticação
Bearer pela sua API Key real (vk_live_* produção, vk_test_* sandbox). Crie a chave em https://app.dotfy.com.br/dashboard/chaves-api. Sem o header → 401. Com chave inválida/revogada → 401. Com chave sem o escopo necessário → 403 insufficient_scope.Criar cobrança PIX
charges:writePré-requisito: KYC aprovado.
Rate limit: 30 req/min por usuário.
Body
| 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, BCB modalidadeAlteracao=1) — disponível apenas para sellers no adquirente 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 (1h). |
customer.name | string | não | 2-100 chars. |
customer.taxID | string | não | CPF (11 dígitos) ou CNPJ (14 dígitos). Apenas números. |
customer.email | string | não | Email válido. |
customer.phone | string | não | Formato E.164 (ex: +5511999998888). |
webhook_url | string | não | URL HTTPS para receber webhook desta cobrança específica (sobrescreve endpoints estáticos). |
split | array | não | Até 10 destinatários. Cada item: { email, type: 'PERCENT'|'FIXED', value }. PERCENT 0.01–100. FIXED em centavos. Soma dos PERCENT ≤ 100. Não pode incluir o próprio email. |
correlationIDnão é aceito como entrada. O ID é gerado pelo Dotfy e retornado na resposta. Isso garante unicidade entre adquirentes (Woovi/Treeal/Asaas/Simpay).
Resposta
200 OK com { success: true, data: { id, chargeId, correlationID, transactionID, qrCode, qrCodeImage, paymentLink, expiresAt, value, splits? } }.id — cuid interno do Dotfy.chargeId — id da cobrança no adquirente upstream.correlationID — gerado pelo Dotfy (ex: dotfy-1714000000000-abc12345). Use este em GET /api/charges/{correlationID} e como chave de deduplicação.qrCode — BR Code copia-e-cola (começa com 00020).qrCodeImage — geralmente data URL data:image/png;base64,... (pode ser URL absoluta dependendo do adquirente).value em centavos.splits — array só presente se você passou split no body.Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff '{{base_url}}/api/charges' \
--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",
"split": [
{ "email": "parceiro@exemplo.com", "type": "PERCENT", "value": 10 }
]
}'Response Response Example
200 - Sucesso (200) — cobrança criada
{
"success": true,
"data": {
"id": "clcharge0001",
"chargeId": "woovi_charge_a1b2c3",
"correlationID": "dotfy-1714000000000-abc12345",
"transactionID": "E18236120202605071430s00abc12345",
"qrCode": "00020126360014BR.GOV.BCB.PIX0114+5511999998888...",
"qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"paymentLink": "https://app.dotfy.com.br/checkout/dotfy-1714000000000-abc12345",
"expiresAt": "2026-05-07T15:30:00.000Z",
"value": 2990
}
}Modificado em 2026-05-07 16:12:35