BANKARTEC Documentação v2.2
Integração externa: use sempre o header Apikey com seu Client ID. Crie credenciais em Credenciais API (até 10 chaves ativas por usuário). Documentação pública: https://app.dexspay.com/docs.php.
Introdução

Esta documentação descreve como integrar sistemas externos (e-commerce, ERP, app mobile, etc.) com a plataforma DEXSPAY.

Base URL: https://app.dexspay.com · Docs: https://app.dexspay.com/docs.php

Primeira integração (passo a passo)
  1. Faça login no painel e configure seu PIN (Configurações).
  2. Acesse Credenciais API → Nova Credencial (nome, domínio HTTPS, descrição).
  3. Guarde o Client ID e o Client Secret (exibido uma única vez).
  4. Em Credenciais API, cadastre o IP público do seu servidor (recomendado para saques).
  5. Teste depósito: POST /api/v1/generate-pix.php com header Apikey.
  6. Configure o campo postback com a URL do seu sistema para receber confirmação de pagamento.
  7. Teste saque: POST /api/v1/cashout.php (requer saldo e IP autorizado se whitelist configurada).
Pré-requisitos da conta
RequisitoOnde verificar
Conta ativa e logadaPainel principal
Documentos aprovadosNecessário para acessar Credenciais API
PIN de 6 dígitosConfigurações → criar/revogar credenciais
Cash-in ativoAdmin ou perfil (depósitos PIX)
Cash-out ativoAdmin ou perfil (saques PIX)
Adquirente PIX configuradaAdmin → usuário (Orus, AtivoPay, BullsPay, etc.)
Orus ativo (se adquirente ORUS)Admin → Adquirentes PIX → Orus
IPs na whitelistCredenciais API → IPs permitidos (obrigatório para saque, opcional para depósito)
Autenticação

Envie o Client ID em todas as requisições. O Client Secret não deve ser enviado nas chamadas — serve apenas para guardar com segurança no momento da criação.

Apikey: seu_client_id_aqui Content-Type: application/json

Múltiplas credenciais: crie uma chave por sistema (loja, ERP, homologação). Revogue chaves comprometidas sem afetar as demais.

Aliases de URL: /api/v1/cashin = generate-pix · /api/v1/cashout = cashout

Depósito PIX (gerar QR Code / copia e cola)

Cria cobrança PIX para seu cliente pagar. Valor mínimo: R$ 6,00. CPF válido obrigatório.

Adquirentes suportados na API: Orus (padrão em muitas contas), AtivoPay/Asaas e BullsPay. A adquirente usada é a configurada na conta dona da credencial Apikey (admin → usuário → Adquirente PIX).

POST https://app.dexspay.com/api/v1/generate-pix.php Headers: Content-Type: application/json Apikey: <client_id> Body (JSON): { "nome": "João Silva", "cpf": "111.111.111-11", "valor": "120.00", "descricao": "Pedido #1234", "postback": "https://seusite.com.br/webhook/pix" } Resposta 200 (Orus — contas com payment_pix = ORUS): { "success": true, "pix_code": "000201...", "pix": "000201...", "id": "ref_interna_abc", "internal_id": "ref_interna_abc", "transaction_id": "charge_orus_xyz", "value": "120.00", "status": "PENDING", "provider": "orus" } Resposta 200 (BullsPay / compatível): { "id": "eabc123...", "pix": "00020101021226...6304ABCD", "value": "120.00", "status": "PENDING" } Resposta 200 (AtivoPay / Asaas): { "success": true, "pix_code": "000201...", "transaction_id": "ext_abc", "internal_id": "eabc123...", "status": "PENDING", "provider": "ativopay" }

Guarde id ou internal_id retornado — é o mesmo valor enviado no postback. QR Code em pix ou pix_code.

Postback — confirmação de pagamento PIX
Obrigatório para integrações externas (ONIZPAY, e-commerce, ERP): sempre envie o campo postback ao criar o PIX. Sem ele, seu sistema não recebe aviso de pagamento confirmado.

Quando o PIX for confirmado (Orus, AtivoPay ou BullsPay), o DEXSPAY envia POST para a URL informada em postback.

POST https://seusite.com.br/webhook/pix Content-Type: application/json { "id": "ref_interna_abc", "value": "120.00", "status": "PAID" }
  • id — referência interna (id / internal_id retornados na criação)
  • value — valor bruto do depósito (string decimal, ex.: "120.00")
  • status — sempre PAID quando confirmado
  • Responda HTTP 200 em até ~10 segundos
  • Implemente idempotência — o postback pode ser reenviado
  • Funciona para depósitos via API com adquirente Orus (desde v2.2)
