API documentation

Authentication

Use an API Key as Bearer token. create an account and generate a key with the required scopes. The token is shown only once.

Authorization: Bearer fdpx_xxxxxxxxxxxxxxxxxxxxxxxx

Missing scope returns 403 insufficient_scope. POST endpoints that move money require an Idempotency-Key header (unique string per request).

Create deposit (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.

Create withdrawal (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 (outbound)

Assine endpoints em sign up. 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 Webhook logs; trate os eventos de forma idempotente (dedupe por data.id + evento).

Register 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

Wallets + balance

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 / Chargebacks

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 — Payment links

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 }

Fees

Default platform fees (your account may have custom values — query GET /v1/api/fees):

The feeCents returned in each response reflects this fee schedule.

Per-transaction limits (deposit and withdrawal): R$ 2,00 – R$ 6.000,00. Out-of-range amounts return 400 invalid_amount.

Errors

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.