Uma chave. Todos os trilhos.

1 Visão geral

A WantsPay é uma camada única de infraestrutura financeira: uma integração dá acesso a um catálogo completo de serviços financeiros e de compliance. Todos os valores em reais trafegam em centavos (amount_cents); quantidades de cripto e moedas estrangeiras são strings decimais.

2 Autenticação

Toda requisição autenticada envia a sua chave no header X-API-Key. Requisições com corpo usam Content-Type: application/json. Uma chave só acessa os serviços aprovados para ela (ver Escopos).

curl --fail-with-body https://api.wantspay.pro/keys/me \
  -H "X-API-Key: $WANTSPAY_API_KEY"

Verificar a chave, os escopos e o saldo

{
  "key_id": "key_9f2e…",
  "env": "live",
  "account_type": "business",
  "scopes": ["cashout.pix", "payout.pix"],
  "scopes_pending": ["swift.payout", "onramp.buy"],
  "partner_fee_bps": 0,
  "webhook_url": null,
  "limits": { "cashout_max_brl_cents": 5000000 }
}

3 Ambientes & chaves

Existe um ambiente de sandbox (determinístico, sem dinheiro real) e o de produção. Distinga-os pelo prefixo da chave e mantenha-os totalmente separados.

Criar chave de sandbox

curl --fail-with-body https://api.wantspay.pro/keys/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"name":"Minha integração de teste"}'

Criar chave de produção

curl --fail-with-body https://api.wantspay.pro/keys \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"Integração de produção",
    "email":"operacao@suaempresa.com",
    "account_type":"business"
  }'

A resposta traz api_key, scopes (os já aprovados), limits e uma monitor_url (painel privado de acompanhamento, somente leitura). Guarde a api_key como WANTSPAY_API_KEY no ambiente do servidor.

4 Escopos & aprovação de serviços

Cada chave carrega um conjunto de escopos — os serviços que a WantsPay aprovou para aquele cliente. Uma chamada a um serviço não aprovado responde 403 com erro: "scope_nao_aprovado".

Solicitar um serviço adicional

{
  "scopes": ["swift.payout", "onramp.buy"],
  "note": "Vamos oferecer remessa internacional aos nossos clientes PJ."
}

Enquanto um escopo está em análise ele aparece em scopes_pending. Você pode acompanhar por GET /keys/me ou receber o evento key.scope_approved por webhook. A aprovação final é da WantsPay e pode exigir documentação adicional do cliente.

5 Comece agora

Do zero à primeira liquidação em quatro passos — usando o serviço-base (cash-out cripto → PIX).

curl --fail-with-body https://api.wantspay.pro/cashout/preview \
  -H "X-API-Key: $WANTSPAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "asset":"USDT", "network":"polygon", "amount":"100.00", "pix_key":"cliente@example.com" }'

6 Cash-out · cripto → PIX cashout.pix

O serviço-base da WantsPay: alguém envia cripto de uma carteira externa e você paga em PIX. O fluxo tem três passos — cotar, aceitar (recebe o endereço de depósito) e acompanhar.

{
  "asset": "USDT",
  "network": "polygon",
  "amount": "100.00",
  "pix_key": "recebedor@example.com",
  "pix_key_type": "email",
  "customer_ref": "cliente-42",
  "external_id": "cashout-001"
}

Ciclo de estados

Estados terminais: COMPLETED, MANUAL_REVIEW, REFUNDING_CRYPTO, REFUNDED, EXPIRED, FAILED. Estimativa sem criar ordem: POST /cashout/preview.

7 Payouts · PIX via API payout.pix

Envie PIX direto a partir do saldo em custódia — sem intermediar cripto. Requer saldo suficiente (valor + taxas).

{
  "amount_cents": 5000,
  "pix_key": "recebedor@example.com",
  "pix_key_type": "email",
  "tax_number": "00000000191",
  "customer_ref": "cliente-42",
  "external_id": "saque-pix-cliente42-001"
}

Estados: processing → sent / failed / refunded. Quando disponível, o comprovante traz e2e, paid_at, receiver_name e verify_url. Dica: valide o titular da chave antes com POST /data/pix-key.

