Livex — Manual de Integração para Parceiros (API)

Versão: 1.0 · Última atualização: 2026-07-29 Operado por: SPG Soluções Financeiras Ltda (CNPJ 63.237.011/0001-00) Liquidação/BaaS: Brasil Cash

Este manual descreve todas as funções disponíveis para integração via API. A plataforma expõe duas superfícies de API para parceiros:

Ambas as superfícies aceitam também o host https://pay.livex.global (o reverse-proxy encaminha /v1/* e /v1/baas/* para a API).

Índice

1. Conceitos gerais
2. Autenticação
3. Escopos (permissões)
4. Idempotência
5. Erros
6. Livex BaaS API - 6.1 Contas - 6.2 KYC / Documentos - 6.3 PIX (entrada / saída) - 6.4 Saldo e Extrato - 6.5 USDT (cripto)
7. LivexPay API (cobrança PIX)
8. Webhooks
9. Fluxos completos (receitas)
10. Ambientes e limites

1. Conceitos gerais

• Parceiro (Partner): sua empresa integradora. Possui uma API key BaaS (bpk_live_...).
• Conta (Account): conta bancária digital que você abre para o seu cliente final via API. Cada conta tem seu próprio saldo, KYC, chaves PIX e extrato.
• Merchant (LivexPay): identidade de cobrança para receber PIX em checkout. Possui uma API key LivexPay (lpk_live_...).
• Formato: todo request/response é JSON. Datas em ISO-8601 (UTC). Valores monetários em BRL decimal (amount_brl) exceto quando indicado em centavos.
• Toda resposta segue o padrão { "ok": true, ... } (sucesso) ou { "ok": false, "error": "...", "code": "..." } (erro).

2. Autenticação

2.1 BaaS API (/v1/baas)

Chave no formato bpk_live_xxxxxxxx (produção) ou bpk_test_... (teste). Envie em um dos formatos:

Authorization: Bearer bpk_live_xxxxxxxxxxxxxxxxxxxxxxxx

ou

x-api-key: bpk_live_xxxxxxxxxxxxxxxxxxxxxxxx

2.2 LivexPay API (/v1)

Chave no formato lpk_live_<prefixo8><segredo24>. Envie via header:

Authorization: Bearer lpk_live_AbCd1234XXXXXXXXXXXXXXXXXXXX

ou

x-api-key: lpk_live_AbCd1234XXXXXXXXXXXXXXXXXXXX

Segurança: as chaves são secretas. Guardamos apenas o hash do segredo — se você perder a chave, gere outra no painel. Nunca exponha a chave no front-end. Todo tráfego é HTTPS obrigatório.

3. Escopos (permissões)

Cada API key BaaS tem escopos que limitam o que ela pode fazer. Se faltar escopo, retorna 403 FORBIDDEN_SCOPE.

4. Idempotência

Operações que movimentam dinheiro (PIX out, USDT buy/sell) aceitam idempotência para evitar duplicidade em retries de rede.

• Envie um idempotency_key no corpo ou no header Idempotency-Key: <uuid>.
• Reenviar a mesma chave retorna a mesma operação (não duplica).
• Se você não enviar, o sistema gera uma automaticamente por request (não protege contra retry do seu lado).

Recomendado: gere um UUID por operação e reutilize-o em todos os retries daquela operação.

5. Erros

Formato padrão:

{ "ok": false, "error": "mensagem legível", "code": "CODIGO_MAQUINA" }

Em 400, o campo details traz a validação por campo:

{ "ok": false, "error": "invalid input", "details": { "fieldErrors": { "email": ["Invalid email"] } } }

6. Livex BaaS API

Base: https://api.livex.global/v1/baas

6.1 Contas

POST /accounts — Criar conta (abrir conta para seu cliente)

Escopo: accounts:write

Body:

{
  "external_id": "seu-id-interno-123",
  "person_type": "PF",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "document": "39053344705",
  "phone": "+5511999990000",
  "birth_date": "1990-01-01",
  "mother_name": "Joana Silva",
  "address": {
    "zip": "01310100", "street": "Av Paulista", "number": "1000",
    "complement": "sala 5", "neighborhood": "Bela Vista",
    "city": "São Paulo", "state": "SP"
  },
  "kyc": {
    "document_type": "cnh",
    "s3_key_front": "kyc/.../front.jpg",
    "s3_key_selfie": "kyc/.../selfie.jpg",
    "s3_key_address_proof": "kyc/.../addr.jpg"
  },
  "metadata": { "plano": "premium" }
}

