WantsPay API — Documentação (escopos por chave

1 Visão geral

API agregadora: uma chave, vários serviços liberados por escopo. Valores em BRL em centavos (amount_cents); cripto como string decimal.

Cash-out

USDT/USDC → PIX. Escopo cashout (default). Gateway Lunium.

Payout PIX

PIX a partir do saldo. Escopo pix_payout (default).

Cash-in

PIX → cripto/saldo. Escopo cashin (sob aprovação).

💡

Fonte de verdade: GET /keys/me (escopos) e catálogo/limites da API — não fixe taxas no código.

2 Autenticação

Header X-API-Key (ou Authorization: Bearer). Corpo JSON com Content-Type: application/json.

bashrequisição

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

🔒

A chave só no servidor. Nunca no front-end nem em git.

GET/keys/meescopos, limites, taxa

GET/saldosaldo da conta

jsonGET /keys/me

{
  "env": "live",
  "scopes": ["cashout", "pix_payout"],
  "scopes_pending": ["cashin", "swift"],
  "partner_fee_bps": 0
}

3 Ambientes & chaves

Ambiente	Como obter	Prefixo
Sandbox	`POST /keys/sandbox`	`wp_test_…`
Produção	`POST /keys` + e-mail	`wp_live_…`

bashsandbox

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

Guarde api_key como WANTSPAY_API_KEY. Resposta também traz scopes e limits.

4 Escopos

Chaves simples (sem ponto), iguais ao código. Sem escopo → 403 scope_nao_aprovado.

✓

Padrão: cashout + pix_payout. Demais entram em scopes_pending até aprovação.

🗝

Controle por projeto: uma conta pode ter várias chaves (app, loja, ERP). Cada chave tem escopos e volume próprios no portal (conta.wantspay.pro / empresas.wantspay.pro → Chaves). Use um nome de projeto ao criar a chave.

Chave	Serviço	Padrão	Gateway
`cashout`	Cripto → PIX	ativo	lunium
`pix_payout`	Payout PIX (saldo)	ativo	pix_payout
`cashin`	PIX → cripto	aprovação	lunium
`pix_qr`	PIX QR dinâmico	aprovação	mesa
`ted`	TED	aprovação	mesa
`doc`	DOC	aprovação	mesa
`boletos`	Boleto	aprovação	mesa
`swift`	SWIFT (20+ moedas)	aprovação	mesa
`wire`	Wire	aprovação	mesa
`ach`	ACH (EUA)	aprovação	mesa
`sepa`	SEPA	aprovação	mesa
`spei`	SPEI (MX)	aprovação	mesa
`pse`	PSE (CO)	aprovação	mesa
`cvu`	CVU (AR)	aprovação	mesa
`tef`	TEF (CL)	aprovação	mesa
`jota`	JOTA (PE)	aprovação	mesa
`onramp`	Compra de cripto	aprovação	mesa
`custodia_brl`	Custódia BRL	aprovação	mesa
`kyc`	KYC pessoa	aprovação	mesa
`kyb`	KYB empresa	aprovação	mesa
`data`	Consulta de dados	aprovação	mesa

Pedir escopo

POST/keys/me/scopes/requestpede aprovação

jsonPOST /keys/me/scopes/request

{
  "scopes": ["swift", "cashin"],
  "note": "Remessa e on-ramp para clientes PJ"
}

🛡️

Trate 403 scope_nao_aprovado como estado normal: o serviço precisa ser habilitado, não é bug de código. Escopos mesa podem responder 503 gateway_nao_configurado até a mesa operar.

5 Comece agora

Chave sandbox

POST /keys/sandbox → wp_test_… → WANTSPAY_API_KEY.

Confira escopos

GET /keys/me deve listar cashout e pix_payout.

Cote

POST /cashout/preview — quanto o PIX recebe por USDT.

Crie e acompanhe

POST /cashout → aceite → GET /cashout/{id} ou webhook.

bashpreview

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

Serviço-base. Três passos: cotar/criar, aceitar (endereço), acompanhar.

`POST /cashout`

asset, network, PIX e amount ou brl_amount. Use external_id.

`POST /cashout/{id}/accept`

Confirma e devolve endereço de depósito.

`GET /cashout/{id}`

Ao concluir: pix_e2e, receipt_url.

jsonPOST /cashout

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

QUOTE_CREATED→AWAITING_DEPOSIT→DEPOSIT_CONFIRMED→PAYING_OUT→COMPLETED

Terminais: COMPLETED, EXPIRED, FAILED, REFUNDED, MANUAL_REVIEW. Preview: POST /cashout/preview.

7 Cash-in · PIX → cripto cashin

Sob aprovação. POST /cashin/charge gera QR PIX; acompanhe com GET /cashin/{id}/status.

jsonPOST /cashin/charge

{
  "amount_cents": 10000,
  "destino": "cripto",
  "asset": "usdt",
  "chain": "polygon",
  "payout_address": "0x…",
  "external_id": "cashin-001"
}

⚠️

Só trate como entregue com status=paid e settlement_status=sent.

8 Outros serviços

Existem no catálogo de escopos; a maioria é mesa (sob aprovação). Sem seção longa de payload até o gateway estar live.

pix_payout — PIX do saldo · POST /payouts

boletos · ted · doc · pix_qr — trilhos BR via mesa

swift · wire · ach · sepa · spei · pse · cvu · tef · jota — internacional / LATAM

onramp · custodia_brl · kyc · kyb · data — on-ramp, saldo, compliance

Peça com POST /keys/me/scopes/request usando exatamente essas chaves.

9 Webhooks

Configure em PATCH /keys/me (webhook_url). O webhook_secret aparece uma vez.

Header X-WantsPay-Signature: t=…,v1=<hmac_hex> — HMAC-SHA256 de timestamp.raw_body. Dedupe por event_id; responda 2xx em <10s.

jsonevento

{
  "event": "cashout.completed",
  "event_id": "evt_…",
  "data": { "cashout_id": "co_…", "status": "COMPLETED" }
}

Principais: cashout.*, cashin.*, key.scope_approved, webhook.test.

10 Erros & idempotência

Sempre envie external_id em operações financeiras. Retry = mesmo ID + mesmo corpo.

HTTP	code	Ação
`401`	—	Chave/ambiente
`403`	`scope_nao_aprovado`	`POST /keys/me/scopes/request`
`409`	`external_id_divergente`	Não reutilize o ID com outro body
`503`	`gateway_nao_configurado`	Gateway/mesa ainda indisponível
`429`	—	Respeite `Retry-After`

11 Referência

Base https://api.wantspay.pro.

Método	Endpoint	Notas
POST	`/keys/sandbox`	chave teste
POST	`/keys`	chave live
GET	`/keys/me`	escopos
POST	`/keys/me/scopes/request`	pedir escopo
POST	`/cashout/preview`	cotação
POST	`/cashout`	criar
POST	`/cashout/{id}/accept`	aceitar
GET	`/cashout/{id}`	status
POST	`/cashin/charge`	escopo cashin
GET	`/cashin/{id}/status`	status
GET	`/saldo`	saldo
POST	`/webhooks/test`	teste
GET	`/ping`	health

12 Suporte

E-mail

suporte@wantspay.pro

OpenAPI

/openapi.json

✓

Produção: chave em env; escopos em /keys/me; webhook com HMAC; external_id em retries.

Uma chave. Escopos por serviço.