8 Cash-in · PIX → cripto / custódia cashin.crypto

Uma única cobrança (POST /cashin/charge) atende dois destinos, controlados pelo campo destino:

{
  "amount_cents": 10000,
  "payer_tax_number": "00000000191",
  "destino": "cripto",
  "asset": "usdt",
  "chain": "polygon",
  "payout_address": "0x1111111111111111111111111111111111111111",
  "external_id": "compra-cripto-001"
}

A resposta traz cashin_id, qr_copypaste, qr_image_url e expires_at. Gerar o QR confirma a criação — não o recebimento.

Acompanhar o status

9 SWIFT · cripto → 20+ moedas swift.payout

Receba cripto e liquide uma transferência internacional na conta bancária do beneficiário, em mais de 20 moedas. O fluxo espelha o cash-out: cotar → aceitar → depositar → acompanhar.

O catálogo de moedas é dinâmico. Exemplos suportados: USD EUR GBP CHF JPY CAD AUD CNY HKD SGD AED MXN ZAR SEK NOK DKK PLN TRY INR NZD ILS …

{
  "asset": "USDT",
  "network": "ethereum",
  "currency": "EUR",
  "amount_fiat": "2500.00",
  "beneficiary": {
    "name": "Acme GmbH",
    "type": "business",
    "country": "DE",
    "address": "Friedrichstrasse 100, Berlin"
  },
  "bank": {
    "swift_bic": "DEUTDEFFXXX",
    "iban": "DE89370400440532013000"
  },
  "purpose_code": "GDDS",
  "external_id": "swift-eur-001"
}

Ciclo de estados

10 Compra de cripto · on-ramp onramp.buy

Compra de criptoativos com KYC/KYB obrigatório, política amplamente descritiva e trava de segurança de 24 horas antes de qualquer saída — proteção contra fraude e conta-laranja.

{
  "amount_cents": 200000,
  "pay_with": "pix",
  "asset": "USDT",
  "network": "polygon",
  "customer_ref": "cliente-42",
  "payout_address": "0x1111111111111111111111111111111111111111",
  "external_id": "onramp-001"
}

{
  "order_id": "onr_9f2e…",
  "status": "LOCKED_24H",
  "asset": "USDT",
  "crypto_amount": "366.20",
  "locked_at": "2026-09-30T14:00:00Z",
  "unlock_at": "2026-10-01T14:00:00Z",
  "kyc_status": "approved"
}

Ciclo de estados

A trava de 24h é contada a partir de locked_at. Enquanto status=LOCKED_24H, exiba ao cliente a data/hora de unlock_at — não é erro. A liberação pode ser automática (em unlock_at) ou manual via POST /onramp/orders/{id}/release quando RELEASABLE.

11 Custódia BRL & saldo custody.brl

O saldo em reais fica organizado por subconta (customer_ref) sobre a "casa". Consulte, extraia, transfira entre subcontas e saque como cripto ou PIX.

12 Boletos boleto.issue

Emita boletos bancários registrados e concilie o pagamento pela mesma API. O crédito cai na custódia em reais (ou dispara o webhook para o seu fluxo).

{
  "amount_cents": 15000,
  "due_date": "2026-10-15",
  "payer": {
    "name": "João da Silva",
    "tax_number": "00000000191"
  },
  "instructions": "Não receber após o vencimento.",
  "customer_ref": "cliente-42",
  "external_id": "boleto-001"
}

A resposta traz boleto_id, linha_digitavel, barcode, pdf_url e expires_at. Estados: registered → paid / expired / canceled. Pagamento confirmado dispara boleto.paid.

13 KYC · verificação de pessoas kyc

Verificação de identidade de pessoas físicas: documento, selfie com prova de vida, validação de CPF e checagem em listas restritivas. Retorna uma decisão auditável que você pode vincular a um customer_ref (pré-requisito da compra de cripto).