Integração white-label (ex.: ONIZPAY → DEXSPAY)

Quando outro sistema usa DEXSPAY como adquirente via API:

  1. Crie credencial API no DEXSPAY (ex.: ZIMPAY) e use o Client ID como Apikey.
  2. No sistema externo, chame POST /api/v1/generate-pix.php com campo postback apontando para o webhook do sistema externo.
  3. O admin do DEXSPAY deve manter cash-in ativo e adquirente PIX (ex.: Orus) configurada na conta dona da credencial.
  4. O admin do sistema externo configura adquirente “DEXSPAY” — isso só roteia para a API; a confirmação chega via postback, não por polling.

Erro comum: PIX pago e confirmado no DEXSPAY, mas sistema externo não atualiza → falta postback na criação ou endpoint externo não responde HTTP 200.

Saque BRL (Cash-out PIX)

Transfere saldo BRL da conta para uma chave PIX. Valor mínimo: R$ 5,00. Debita valor + taxas do saldo.

POST https://app.dexspay.com/api/v1/cashout.php Headers: Content-Type: application/json Apikey: <client_id> Body (JSON): { "nome": "João Silva", "cpf": "111.111.111-11", "key": "email@exemplo.com", "valor": "50.00", "descricao": "Saque pedido #99" } Resposta 200: { "statusCode": 200, "message": "Saque efetuado via ORUS, verifique em seu banco.", "transaction_id": "eabc...", "external_id": "orus_...", "acquirer_used": "ORUS", "debug_info": { "valor_solicitado": 50, "taxa_aplicada": 2.5, "total_debitado": 52.5, "saldo_antes": 1000, "saldo_depois": 947.5 } }

Chave PIX (key): CPF, CNPJ, e-mail, telefone (+55) ou chave aleatória (EVP).

Folha de pagamento

API REST autenticada com header Apikey (Client ID). Cada pagamento da folha vira uma transação oficial do DEXSPAY (PIX ou transferência). O status pago só muda após confirmação real do provedor.

Escopos: payroll:read, payroll:create, payroll:update, payroll:execute, payroll:cancel, payroll:recipients, payroll:reports. Credenciais sem scopes mantêm acesso total.