Campos PJ (quando person_type = "PJ"): company_name, trade_name, founded_date, legal_rep_name, legal_rep_cpf (o document vira o CNPJ, name = razão social).

Resposta 201:

{ "ok": true, "account": { "id": "uuid", "external_id": "...", "status": "pending", "kyc_status": "pending", ... } }

• document: CPF (11) ou CNPJ (14 dígitos, sem máscara).
• external_id: seu identificador — devolvido em todos os webhooks para correlação.
• A conta nasce status: pending e precisa de KYC aprovado para operar PIX/USDT.

GET /accounts — Listar contas

Escopo: accounts:read · Query: ?limit=50&status=approved

GET /accounts/:id — Detalhe da conta

Escopo: accounts:read

GET /accounts/:id/kyc — Status do KYC

Escopo: accounts:read

{ "ok": true, "kyc": { "account_id": "uuid", "baas_status": "approved",
  "kyc_status": "approved", "reason": null, "reviewed_at": "2026-07-20T..." } }

6.2 KYC / Documentos

O envio de documentos usa presigned URL (upload direto ao storage seguro):

POST /accounts/:id/documents/presign — Gerar URL de upload

Escopo: accounts:write

{ "slot": "front", "mime_type": "image/jpeg", "content_length": 245123 }

• slot: front | back | selfie | address_proof
• Resposta traz url (PUT direto) + key (o s3_key_* que você passa no POST /accounts ou na atualização de KYC).

Fluxo de KYC: 1. presign para cada documento → faça o PUT do arquivo na URL retornada. 2. Crie a conta (ou informe as keys) com os s3_key_*. 3. A Livex processa biometria (face match + prova de vida + OCR) e valida na Brasil Cash. 4. Você recebe webhooks: kyc.received → kyc.approved / kyc.rejected / kyc.docs_requested.

6.3 PIX (entrada / saída)

POST /pix/in — Gerar cobrança PIX (receber na conta)

Escopo: pix:write

{ "account_id": "uuid-da-conta", "amount_brl": 150.00, "expiration_minutes": 60 }

Resposta 201: objeto charge com o QR code / copia-e-cola para o pagador. Quando pago, você recebe webhook pix.received.

POST /pix/out — Enviar PIX (pagar a partir da conta)

Escopo: pix:write

{
  "account_id": "uuid-da-conta",
  "amount_brl": 100.00,
  "pix_key": "destino@exemplo.com",
  "pix_key_type": "email",
  "beneficiary_name": "João Souza",
  "beneficiary_document": "12345678909",
  "description": "Pagamento pedido 123",
  "idempotency_key": "uuid-unico"
}

• pix_key_type: cpf | cnpj | email | phone | evp
• Requer saldo suficiente e KYC aprovado. Retorna payout com status.
• Webhooks: pix.sent → pix.completed (ou pix.refused / pix.refunded).

6.4 Saldo e Extrato

GET /accounts/:id/balance — Saldo

Escopo: pix:read

{ "ok": true, "balance": { "brl": "1500.00", "usdt": "0.000000" } }

GET /accounts/:id/transactions — Extrato

Escopo: pix:read · Query: ?limit=50&type=pix_in

GET /accounts/:id/transactions/:txId — Detalhe de uma transação

Escopo: pix:read

6.5 USDT (cripto)

GET /usdt/quote — Cotação atual

Escopo: usdt:read

POST /usdt/buy — Comprar USDT (debita BRL da conta)

Escopo: usdt:write

{ "account_id": "uuid", "amount_brl": 500.00, "idempotency_key": "uuid" }

POST /usdt/sell — Vender USDT (credita BRL na conta)

Escopo: usdt:write

{ "account_id": "uuid", "amount_usdt": 100.00, "idempotency_key": "uuid" }

GET /accounts/:id/orders — Listar ordens · Escopo: usdt:read

GET /accounts/:id/orders/:orderId — Detalhe da ordem · Escopo: usdt:read

Webhooks: usdt.bought / usdt.sold / order.completed / order.cancelled.

7. LivexPay API (cobrança PIX)

Base: https://api.livex.global/v1 · Auth: chave lpk_live_...

Use quando você só precisa receber pagamentos PIX (checkout / e-commerce), sem abrir contas.

POST /charges — Criar cobrança

{
  "amount_brl": 99.90,
  "description": "Pedido #4821",
  "merchant_order_id": "4821",
  "idempotency_key": "uuid-unico",
  "expires_in_seconds": 3600
}

• expires_in_seconds: 60 a 86400 (default 3600).
• Resposta 201: charge com id, status, pix_copia_e_cola (EMV) e pix_qr_base64 (imagem QR pronta para exibir).