{
  "customer_ref": "cliente-42",
  "person": {
    "name": "João da Silva",
    "tax_number": "00000000191",
    "birth_date": "1990-01-01"
  },
  "level": "full",
  "redirect_url": "https://suaempresa.com/kyc/callback",
  "external_id": "kyc-cliente42-001"
}

A resposta traz session_url (fluxo hospedado, pronto para abrir num iframe/redirect), decision, reasons[] e expires_at. Conclusões disparam kyc.approved / kyc.rejected / kyc.review por webhook.

14 KYB · verificação de empresas kyb

Verificação de pessoas jurídicas (CNPJ): situação cadastral, quadro societário (QSA), beneficiários finais (UBO), checagem de sócios em listas restritivas e documentos societários.

{
  "customer_ref": "empresa-7",
  "company": {
    "tax_number": "60281018000130",
    "legal_name": "Acme Serviços Ltda"
  },
  "require_ubo": true,
  "require_documents": true,
  "external_id": "kyb-empresa7-001"
}

Conclusões disparam kyb.approved / kyb.rejected / kyb.review. A decisão aprovada habilita onramp.buy e swift.payout para o customer_ref vinculado.

15 Consulta de dados data.lookup

Enriquecimento e validação em tempo real, roteados para os bureaus da malha WantsPay. Use antes de pagar, cobrar ou aprovar — reduz erro de titularidade e fraude.

{ "pix_key": "recebedor@example.com" }

// resposta
{
  "pix_key": "recebedor@example.com",
  "owner_name": "J*** da S***",
  "owner_tax_masked": "***.000.001-**",
  "bank": "Nubank",
  "key_type": "email"
}

16 Catálogo, limites & cotações

Nunca fixe redes, moedas, mínimos ou taxas no código — leia-os por API antes de cada operação.

17 Comissão (partner fee)

Você pode embutir uma comissão própria sobre cada operação, definida em basis points (partner_fee_bps; 200 = 2%). Ela é calculada sobre a base após a taxa da WantsPay e creditada num saldo de comissão separado.

{ "partner_fee_bps": 200 }   // 2%

A comissão é apurada após a liquidação da operação. Consulte disponivel_cents, min_saque_cents e pode_sacar_agora antes de sacar. Fórmula: floor(base_cents × (10000 − wantspay_bps − partner_bps) / 10000).

18 Webhooks

Configure a URL de recepção em PATCH /keys/me. A resposta devolve o webhook_secret uma única vez — guarde com segurança. Um só endpoint recebe os eventos de todos os serviços da chave.

{ "webhook_url": "https://suaempresa.com/api/wantspay/webhook" }

Assinatura (HMAC-SHA256)

Cada entrega traz o header X-WantsPay-Signature: t=1700000000,v1=<hmac_hex>. Valide o HMAC-SHA256 de timestamp.raw_body — capture o corpo bruto antes de fazer o parse do JSON.

const crypto = require('crypto');

function verify(header, rawBody, secret) {
  const t  = header.split(',')[0].split('=')[1];
  const v1 = header.split(',')[1].split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(v1), Buffer.from(expected)      // comparação em tempo constante
  );
}

Outros headers: X-WantsPay-Event-Id (dedupe por ele), X-WantsPay-Delivery-Id e X-WantsPay-Attempt (até 12 tentativas em ~7h).

Formato do evento

{
  "event": "cashout.completed",
  "event_id": "evt_exemplo",
  "created_at": "2026-09-30T20:00:00.000Z",
  "data": {
    "cashout_id": "co_exemplo",
    "status": "COMPLETED",
    "pix_e2e": "E00000000202609302000…"
  }
}

19 Idempotência & erros

Envie external_id em toda operação financeira (cash-out, payout, cash-in, swift, on-ramp, boleto, transferência). Em retry, reutilize o mesmo external_id com o corpo idêntico.

Códigos de erro

O corpo de erro inclui erro, acao, detail, request_id e agent_guidance. Ao pedir suporte, informe ambiente, id da operação, external_id, horário com fuso e request_id — nunca a chave, o segredo do webhook ou o CPF/CNPJ completo.

20 Referência de endpoints

Resumo das rotas por serviço. Base: https://api.wantspay.pro.

21 Suporte