Criar folha
POST https://app.dexspay.com/api/v1/payrolls Headers: Content-Type: application/json Apikey: <client_id> { "name": "Folha mensal - Setembro", "default_amount": 3500.00, "payment_day": 5, "cycle": "monthly", "period_type": "12m", "payment_method": "PIX", "auto_debit": 1, "execution_time": "02:00", "recipients": [ { "recipient_id": 10, "amount": 3500.00 }, { "recipient_id": 11, "amount": 4200.00 } ] }
Adicionar destinatário · Agendar · Consultar · Executar · Pagamentos
POST /api/v1/payrolls/{id}/recipients POST /api/v1/payrolls/{id}/schedule GET /api/v1/payrolls/{id} POST /api/v1/payrolls/{id}/execute GET /api/v1/payrolls/{id}/payments GET /api/v1/payrolls/{id}/report
cURL
curl -X POST https://app.dexspay.com/api/v1/payrolls \ -H "Content-Type: application/json" \ -H "Apikey: SEU_CLIENT_ID" \ -d '{"name":"Folha mensal - Setembro","payment_day":5,"cycle":"monthly","payment_method":"PIX","auto_debit":1}'
PHP
$ch = curl_init('https://app.dexspay.com/api/v1/payrolls'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Apikey: SEU_CLIENT_ID'], CURLOPT_POSTFIELDS => json_encode(['name' => 'Folha mensal - Setembro', 'cycle' => 'monthly', 'payment_method' => 'PIX']), CURLOPT_RETURNTRANSFER => true, ]); echo curl_exec($ch);
JavaScript / Node.js
await fetch('https://app.dexspay.com/api/v1/payrolls', { method: 'POST', headers: { 'Content-Type': 'application/json', Apikey: 'SEU_CLIENT_ID' }, body: JSON.stringify({ name: 'Folha mensal - Setembro', cycle: 'monthly', payment_method: 'PIX' }) });
Python
import requests requests.post('https://app.dexspay.com/api/v1/payrolls', headers={'Apikey': 'SEU_CLIENT_ID'}, json={'name': 'Folha mensal - Setembro', 'cycle': 'monthly', 'payment_method': 'PIX'})

Webhooks HMAC (X-Bank-Signature: sha256=...): payroll.created, payroll.scheduled, payroll.processing, payroll.completed, payroll.failed, payroll.cancelled, payroll.paused, payroll.payment.paid e correlatos. O status financeiro acompanha a confirmação do provedor — não é marcado como pago só pelo envio da requisição.

Transferência em Lote

API REST autenticada com header Apikey. O lote é apenas o agrupador: cada item tem idempotency_key, status, tarifa snapshot e comprovante próprios. O status pago só muda após confirmação do provedor (webhook/consulta) — nunca só porque a API externa aceitou o envio.

Escopos: batch:read, batch:create, batch:update, batch:execute, batch:cancel, batch:import. Credenciais sem scopes mantêm acesso total.

Autenticação · Criar lote · Adicionar item
POST https://app.dexspay.com/api/v1/batches Headers: Content-Type: application/json Apikey: <client_id> { "name": "Folha Setembro 2026", "description": "Pagamento de funcionários e fornecedores", "transfer_type": "PIX" } POST /api/v1/batches/{id}/items { "name": "João Silva", "document": "12345678900", "tipo_chave": "CPF", "chave_pix": "12345678900", "amount": 500.00, "descricao": "Pagamento", "identificador": "001" }
Consultar · Validar · Confirmar · Agendar · Cancelar · Comprovante
GET /api/v1/batches GET /api/v1/batches/{id} PUT /api/v1/batches/{id} DELETE /api/v1/batches/{id} POST /api/v1/batches/{id}/validate POST /api/v1/batches/{id}/confirm POST /api/v1/batches/{id}/process POST /api/v1/batches/{id}/cancel POST /api/v1/batches/{id}/schedule GET /api/v1/batches/scheduled POST /api/v1/batches/{id}/unschedule GET /api/v1/batches/{id}/items GET /api/v1/batches/{id}/summary GET /api/v1/batches/{id}/receipt POST /api/v1/batches/import GET /api/v1/beneficiaries POST /api/v1/webhooks/transfers
Idempotência

Cada item recebe uma chave no formato BANK-BATCH-{id}-ITEM-.... Reenviar a mesma requisição não cria nova transferência.

Códigos de erro
BATCH_001 lote não encontrado BATCH_002 validação / regra de negócio BATCH_003 destinatário / assinatura TRANSFER_001 item não encontrado INSUFFICIENT_BALANCE INVALID_PIX_KEY INVALID_AMOUNT LIMIT_EXCEEDED DUPLICATE_TRANSFER PROVIDER_ERROR ANTIFRAUD_REVIEW
cURL
curl -X POST https://app.dexspay.com/api/v1/batches \ -H "Content-Type: application/json" \ -H "Apikey: SEU_CLIENT_ID" \ -d '{"name":"Folha Setembro 2026","transfer_type":"PIX"}'
PHP
$ch = curl_init('https://app.dexspay.com/api/v1/batches'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Apikey: SEU_CLIENT_ID'], CURLOPT_POSTFIELDS => json_encode(['name' => 'Folha Setembro 2026', 'transfer_type' => 'PIX']), CURLOPT_RETURNTRANSFER => true, ]); echo curl_exec($ch);
JavaScript / Node.js
await fetch('https://app.dexspay.com/api/v1/batches', { method: 'POST', headers: { 'Content-Type': 'application/json', Apikey: 'SEU_CLIENT_ID' }, body: JSON.stringify({ name: 'Folha Setembro 2026', transfer_type: 'PIX' }) });
Python
import requests requests.post('https://app.dexspay.com/api/v1/batches', headers={'Apikey': 'SEU_CLIENT_ID'}, json={'name': 'Folha Setembro 2026', 'transfer_type': 'PIX'})

Webhooks internos: transfer.created, transfer.processing, transfer.completed, transfer.failed, transfer.cancelled, transfer.reversed, batch.completed, batch.partial, batch.failed. Eventos do provedor entram em POST /api/v1/webhooks/transfers com validação de assinatura, timestamp e idempotência (event_id). Importação CSV/XLSX nunca dispara pagamento — só prévia e validação.

Tiers de Clientes

Camada de segmentação do cliente (regras, badge, benefícios, limites e vínculo com o Plano de Tarifas). Não altera transações já processadas. Header Apikey. Escopos: tier:read, tier:admin.

Consultar o próprio tier
GET https://app.dexspay.com/api/v1/customer/tier Headers: Apikey: <client_id>
Admin — Tiers e classificação
GET /api/v1/admin/tiers POST /api/v1/admin/tiers GET /api/v1/admin/tiers/{id} PUT /api/v1/admin/tiers/{id} DELETE /api/v1/admin/tiers/{id} PATCH /api/v1/admin/tiers/{id}/status GET /api/v1/admin/tiers/{id}/customers GET /api/v1/admin/tiers/statistics POST /api/v1/admin/customers/{id}/tier GET /api/v1/admin/customers/{id}/tier DELETE /api/v1/admin/customers/{id}/tier
Alterar classificação
{ "tier_id": 4, "mode": "manual", "reason": "Cliente empresarial" }
cURL
curl https://app.dexspay.com/api/v1/customer/tier -H "Apikey: SEU_CLIENT_ID"
PHP
$ch = curl_init('https://app.dexspay.com/api/v1/customer/tier'); curl_setopt_array($ch, [CURLOPT_HTTPHEADER => ['Apikey: SEU_CLIENT_ID'], CURLOPT_RETURNTRANSFER => true]); echo curl_exec($ch);
JavaScript / Node.js
await fetch('https://app.dexspay.com/api/v1/customer/tier', { headers: { Apikey: 'SEU_CLIENT_ID' } });
Python
import requests print(requests.get('https://app.dexspay.com/api/v1/customer/tier', headers={'Apikey': 'SEU_CLIENT_ID'}).json())

Webhooks: tier.created, tier.updated, tier.activated, tier.deactivated, customer.tier_changed, customer.tier_promoted, customer.tier_downgraded, customer.tier_fee_plan_changed. Códigos: TIER_001 não encontrado, TIER_002 validação, TIER_003 exclusão bloqueada. Novos critérios/benefícios entram no catálogo de campos sem reescrever o módulo.

Referral API (Indique e Ganhe)

Programa de indicação de nível único. O cadastro pelo link /cadastro?ref=CODIGO vincula o indicado ao indicador de forma permanente. A comissão só é criada após a operação original ser confirmada. O markup do indicador é cobrado além da tarifa-base do DEXSPAY e creditado no saldo oficial (tipo COMISSAO_INDICACAO) após o prazo de retenção.

Escopos: referral:read, referral:create, referral:markup, referral:earnings. Credenciais sem scopes mantêm acesso total. Header: Apikey.

Consultar código, link, resumo, indicados e ganhos
GET https://app.dexspay.com/api/v1/referrals GET https://app.dexspay.com/api/v1/referrals/code GET https://app.dexspay.com/api/v1/referrals/link GET https://app.dexspay.com/api/v1/referrals/summary GET https://app.dexspay.com/api/v1/referrals/users GET https://app.dexspay.com/api/v1/referrals/earnings GET https://app.dexspay.com/api/v1/referrals/earnings/{id} GET https://app.dexspay.com/api/v1/referrals/markup GET https://app.dexspay.com/api/v1/referrals/markup/limits PUT https://app.dexspay.com/api/v1/referrals/markup
Exemplo de markup
{ "cash_in": { "fixed": 0.50, "percentage": 0 }, "cash_out": { "fixed": 0, "percentage": 0.50 }, "boleto_paid": { "fixed": 1.00, "percentage": 0 } }

O backend valida obrigatoriamente os limites definidos pelo administrador. Markup negativo ou fora da faixa é recusado.

cURL
curl https://app.dexspay.com/api/v1/referrals/summary \ -H "Apikey: SEU_CLIENT_ID"
PHP
$ch = curl_init('https://app.dexspay.com/api/v1/referrals/link'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Apikey: SEU_CLIENT_ID'], CURLOPT_RETURNTRANSFER => true, ]); echo curl_exec($ch);
JavaScript / Node.js
const res = await fetch('https://app.dexspay.com/api/v1/referrals/markup', { method: 'PUT', headers: { 'Content-Type': 'application/json', Apikey: 'SEU_CLIENT_ID' }, body: JSON.stringify({ cash_in: { fixed: 0.5, percentage: 0 } }) });
Python
import requests print(requests.get('https://app.dexspay.com/api/v1/referrals/earnings', headers={'Apikey': 'SEU_CLIENT_ID'}).json())

Webhooks HMAC (X-Bank-Signature: sha256=...): referral.created, referral.activated, referral.earning.created, referral.earning.pending, referral.earning.available, referral.earning.reversed, referral.program.suspended.

USDT — Payin e Saque
Depósito USDT (PIX → USDT)
POST https://app.dexspay.com/api/v1/usdt-deposit-public.php Headers: Apikey: <client_id> Content-Type: multipart/form-data Campos: nome: "João" valor: "150.00" descricao: "Compra USDT" Resposta 200: { "success": true, "pix_code": "000201...", "quote_id": "qu_xxx", "transaction_id": 84, "status": "processing" }

Valor mínimo: R$ 60,00.

Saque USDT
POST https://app.dexspay.com/api/v1/withdraw-usdt-request.php Headers: Apikey: <client_id> Form-Data: chain: "TRON" to_address: "T..." amount: "12.5" memo: "" Resposta 200: { "success": true, "id": 123, "status": "PENDING" }

Saques USDT ficam PENDING até aprovação manual/admin.

Gas — PIX → token nativo

Mesmo fluxo do PIX → USDT: o usuário escolhe valor em BRL e a rede. Após o PIX, a hot wallet envia o gas nativo (POL, BNB, ETH ou xDAI) para a carteira destino.

Cotação
GET https://app.dexspay.com/api/v1/gas.php?action=quote&valor=100&network=POLYGON Headers: Apikey: <client_id> Resposta 200: { "success": true, "network": "POLYGON", "token": "POL", "rate": 3.12, "gas_estimated": 31.45, "network_fee_native": 0.05 }
Criar ordem (gera PIX)
POST https://app.dexspay.com/api/v1/gas.php Headers: Apikey: <client_id> Content-Type: application/json { "valor": "100.00", "network": "POLYGON", "wallet": "0x...", "nome": "Alex Silva", "cpf": "00000000000" } Resposta 200: { "success": true, "pix_code": "000201...", "uuid": "...", "transaction_id": "pixgas_...", "status": "pending", "gas_estimated": 31.45, "token": "POL" }
Consultar status
GET https://app.dexspay.com/api/v1/gas.php?id=<uuid> Headers: Apikey: <client_id>

Redes: POLYGON (POL), BSC (BNB), ETH (ETH), GNO (xDAI). A carteira destino, se omitida, usa a wallet da rede em Carteiras Crypto. Escopos: gas:create, gas:read ou gas:*.

Taxas
  • Cash-in (depósito): taxa descontada do valor creditado (percentual, fixa ou mista — configurável por usuário no admin).
  • Cash-out (saque): taxa adicionada ao valor debitado (ex.: sacar R$ 50 + taxa = débito maior).
  • Taxas individuais substituem as globais quando configuradas pelo administrador.
  • Consulte seu admin ou extrato no painel para valores exatos aplicados à sua conta.
Códigos de erro HTTP
HTTPSignificado comum
400Dados inválidos (CPF, valor mínimo, chave PIX, JSON malformado)
401Apikey não enviada (cashout)
403Client ID inválido/revogado, cash-in/out inativo, IP não autorizado
404Usuário não encontrado
405Método não permitido (use POST)
502Falha na adquirente/gateway PIX
503Gateway desativado, Orus inativo ou adquirente não suportada na API

Formato típico de erro: {"statusCode": 403, "message": "Client id inválido ou revogado."}

Exemplos cURL
Gerar PIX
curl -X POST 'https://app.dexspay.com/api/v1/generate-pix.php' \ -H 'Content-Type: application/json' \ -H 'Apikey: SEU_CLIENT_ID' \ -d '{ "nome": "João Silva", "cpf": "52998224725", "valor": "100.00", "descricao": "Pedido 1001", "postback": "https://seusite.com.br/webhook/pix" }'
Saque PIX
curl -X POST 'https://app.dexspay.com/api/v1/cashout.php' \ -H 'Content-Type: application/json' \ -H 'Apikey: SEU_CLIENT_ID' \ -d '{ "nome": "João Silva", "cpf": "52998224725", "key": "email@exemplo.com", "valor": "50.00", "descricao": "Saque API" }'
Qual API usar?
APIAuthUso
/api/v1/generate-pix.php
/api/v1/cashout.php
/api/v1/payrolls
/api/v1/gas.php
Apikey (Client ID) Integração externa — e-commerce, ERP, apps, folha de pagamento, compra de gas
/api/v1/pix/charge
/api/v1/pix/payment
Sessão (login painel) Uso interno no navegador — Swagger

Para integrar outro sistema, use somente os endpoints com autenticação Apikey.

Consulta de status: não há endpoint Apikey para polling. Use o postback como confirmação oficial. Guarde internal_id / id retornados na criação.

Boas práticas
  • O campo postback é obrigatório em produção — sem ele o pagamento confirma no DEXSPAY mas não no seu sistema.
  • Nunca exponha o Client Secret em frontend ou repositórios públicos.
  • Use HTTPS em postbacks e valide o campo id antes de liberar produto/serviço.
  • Implemente idempotência no postback (mesmo id + PAID não deve creditar duas vezes).
  • Cadastre IPs fixos do servidor em Credenciais API antes de ir para produção.
  • Retry com backoff exponencial em erros 502/503 (máx. 3–5 tentativas).
  • Homologação: crie credencial separada com sufixo no nome (ex.: ERP Homolog).
  • Guarde logs de transaction_id, id interno e respostas para suporte.