Documentação da API

Autenticação

Use uma API Key como Bearer token. crie uma conta e gere uma chave com os escopos necessários. O token é exibido uma única vez.

Authorization: Bearer fdpx_xxxxxxxxxxxxxxxxxxxxxxxx

Sem o escopo necessário retorna 403 insufficient_scope. Endpoints POST que movem dinheiro exigem o header Idempotency-Key (uma string única por requisição).

Criar depósito (PIX → DePix)

Escopo deposit:create. Não-custodial: o DePix vai direto para o seu endereço Liquid; a taxa da plataforma é recolhida via split da Eulen.

// request  (Idempotency-Key: <único>)
{
  "amountCents": 5000,        // R$50,00 que o recebedor quer
  "taxId": "12345678900",     // CPF/CNPJ do pagador (obrigatório)
  "walletId": "…",            // opcional; usa a carteira padrão
  "passFeesToPayer": true     // padrão: pagador cobre a taxa
}

// 201 response
{
  "id": "ckv…",
  "status": "PENDING",
  "amountCents": 5000,
  "feeCents": 199,            // sua taxa configurada (ex.)
  "totalCents": 5199,         // o que o pagador paga
  "pixQrCode": "0002…",       // copia e cola (EMV)
  "pixQrImage": "https://…png"
}

Escopo read:transactions. Status: PENDING → CONFIRMED. Falha: FAILED. REFUNDED = MED (estorno PIX), pode ocorrer mesmo após confirmado.

Criar saque (DePix → PIX)

Escopo withdrawal:create.

// request  (Idempotency-Key: <único>)
{
  "amountCents": 10000,        // R$100,00 recebidos via PIX
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",       // CPF | CNPJ | EMAIL | PHONE | EVP
  "taxId": "12345678900"
}

// response — envie DePix para depositAddress
{
  "id": "ckv…",
  "status": "PENDING",
  "amountCents": 10000,
  "feeCents": 100,
  "depositAddress": "lq1…",    // envie DePix aqui
  "depositAmountCents": 10123  // este tanto de DePix (inclui taxa do provedor)
}

Status: PENDING → PROCESSING → COMPLETED. Falha: FAILED / EXPIRED.

Webhooks (saída)

Assine endpoints em cadastre-se. Em cada evento terminal enviamos um POST assinado:

// body
{ "event": "deposit.confirmed", "data": { "id": "ckv…", … } }

// headers
X-Webhook-Event: deposit.confirmed
X-Webhook-Signature: sha256=<HMAC-SHA256 do corpo, com o secret do endpoint>

Eventos: deposit.confirmed, deposit.refunded, deposit.failed, withdrawal.completed, withdrawal.failed. Verifique recomputando o HMAC sobre o corpo cru. Entregas são registradas em Logs de webhook; trate os eventos de forma idempotente (dedupe por data.id + evento).

Registrar webhook (API)

Escopo webhook:manage. Registre a URL que receberá os eventos — o secret retornado assina cada entrega (guarde-o).

// request
{ "url": "https://seu-servidor.com/webhooks/flipdepix" }

// 201 response
{ "id": "ckv…", "url": "https://…", "secret": "whsec_…" }  // secret exibido só aqui

Carteiras + saldo

O DePix cai na sua carteira Liquid — cadastre ao menos uma (padrão) antes de criar depósitos.

// POST /v1/api/wallets  (wallets:write)
{ "liquidAddress": "lq1…", "label": "Principal", "makeDefault": true }

MEDs / Estornos

Lista os estornos (depósitos revertidos) da sua conta. Cada item traz tipo: estorno (pago por CPF/CNPJ diferente do informado — titularidade divergente) ou med (pago com o CPF informado e ainda revertido — possível contestação, o caso de risco). Cruze pelo depositId com a sua ordem.

// GET /v1/api/meds  (read:transactions)
{ "alerts": [
  { "id": "…", "depositId": "cmr…", "providerRef": "019f…", "blockchainTxId": "…",
    "tipo": "estorno" | "med", "cpfDivergente": true,
    "amountCents": 2599, "payerName": "FULANO",
    "cpfReal": "12345678900", "cpfRequisitado": "99999999999",
    "status": "PENDING", "deadline": "…", "createdAt": "…" } ] }

Checkout — Links de pagamento

Crie links de cobrança PIX por API. A página pública de pagamento fica em https://flipdepix.net/pay/{slug}. A taxa é absorvida por você (recebedor) — o pagador paga o valor cheio. amountCents entre R$ 2,00 e R$ 6.000,00; omita para valor aberto (o pagador escolhe). Requer o escopo links:manage.

// POST /v1/api/payment-links  (links:manage)
{ "title": "Mensal", "description": "Plano mensal", "amountCents": 2599 }
// → 201 { "id", "slug": "ab12cd34", "amountCents": 2599, "active": true, ... }
// Link público: https://flipdepix.net/pay/ab12cd34

// PATCH /v1/api/payment-links/{id}  → ativar / desativar
{ "active": false }

Taxas

Taxas padrão da plataforma (sua conta pode ter valores personalizados — consulte GET /v1/api/fees):

O feeCents retornado em cada resposta reflete essa taxa.

Limites por transação (depósito e saque): R$ 2,00 – R$ 6.000,00. Fora da faixa retorna 400 invalid_amount.

Erros

Toda resposta de erro tem o formato { "error": "<código>", "message": "<texto>" }. Trate por error (estável); o message pode ser exibido ao usuário.