GET /charges/:id — Consultar status da cobrança

status: pending | paid | expired | cancelled | refunded

GET /charges — Listar cobranças

Query: ?limit=50&status=paid

Quando o cliente paga, você recebe webhook charge.paid.

8. Webhooks

Você cadastra uma ou mais URLs de webhook no painel (com um secret por endpoint). A Livex faz POST JSON no seu endpoint a cada evento, com retry automático.

8.1 Verificação de assinatura (obrigatório)

Cada entrega inclui headers. Valide a assinatura HMAC-SHA256 do corpo cru (raw body) usando o secret do endpoint:

BaaS (/v1/baas): | Header | Conteúdo | |---|---| | X-Livex-Signature | HMAC-SHA256(secret, rawBody) em hex | | X-Livex-Event | tipo do evento (ex: pix.received) | | X-Livex-Event-Id | id único do evento (use para idempotência do seu lado) | | X-Livex-Delivery-Attempt | número da tentativa |

LivexPay (/v1): | Header | Conteúdo | |---|---| | X-Livexpay-Signature | HMAC-SHA256(secret, rawBody) em hex | | X-Livexpay-Event | charge.paid |

Exemplo de verificação (Node.js):

const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Responda HTTP 2xx rápido (idealmente < 5s). Se falhar, reenviamos com backoff. Trate eventos como idempotentes pelo X-Livex-Event-Id.

8.2 Eventos disponíveis

Contas / KYC: - account.created — conta criada - kyc.received — documentos recebidos, em análise - kyc.approved — KYC aprovado (conta pode operar) - kyc.rejected — KYC reprovado (veja reason) - kyc.docs_requested — documentos adicionais necessários - account.blocked / account.unblocked — conta bloqueada/desbloqueada

PIX: - pix.received — PIX de entrada confirmado (cobrança paga) - pix.sent — PIX de saída enviado - pix.completed — PIX de saída liquidado - pix.refused — PIX recusado - pix.refunded — PIX devolvido

USDT / ordens: - usdt.bought / usdt.sold - order.completed / order.cancelled

Saldo: - balance.changed — saldo da conta mudou

LivexPay: - charge.paid — cobrança paga

8.3 Payload (exemplo)

{
  "id": "evt_uuid",
  "type": "pix.received",
  "created_at": "2026-07-29T17:00:00Z",
  "data": {
    "account_id": "uuid",
    "external_id": "seu-id-interno-123",
    "transaction_id": "uuid",
    "amount_brl": "150.00",
    "status": "completed"
  }
}

9. Fluxos completos (receitas)

9.1 Onboarding de cliente final (PF) com PIX

1. POST /accounts/:id/documents/presign (front, selfie, address_proof) → PUT cada arquivo.
2. POST /accounts com person_type: PF, dados + s3_key_*.
3. Aguardar webhook kyc.approved.
4. POST /pix/in para gerar cobrança → mostrar QR ao cliente.
5. Receber webhook pix.received → creditado no saldo.
6. POST /pix/out para o cliente sacar/pagar.

9.2 Checkout simples (só receber PIX) — LivexPay

1. POST /v1/charges com amount_brl + merchant_order_id.
2. Exibir pix_qr_base64 / pix_copia_e_cola no checkout.
3. Receber webhook charge.paid → liberar o pedido.
4. (Opcional) GET /v1/charges/:id para polling de status.

9.3 Câmbio cripto (BRL ⇄ USDT)

1. Conta com KYC aprovado e saldo BRL.
2. GET /usdt/quote → mostrar cotação.
3. POST /usdt/buy (BRL→USDT) ou POST /usdt/sell (USDT→BRL) com idempotency_key.
4. Webhook usdt.bought / usdt.sold.

10. Ambientes e limites

• Produção: chaves bpk_live_ / lpk_live_. Movimenta dinheiro real.
• Teste: chaves bpk_test_ / lpk_test_. Não movimenta valores reais.
• Rate limit: aplicado por chave. Ao receber 429, aguarde e respeite Retry-After. Prefira lotes maiores a muitas chamadas pequenas.
• KYC obrigatório: contas só operam PIX/USDT após kyc.approved.
• HTTPS obrigatório em todas as chamadas.

Suporte

Para credenciais de produção, allowlist de IP de webhook, ou dúvidas de integração, fale com o time Livex. A referência viva dos endpoints está em https://pay.livex.global/api/baas-docs.

© SPG Soluções Financeiras Ltda — Livex. Documento técnico de integração.