{ "info": { "_postman_id": "ee9a0207-c167-4eb2-ac2b-a3b5d377b6e2", "name": "BSPay Gateway API v2 — Documentação Cliente", "description": "# BSPay Gateway API v2\n\nDocumentação completa de **TODOS** os endpoints acessíveis via **credenciais API** (Bearer JWT).\n\nNão inclui rotas admin/dashboard/internal — apenas integração server-to-server.\n\n## Base URL\n- Produção: `https://api.bspay.co`\n- Docs: https://dev.bspay.co\n\n## Fluxo típico\n\n1. **Autenticar** via `POST /v2/oauth/token` (Basic auth com client_id:client_secret) → recebe JWT\n2. **Consultar saldos/limites/fees** antes de operar\n3. **Criar cashin** (`/v2/transactions/cashin`) ou **wallet fixa** (`/v2/transactions/wallet`) pra receber\n4. **Receber webhook** `cashin.confirmed` ou `cashin.confirmed` quando pagamento entrar\n5. **Solicitar cashout** (`/v2/transactions/cashout`) com HMAC signing pra sacar — resposta 202 (async)\n6. **Receber webhook** `cashout.confirmed` ou `cashout.failed` quando processar\n7. **Listar transações** via `/v2/account/transactions/list` pra reconciliação\n\n## Autenticação\n\nTodas rotas (exceto `/v2/oauth/token`) exigem `Authorization: Bearer `.\n\nToken expira em 1h — re-autenticar antes.\n\n## Assinatura HMAC (rotas financeiras)\n\nCashout, internal_transfer e conversion exigem 3 headers adicionais:\n```\nX-Signature: hex(hmac_sha256(timestamp + '.' + nonce + '.' + body, signing_key))\nX-Timestamp: \nX-Nonce: \n```\n\nValidações:\n- Timestamp ±5min\n- Nonce único nos últimos 5min (anti-replay)\n\n## Estrutura padrão de resposta\n\n**Sucesso** (200/202): `{ success: true, data: {...}, request_id, timestamp }`\n\n**Erro**: `{ success: false, error: { code, message, group, retryable, details? } }`\n\n## Moedas e chains suportadas\n\n| Moeda | Chains |\n|---|---|\n| BRL | PIX |\n| MXN | SPEI |\n| USDT | tron, ethereum, bsc, polygon, arbitrum |\n| USDC | ethereum, bsc, polygon, arbitrum, base, optimism |\n| BTC | bitcoin |\n| ETH | ethereum, arbitrum, base, optimism |\n| SOL | solana |\n| BNB | bsc |\n\n## Webhooks\n\nBSPay envia POST pra URL configurada na credencial.\n\nValidar via `X-Webhook-Signature: hex(hmac_sha256(rawBody, callback_secret))`.\n\nHeaders enviados:\n```\nContent-Type: application/json\nX-Webhook-Event: \nX-Webhook-Signature: \nX-Webhook-Timestamp: \n```\n\nEventos:\n- `cashin.confirmed`, `cashin.refunded`\n- `cashout.confirmed`, `cashout.failed`\n- `cashin.confirmed`\n- `transfer.confirmed`\n- `conversion.confirmed`\n- `chargeback.opened`, `chargeback.opened|chargeback.won|chargeback.lost|chargeback.canceled`\n\nRetry: 5 tentativas (1min, 5min, 15min, 1h, 6h). Aguarda HTTP 2xx.\n\n## Suporte\ncontato@bspay.co", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "01 — Auth (OAuth)", "item": [ { "name": "POST OAuth Token", "request": { "auth": { "type": "basic", "basic": [ { "key": "username", "value": "{{client_id}}", "type": "string" }, { "key": "password", "value": "{{client_secret}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"grant_type\": \"client_credentials\"\n}" }, "url": { "raw": "{{base_url}}/v2/oauth/token", "host": [ "{{base_url}}" ], "path": [ "v2", "oauth", "token" ] }, "description": "## OAuth Token (gerar JWT)\n\n### Auth: Basic base64(client_id:client_secret)\n\n### Body\n- `grant_type`: `client_credentials` (required)\n\n### Response 200\n```json\n{\n \"access_token\": \"eyJ0eXAi...\",\n \"expires_in\": 3600,\n \"_meta\": { \"request_id\": \"...\", \"timestamp\": \"...\" }\n}\n```\n\n### Errors\n- `MISSING_AUTH_HEADER` 401\n- `INVALID_AUTH_FORMAT` 401\n- `INVALID_CREDENTIALS` 401\n- `IP_BLOCKED_TEMPORARILY` 403 — após 5 tentativas erradas (lock 5min)\n- `CREDENTIAL_PENDING_ADMIN_ACTIVATION` 403\n\n### Rate limit\n30/min/IP" }, "response": [] } ] }, { "name": "02 — Account (read)", "item": [ { "name": "GET Balance", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v2/account/balance", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "balance" ] }, "description": "## Saldo agregado\n\nRetorna saldos (available + blocked + pending) em todas as moedas da conta.\n\n### Rate: 120/min\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"balances\": [\n { \"type\": \"fiat\", \"currency\": \"BRL\", \"available\": \"12823.91\", \"blocked\": \"5797.19\", \"pending\": \"0.00\", \"total\": \"18621.10\" },\n { \"type\": \"crypto\", \"currency\": \"USDT\", \"available\": \"1500.00\", \"blocked\": \"0.00\", \"pending\": \"0.00\", \"total\": \"1500.00\" }\n ],\n \"wallet_total_usd\": \"3947.18\",\n \"wallet_total_brl\": \"21376.10\"\n }\n}\n```" }, "response": [] }, { "name": "GET Profile", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v2/account/info/profile", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "info", "profile" ] }, "description": "## Perfil da conta\n\n### Rate: 60/min\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"username\": \"merchant_demo\",\n \"email\": \"user@example.com\",\n \"kyc_level\": 2,\n \"kyc_status\": \"approved\",\n \"status\": 1\n }\n}\n```" }, "response": [] }, { "name": "GET Limits", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v2/account/limits", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "limits" ] }, "description": "## Limites diários, mensais e por operação\n\n### Rate: 60/min\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"limits\": [\n {\n \"currency\": \"BRL\",\n \"operation\": \"cashin\",\n \"daily_limit\": \"100000.00\",\n \"daily_used\": \"12345.67\",\n \"daily_remaining\": \"87654.33\",\n \"per_operation_min\": \"1.00\",\n \"per_operation_max\": \"50000.00\"\n }\n ],\n \"reset_at\": \"2026-05-01T00:00:00Z\"\n }\n}\n```\n\n### Erros relacionados\n- `LIMIT_EXCEEDED` 409 — daily/monthly atingido\n- `EXCEEDS_MAX_LIMIT` 409 — `details.max_amount`\n- `BELOW_MIN_LIMIT` 409 — `details.min_amount`" }, "response": [] }, { "name": "GET Fees", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v2/account/fees", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "fees" ] }, "description": "## Taxas configuradas\n\n### Rate: 60/min\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"fees\": {\n \"BRL\": {\n \"cashin\": { \"type\": \"percent\", \"value\": \"1.50\", \"min\": \"0.50\", \"max\": \"100.00\" },\n \"cashout\": { \"type\": \"fixed\", \"value\": \"1.00\" }\n },\n \"USDT\": {\n \"cashin\": { \"type\": \"fixed\", \"value\": \"1.00\" },\n \"cashout\": { \"type\": \"fixed\", \"value\": \"1.50\" }\n }\n },\n \"conversion\": {\n \"spread_percent\": \"0.40\",\n \"fee_percent\": \"0.10\"\n }\n }\n}\n```\n\n### Errors\n- `MISSING_FEE_CONFIG` 500" }, "response": [] } ] }, { "name": "03 — Transactions", "item": [ { "name": "POST Cashin (BRL via PIX QR)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 100.00,\n \"currency\": \"BRL\",\n \"payer\": {\n \"name\": \"João Silva\",\n \"document\": \"12345678901\"\n },\n \"external_id\": \"order_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin BRL (PIX QR Code)\n\n### Rate: 12000/min\n\n### Body\n| Campo | Required | Descrição |\n|--|--|--|\n| `amount` | sim | Valor BRL (até 2 decimais) |\n| `currency` | sim | `BRL` |\n| `payer.name` | sim | Nome pagador |\n| `payer.document` | sim | CPF/CNPJ |\n| `payer.email` | não | E-mail |\n| `external_id` | sim | ID único |\n| `postback_url` | não | Webhook (override do default da credencial) |\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"transaction_id\": \"abc123\",\n \"external_id\": \"order_xyz\",\n \"currency\": \"BRL\",\n \"amount\": 100.00,\n \"fee\": 0.30,\n \"payment_method\": \"pix\",\n \"payment_info\": {\n \"qrcode\": \"00020126360014BR.GOV.BCB.PIX...\",\n \"expiration\": 3600,\n \"expires_at\": \"2026-04-30T11:20:00Z\"\n },\n \"status\": \"pending\"\n }\n}\n```\n\n### Errors\n- `MISSING_REQUIRED_FIELD` 400\n- `INVALID_AMOUNT` 422\n- `INVALID_CURRENCY` 422\n- `EXCEEDS_MAX_LIMIT` 409\n- `LIMIT_EXCEEDED` 409\n- `DUPLICATE_EXTERNAL_ID` 409\n- `PROVIDER_ERROR` 502" }, "response": [] }, { "name": "POST Cashin (USDT TRON)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 50.00,\n \"currency\": \"USDT\",\n \"chain\": \"tron\",\n \"external_id\": \"crypto_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin USDT TRON\n\nGera endereço temporário (expira em ~30min). Para endereço permanente use `/v2/transactions/wallet`.\n\n### Body adicional pra crypto\n| Campo | Required |\n|--|--|\n| `chain` | sim — `tron`, `ethereum`, `bsc`, `polygon`, `arbitrum` |\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"transaction_id\": \"abc123\",\n \"currency\": \"USDT\",\n \"amount\": 50.00,\n \"fee\": 1.00,\n \"payment_method\": \"crypto\",\n \"payment_info\": {\n \"address\": \"TVh59WL5XLqHTCiVCPp7bECRug9QQaHgXa\",\n \"chain\": \"tron\",\n \"network\": \"tron\",\n \"expires_at\": \"2026-04-30T10:50:00Z\",\n \"min_confirmations\": 20\n },\n \"status\": \"pending\"\n }\n}\n```" }, "response": [] }, { "name": "POST Cashin (USDC ETH)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 100.00,\n \"currency\": \"USDC\",\n \"chain\": \"ethereum\",\n \"external_id\": \"crypto_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin USDC Ethereum (ERC20)\n\nUSDC suporta: `ethereum`, `bsc`, `polygon`, `arbitrum`, `base`, `optimism`." }, "response": [] }, { "name": "POST Cashin (BTC)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 0.001,\n \"currency\": \"BTC\",\n \"chain\": \"bitcoin\",\n \"external_id\": \"crypto_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin BTC (mainnet)\n\nMín 0.0001 BTC. Confirma após 3 confirmações." }, "response": [] }, { "name": "POST Cashin (ETH Arbitrum)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 0.05,\n \"currency\": \"ETH\",\n \"chain\": \"arbitrum\",\n \"external_id\": \"crypto_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin ETH Arbitrum (L2)\n\nETH suporta: `ethereum`, `arbitrum`, `base`, `optimism`." }, "response": [] }, { "name": "POST Cashin (SOL)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 1.5,\n \"currency\": \"SOL\",\n \"chain\": \"solana\",\n \"external_id\": \"crypto_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin SOL\n\n32 confirmações típicas." }, "response": [] }, { "name": "POST Cashin (MXN SPEI)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 200.00,\n \"currency\": \"MXN\",\n \"payer\": {\n \"name\": \"Maria Lopez\",\n \"document\": \"LOPM800101HDFLNN09\"\n },\n \"external_id\": \"order_{{$randomUUID}}\",\n \"postback_url\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashin", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashin" ] }, "description": "## Cashin SPEI MXN\n\nGera CLABE temporária (expira em ~30min)." }, "response": [] }, { "name": "POST Cashout (PIX BRL)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"withdraw_{{$randomUUID}}\",\n \"amount\": 50.00,\n \"currency\": \"BRL\",\n \"key\": \"12345678901\",\n \"key_type\": \"cpf\",\n \"description\": \"Saque PIX\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashout", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashout" ] }, "description": "## Cashout PIX BRL\n\n### Auth: Bearer + HMAC\n### Rate: 6000/min\n\n### Body\n| Campo | Required | Descrição |\n|--|--|--|\n| `external_id` | sim | ID único |\n| `amount` | sim | Valor BRL |\n| `currency` | sim | `BRL` |\n| `key` | sim | Chave PIX |\n| `key_type` | sim | `cpf`, `cnpj`, `email`, `phone`, `random` |\n| `description` | não | |\n\n### Response 202 (assíncrono)\n```json\n{\n \"success\": true,\n \"data\": {\n \"transaction_id\": \"abc123\",\n \"external_id\": \"withdraw_001\",\n \"currency\": \"BRL\",\n \"amount\": 50.00,\n \"fee\": 1.00,\n \"status\": \"pending\"\n },\n \"message\": \"PENDING\"\n}\n```\n\nWebhook `cashout.confirmed` ou `cashout.failed` chega depois.\n\n### Errors\n- `MISSING_SIGNATURE` / `INVALID_SIGNATURE` 401\n- `INVALID_TIMESTAMP` 401 — fora janela ±5min\n- `REPLAY_DETECTED` 401 — nonce duplicado\n- `BELOW_MIN_LIMIT` 409\n- `EXCEEDS_MAX_LIMIT` 409\n- `LIMIT_EXCEEDED` 409\n- `INSUFFICIENT_FUNDS` 422\n- `ACCOUNT_UNDER_REVIEW` 403\n- `INVALID_PIX_KEY` 422\n- `DUPLICATE_EXTERNAL_ID` 409" }, "response": [] }, { "name": "POST Cashout (USDT TRON)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"withdraw_{{$randomUUID}}\",\n \"amount\": 50.00,\n \"currency\": \"USDT\",\n \"key\": \"TRwLhXvqNqTqbGgHNPCEfLeEfDwfWTpuxi\",\n \"network\": \"tron\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashout", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashout" ] }, "description": "## Cashout Crypto (USDT/USDC/BTC/ETH/SOL)\n\n### Body adicional crypto\n| Campo | Required |\n|--|--|\n| `network` | sim — chain válida pra moeda |\n\n### Errors específicos\n- `UNSUPPORTED_CHAIN` 422 — `details.supported`\n\n### Webhook async\nSucesso: `cashout.confirmed` com `tx_hash` blockchain.\nFalha: `cashout.failed` — saldo refundado AUTOMATICAMENTE.\n\n`error_code` possíveis: `TRON_ENERGY_FAIL`, `INSUFFICIENT_BALANCE`, `NO_HOT_WALLET`, `INVALID_ADDRESS`, `BLACKLISTED`, `BLOCKCHAIN_REVERT`, `BROADCAST_FAIL`, `UNKNOWN`." }, "response": [] }, { "name": "POST Cashout (USDC Polygon)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"withdraw_{{$randomUUID}}\",\n \"amount\": 100.00,\n \"currency\": \"USDC\",\n \"key\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb\",\n \"network\": \"polygon\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashout", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashout" ] }, "description": "## Cashout USDC Polygon\n\nUSDC suporta: ethereum, bsc, polygon, arbitrum, base, optimism." }, "response": [] }, { "name": "POST Cashout (BTC)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"withdraw_{{$randomUUID}}\",\n \"amount\": 0.001,\n \"currency\": \"BTC\",\n \"key\": \"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh\",\n \"network\": \"bitcoin\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashout", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashout" ] }, "description": "## Cashout BTC mainnet" }, "response": [] }, { "name": "POST Cashout (SPEI MXN)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"withdraw_{{$randomUUID}}\",\n \"amount\": 200.00,\n \"currency\": \"MXN\",\n \"key\": \"012345678901234567\",\n \"name\": \"Maria Lopez\",\n \"bank_code\": \"BANORTE\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/cashout", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "cashout" ] }, "description": "## Cashout SPEI (MXN)\n\n### Body adicional MXN\n| Campo | Required |\n|--|--|\n| `key` | sim — CLABE 18 dígitos |\n| `name` | sim — nome recebedor |\n| `bank_code` | não — auto-detect via CLABE |" }, "response": [] }, { "name": "POST Wallet Fixa (USDT TRON)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"currency\": \"USDT\",\n \"chain\": \"tron\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/wallet", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "wallet" ] }, "description": "## Wallet Fixa (endereço permanente)\n\nProvisiona endereço crypto/PIX/CLABE permanente. Qualquer depósito futuro nele dispara webhook `cashin.confirmed`.\n\n### Rate: 30/min\n\n### Body\n| Campo | Required |\n|--|--|\n| `currency` | sim — `BRL`, `MXN`, `USDT`, `USDC`, `BTC`, `ETH`, `SOL`, `BNB` |\n| `chain` | sim para crypto — `tron`/`ethereum`/`bsc`/`polygon`/`arbitrum`/`base`/`optimism`/`solana`/`bitcoin` |\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"wallet_id\": 41,\n \"address\": \"TWMrdKSXaTbpcjBAT5PEzL4LtkC9fL4HQk\",\n \"currency\": \"USDT\",\n \"chain\": \"tron\",\n \"min_confirmations\": 20\n }\n}\n```\n\n### Errors\n- `INVALID_CURRENCY` 422\n- `UNSUPPORTED_CHAIN` 422 — `details.supported`\n- `UNSUPPORTED_CURRENCY` 422\n- `WALLET_LIMIT_REACHED` 409\n- `PROVIDER_ERROR` 502" }, "response": [] }, { "name": "POST Wallet Fixa (USDC Base)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"currency\": \"USDC\",\n \"chain\": \"base\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/wallet", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "wallet" ] }, "description": "## Wallet Fixa USDC Base (L2)" }, "response": [] }, { "name": "POST Wallet Fixa (PIX BRL)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"currency\": \"BRL\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/wallet", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "wallet" ] }, "description": "## Wallet Fixa PIX BRL\n\nResponse contém `pix_key` (chave aleatória) e `qrcode` EMV estático." }, "response": [] }, { "name": "POST Wallet Fixa (SPEI MXN)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"currency\": \"MXN\"\n}" }, "url": { "raw": "{{base_url}}/v2/transactions/wallet", "host": [ "{{base_url}}" ], "path": [ "v2", "transactions", "wallet" ] }, "description": "## Wallet Fixa SPEI MXN\n\nResponse contém `clabe` (18 dígitos) e `bank_code`." }, "response": [] } ] }, { "name": "04 — PIX (Legacy)", "item": [ { "name": "POST QR Code Legacy", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 100.00,\n \"payer\": {\n \"name\": \"João Silva\",\n \"document\": \"12345678901\"\n },\n \"external_id\": \"order_{{$randomUUID}}\",\n \"postbackUrl\": \"https://yourdomain.com/webhook\"\n}" }, "url": { "raw": "{{base_url}}/v2/pix/qrcode", "host": [ "{{base_url}}" ], "path": [ "v2", "pix", "qrcode" ] }, "description": "## Cashin PIX QR (legacy BRL)\n\nVer `/v2/transactions/cashin` (preferido).\n\n### Rate: 12000/min\n\nResponse retorna payload \"achatado\" sem envelope `success`/`data`." }, "response": [] }, { "name": "POST Cashout Legacy", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 50.00,\n \"pix_key\": \"12345678901\",\n \"pix_key_type\": \"cpf\",\n \"external_id\": \"withdraw_{{$randomUUID}}\"\n}" }, "url": { "raw": "{{base_url}}/v2/pix/payment", "host": [ "{{base_url}}" ], "path": [ "v2", "pix", "payment" ] }, "description": "## Cashout PIX legacy\n\nMesmo comportamento de `/v2/transactions/cashout` com `currency=BRL`.\n\n### Auth: Bearer + HMAC\n### Rate: 6000/min" }, "response": [] }, { "name": "POST Consult Transaction", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"pix_id\": \"9a18e703b3f5db3d2704401f5f49c9ab\"\n}" }, "url": { "raw": "{{base_url}}/v2/consult-transaction", "host": [ "{{base_url}}" ], "path": [ "v2", "consult-transaction" ] }, "description": "## Consultar transação PIX por ID\n\n### Status legend (legacy)\n| Code | Label |\n|--|--|\n| 0 | pending |\n| 1 | confirmed |\n| 3 | manual_review |\n| 5 | cancelled |\n| 6 | sending |\n| 99 | failed |\n\n### Errors\n- `MISSING_REQUIRED_FIELD` 400 — `pix_id`\n- `TRANSACTION_NOT_FOUND` 404" }, "response": [] } ], "description": "Endpoints PIX legados — manter compatibilidade. Pra novas integrações, usar `/v2/transactions/*`." }, { "name": "05 — Internal Transfers", "item": [ { "name": "POST Send Transfer", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"username\": \"receiver_username\",\n \"amount\": 25.00,\n \"currency\": \"BRL\",\n \"description\": \"Pagamento\",\n \"external_id\": \"transfer_{{$randomUUID}}\"\n}" }, "url": { "raw": "{{base_url}}/v2/internal_transfers/payment", "host": [ "{{base_url}}" ], "path": [ "v2", "internal_transfers", "payment" ] }, "description": "## Transferência interna BSPay\n\n### Auth: Bearer + HMAC\n### Rate: 60/min (anti-enumeração)\n\n### Errors\n- `MISSING_REQUIRED_FIELD` (`details.field: pin`)\n- `INVALID_AMOUNT` 422\n- `INVALID_CURRENCY` 422\n- `LIMIT_EXCEEDED` 409\n- `INSUFFICIENT_BALANCE` 422\n- `USER_NOT_FOUND` 404\n- `SELF_TRANSFER_BLOCKED` 400\n\n### Webhook\nAmbas contas recebem `transfer.confirmed` (`direction: sent` / `direction: received`)." }, "response": [] } ] }, { "name": "06 — Currency Conversion", "item": [ { "name": "POST Rate (cotação spot)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 100.00,\n \"base_currency\": \"USDT\",\n \"destination_currency\": \"BRL\"\n}" }, "url": { "raw": "{{base_url}}/v2/conversions/rate", "host": [ "{{base_url}}" ], "path": [ "v2", "conversions", "rate" ] }, "description": "## Cotação atual (sem fees calculados)\n\n### Rate: 120/min\n\nMais leve que `simulate` — não calcula spread por valor." }, "response": [] }, { "name": "POST Simulate Conversion", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 100.00,\n \"base_currency\": \"BRL\",\n \"destination_currency\": \"USDT\"\n}" }, "url": { "raw": "{{base_url}}/v2/conversions/simulate", "host": [ "{{base_url}}" ], "path": [ "v2", "conversions", "simulate" ] }, "description": "## Simular (sem executar)\n\nRetorna cotação + spread + fee sem debitar.\n\n### Rate: 60/min\n\n### Response\n```json\n{\n \"success\": true,\n \"data\": {\n \"base_currency\": \"BRL\",\n \"destination_currency\": \"USDT\",\n \"from_amount\": \"100.00\",\n \"to_amount\": \"19.00\",\n \"rate\": \"0.1900\",\n \"spread\": \"0.0039\",\n \"fee\": \"0.50\",\n \"expires_at\": \"2026-04-30T13:25:37Z\"\n }\n}\n```" }, "response": [] }, { "name": "POST Convert (executar)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Signature", "value": "{{signature}}" }, { "key": "X-Timestamp", "value": "{{timestamp}}" }, { "key": "X-Nonce", "value": "{{nonce}}" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 80,\n \"base_currency\": \"USDT\",\n \"destination_currency\": \"BRL\",\n \"external_id\": \"conv_{{$randomUUID}}\"\n}" }, "url": { "raw": "{{base_url}}/v2/conversions/new", "host": [ "{{base_url}}" ], "path": [ "v2", "conversions", "new" ] }, "description": "## Conversão FX (executa)\n\n### Auth: Bearer + HMAC\n### Rate: 30/min\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"conversion_id\": \"conv_abc\",\n \"amount_from\": 80,\n \"currency_from\": \"USDT\",\n \"amount_to\": 432.00,\n \"currency_to\": \"BRL\",\n \"rate\": 5.40,\n \"fee\": 1.50\n }\n}\n```\n\n### Errors\n- `INVALID_CURRENCY` (origem == destino)\n- `LIMIT_EXCEEDED`\n- `INSUFFICIENT_BALANCE`\n- `RATE_EXPIRED`\n\n### Webhook\n`conversion.confirmed` com `conversion_id`, `rate`, `fee`." }, "response": [] } ] }, { "name": "07 — Listagens", "item": [ { "name": "POST List Transactions", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"page\": 1,\n \"page_size\": 20,\n \"status\": null,\n \"type\": null,\n \"currency\": null,\n \"from_date\": null,\n \"to_date\": null\n}" }, "url": { "raw": "{{base_url}}/v2/account/transactions/list", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "transactions", "list" ] }, "description": "## Lista transações (cashin + cashout + transfer + conversion)\n\n### Rate: 300/min\n\n### Body\n| Campo | Valores |\n|--|--|\n| `page`, `page_size` | Paginação (1-100) |\n| `status` | `pending`/`confirmed`/`failed`/`cancelled`/null |\n| `type` | `cashin`/`cashout`/null |\n| `source` | `cashin`/`cashout`/`conversion`/`internal_transfer`/`cashin.confirmed`/null |\n| `currency` | código ou null |\n| `from_date`, `to_date` | YYYY-MM-DD ou null |\n| `transaction_id`, `external_id` | filtro pontual |\n\n### Response 200\n```json\n{\n \"success\": true,\n \"data\": {\n \"items\": [\n {\n \"source\": \"cashout\",\n \"transaction_id\": \"abc123\",\n \"external_id\": \"withdraw_001\",\n \"status\": \"confirmed\",\n \"amount\": \"50.00\",\n \"fee_amount\": \"1.00\",\n \"currency\": \"BRL\",\n \"currency_type\": \"fiat\",\n \"direction\": \"debit\",\n \"wallet\": \"12345678901\",\n \"hash\": \"E17028...\",\n \"old_balance\": \"1000.00\",\n \"new_balance\": \"949.00\",\n \"created_at\": \"2026-04-30T13:00:00Z\",\n \"confirmed_at\": \"2026-04-30T13:00:04Z\",\n \"payer\": { \"name\": \"...\", \"document\": \"...\" },\n \"receiver\": { \"name\": \"...\", \"document\": \"...\" }\n }\n ],\n \"pagination\": { \"page\": 1, \"page_size\": 20, \"total\": 142, \"total_pages\": 8, \"has_next\": true, \"has_prev\": false }\n }\n}\n```\n\n### Errors\n- `INVALID_PAYLOAD` 400\n- `INVALID_FORMAT` 422\n- `INVALID_VALUE` 422" }, "response": [] } ] }, { "name": "10 — Infrações PIX (MED)", "item": [ { "name": "POST List Infractions", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": null, "url": { "raw": "{{base_url}}/v2/account/infractions", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "infractions" ] }, "description": "## Lista infrações recebidas\n\n### Rate: 60/min\n\n### Body\n| Campo | Valores |\n|--|--|\n| `page`, `page_size` | Paginação |\n| `status` | `open`/`responded`/`resolved`/null |\n| `type` | `REFUND_REQUEST`/`FRAUD`/null |" }, "response": [] }, { "name": "GET Infraction Detail", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v2/account/infractions/detail?id=abc-uuid", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "infractions", "detail" ], "query": [ { "key": "id", "value": "abc-uuid" } ] }, "description": "## Detalhes infração + replies\n\n### Errors\n- `INFRACTION_NOT_FOUND` 404" }, "response": [] }, { "name": "POST Reply Infraction (multipart com evidências)", "request": { "method": "POST", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "id", "value": "abc-uuid", "type": "text" }, { "key": "message", "value": "Pagamento legítimo. Anexos: NF-e e comprovante.", "type": "text" }, { "key": "files[]", "type": "file", "src": [] } ] }, "url": { "raw": "{{base_url}}/v2/account/infractions/reply", "host": [ "{{base_url}}" ], "path": [ "v2", "account", "infractions", "reply" ] }, "description": "## Responder infração\n\n### Content-Type: multipart/form-data\n### Rate: 10/min\n\n### Form fields\n| Campo | Required |\n|--|--|\n| `id` | sim — infraction_id |\n| `message` | sim — texto defesa (até 5000 chars) |\n| `files[]` | não — PDF/JPG/PNG até 10MB cada (máx 5) |\n\n### Errors\n- `MISSING_REQUIRED_FIELD` 400\n- `INFRACTION_NOT_FOUND` 404\n- `INFRACTION_CLOSED` 409\n- `DEADLINE_EXPIRED` 409\n- `FILE_TOO_LARGE` 413\n- `TOO_MANY_FILES` 422\n- `UNSUPPORTED_FILE_TYPE` 422" }, "response": [] } ], "description": "Sistema de disputas PIX (REFUND_REQUEST, FRAUD) do BACEN/PSP." }, { "name": "12 — Webhooks (recebidos pelo cliente)", "item": [ { "name": "Payload: cashin.confirmed (PIX BRL)", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashin.confirmed" }, { "key": "X-Webhook-Signature", "value": "" }, { "key": "X-Webhook-Timestamp", "value": "" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashin.confirmed\",\n \"transaction_id\": \"abc123\",\n \"external_id\": \"order_xyz\",\n \"type\": \"cashin\",\n \"currency\": \"BRL\",\n \"currency_type\": \"fiat\",\n \"amount\": \"100.00\",\n \"fee\": \"1.50\",\n \"amount_net\": \"98.50\",\n \"status\": \"confirmed\",\n \"source\": \"dynamic_qr\",\n \"e2e_id\": \"E17028875202604301400ABC123\",\n \"payer\": { \"name\": \"João Silva\", \"document\": \"12345678901\" },\n \"old_balance\": \"500.00\",\n \"new_balance\": \"598.50\",\n \"confirmed_at\": \"2026-04-30T13:00:04Z\"\n}" }, "url": { "raw": "" }, "description": "Pagador completou PIX. Idempotência via `transaction_id`." }, "response": [] }, { "name": "Payload: cashin.confirmed (Crypto)", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashin.confirmed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashin.confirmed\",\n \"transaction_id\": \"abc123\",\n \"external_id\": \"crypto_001\",\n \"type\": \"cashin\",\n \"currency\": \"USDT\",\n \"currency_type\": \"crypto\",\n \"chain\": \"tron\",\n \"amount\": \"50.00\",\n \"fee\": \"1.00\",\n \"amount_net\": \"49.00\",\n \"status\": \"confirmed\",\n \"source\": \"crypto\",\n \"tx_hash\": \"1c71b23e0fac...\",\n \"old_balance\": \"1000.00\",\n \"new_balance\": \"1049.00\",\n \"confirmed_at\": \"2026-04-30T13:00:30Z\"\n}" }, "url": { "raw": "" }, "description": "Cashin crypto temporário confirmado on-chain." }, "response": [] }, { "name": "Payload: cashin.refunded", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashin.refunded" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashin.refunded\",\n \"transaction_id\": \"abc123\",\n \"original_transaction_id\": \"abc123\",\n \"external_id\": \"order_xyz\",\n \"currency\": \"BRL\",\n \"amount\": \"100.00\",\n \"amount_refunded\": \"100.00\",\n \"status\": \"refunded\",\n \"reason\": \"PROVIDER_REVERSAL\",\n \"old_balance\": \"598.50\",\n \"new_balance\": \"498.50\",\n \"refunded_at\": \"2026-04-30T14:00:00Z\"\n}" }, "url": { "raw": "" }, "description": "Cashin estornado — saldo debitado e devolvido ao pagador." }, "response": [] }, { "name": "Payload: cashout.confirmed (PIX BRL)", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashout.confirmed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashout.confirmed\",\n \"transaction_id\": \"abc123\",\n \"external_id\": \"withdraw_001\",\n \"type\": \"cashout\",\n \"currency\": \"BRL\",\n \"currency_type\": \"fiat\",\n \"amount\": \"50.00\",\n \"fee\": \"1.00\",\n \"status\": \"confirmed\",\n \"wallet\": \"12345678901\",\n \"key_type\": \"cpf\",\n \"hash\": \"E17028875202604301400ABC123\",\n \"receiver\": { \"name\": \"João Silva\", \"document\": \"12345678901\", \"bank\": \"BCO DO BRASIL\" },\n \"confirmed_at\": \"2026-04-30T13:00:04Z\"\n}" }, "url": { "raw": "" }, "description": "Saque PIX concluído. `hash` é o e2e_id." }, "response": [] }, { "name": "Payload: cashout.confirmed (Crypto)", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashout.confirmed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashout.confirmed\",\n \"transaction_id\": \"abc123\",\n \"type\": \"cashout\",\n \"currency\": \"USDT\",\n \"currency_type\": \"crypto\",\n \"chain\": \"TRON\",\n \"amount\": \"50.00\",\n \"fee\": \"1.50\",\n \"status\": \"confirmed\",\n \"wallet\": \"TRwLh...\",\n \"tx_hash\": \"1c71b23e0fac...\",\n \"confirmed_at\": \"2026-04-30T13:00:30Z\"\n}" }, "url": { "raw": "" }, "description": "Saque crypto concluído. `tx_hash` é o hash on-chain." }, "response": [] }, { "name": "Payload: cashout.failed", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashout.failed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashout.failed\",\n \"transaction_id\": \"abc123\",\n \"external_id\": \"withdraw_001\",\n \"type\": \"cashout\",\n \"currency\": \"USDT\",\n \"amount\": \"50.00\",\n \"status\": \"failed\",\n \"wallet\": \"TRwLh...\",\n \"error_code\": \"TRON_ENERGY_FAIL\",\n \"error_message\": \"Insufficient energy on hot wallet.\",\n \"refunded_amount\": \"51.50\",\n \"failed_at\": \"2026-04-30T13:05:00Z\"\n}" }, "url": { "raw": "" }, "description": "Saque falhou. **Saldo refundado automaticamente**.\n\n`error_code` possíveis: `TRON_ENERGY_FAIL`, `INSUFFICIENT_BALANCE`, `NO_HOT_WALLET`, `INVALID_ADDRESS`, `BLACKLISTED`, `BLOCKCHAIN_REVERT`, `BROADCAST_FAIL`, `PIX_KEY_NOT_FOUND`, `PROVIDER_TIMEOUT`, `UNKNOWN`." }, "response": [] }, { "name": "Payload: cashin.confirmed", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "cashin.confirmed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"cashin.confirmed\",\n \"transaction_id\": \"wdep_abc123\",\n \"wallet_id\": 41,\n \"address\": \"TWMrdKSXa...\",\n \"chain\": \"tron\",\n \"currency\": \"USDT\",\n \"currency_type\": \"crypto\",\n \"amount_gross\": \"5.403\",\n \"amount_net\": \"4.403\",\n \"fee\": \"1.000\",\n \"tx_hash\": \"24669f333...\",\n \"from_address\": \"TKxSenderAddress...\",\n \"old_balance\": \"100.00\",\n \"new_balance\": \"104.403\",\n \"confirmed_at\": \"2026-04-30T13:00:00Z\"\n}" }, "url": { "raw": "" }, "description": "Depósito recebido em wallet fixa. `amount_net` = valor creditado (após fee BSPay)." }, "response": [] }, { "name": "Payload: transfer.confirmed", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "transfer.confirmed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"transfer.confirmed\",\n \"transaction_id\": \"tx_abc\",\n \"direction\": \"received\",\n \"amount\": \"25.00\",\n \"currency\": \"BRL\",\n \"counterparty\": \"sender_username\",\n \"description\": \"Pagamento\",\n \"old_balance\": \"100.00\",\n \"new_balance\": \"125.00\",\n \"confirmed_at\": \"2026-04-30T13:00:00Z\"\n}" }, "url": { "raw": "" }, "description": "Transferência interna concluída — ambas contas recebem (`direction: sent` ou `direction: received`)." }, "response": [] }, { "name": "Payload: conversion.confirmed", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "conversion.confirmed" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"conversion.confirmed\",\n \"conversion_id\": \"conv_abc\",\n \"external_id\": \"conv_001\",\n \"amount_from\": \"80.00\",\n \"currency_from\": \"USDT\",\n \"amount_to\": \"432.00\",\n \"currency_to\": \"BRL\",\n \"rate\": \"5.4000\",\n \"fee\": \"1.50\",\n \"status\": \"completed\",\n \"completed_at\": \"2026-04-30T13:00:00Z\"\n}" }, "url": { "raw": "" }, "description": "Conversão FX completada." }, "response": [] }, { "name": "Payload: chargeback.opened", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "chargeback.opened" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"chargeback.opened\",\n \"infraction_id\": \"abc-uuid-1234\",\n \"type\": \"REFUND_REQUEST\",\n \"status\": \"open\",\n \"amount\": \"25.00\",\n \"currency\": \"BRL\",\n \"transaction_id\": \"tx_xyz789\",\n \"e2e_id\": \"E17028875202604301400ABC123\",\n \"deadline_at\": \"2026-05-07T13:00:00Z\",\n \"reason\": \"Customer disputed — alleged unauthorized payment\",\n \"created_at\": \"2026-04-30T13:00:00Z\"\n}" }, "url": { "raw": "" }, "description": "Nova infração PIX. Saldo bloqueado automaticamente. Responder via `/v2/account/infractions/reply` antes de `deadline_at`." }, "response": [] }, { "name": "Payload: chargeback.opened|chargeback.won|chargeback.lost|chargeback.canceled", "request": { "method": "POST", "header": [ { "key": "X-Webhook-Event", "value": "chargeback.opened|chargeback.won|chargeback.lost|chargeback.canceled" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"chargeback.opened|chargeback.won|chargeback.lost|chargeback.canceled\",\n \"infraction_id\": \"abc-uuid-1234\",\n \"transaction_id\": \"tx_xyz789\",\n \"status\": \"resolved\",\n \"outcome\": \"won\",\n \"amount\": \"25.00\",\n \"currency\": \"BRL\",\n \"resolved_at\": \"2026-05-05T10:00:00Z\"\n}" }, "url": { "raw": "" }, "description": "Infração resolvida. `outcome`: `won` (saldo desbloqueado) ou `lost` (saldo debitado/refundado pro pagador)." }, "response": [] } ], "description": "## Webhooks que BSPay envia ao seu endpoint\n\nBSPay POSTa pra URL configurada na credencial. Validar HMAC.\n\n### Headers comuns\n```\nContent-Type: application/json\nX-Webhook-Event: \nX-Webhook-Signature: hex(hmac_sha256(rawBody, callback_secret))\nX-Webhook-Timestamp: \n```\n\n### Validação PHP\n```php\n$rawBody = file_get_contents('php://input');\n$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';\n$ts = (int) ($_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? 0);\n\nif (abs(time() - $ts) > 300) { http_response_code(401); exit; }\n\n$expected = hash_hmac('sha256', $rawBody, $YOUR_CALLBACK_SECRET);\nif (!hash_equals($expected, $sig)) { http_response_code(401); exit; }\n```\n\n### Eventos\n| Event | Quando |\n|--|--|\n| `cashin.confirmed` | PIX/crypto/SPEI recebido |\n| `cashin.refunded` | Cashin estornado |\n| `cashout.confirmed` | Saque concluído (com hash/tx_hash) |\n| `cashout.failed` | Saque falhou — saldo refundado AUTO |\n| `cashin.confirmed` | Depósito em wallet fixa |\n| `transfer.confirmed` | Transferência interna concluída |\n| `conversion.confirmed` | Conversão FX concluída |\n| `chargeback.opened` | Nova infração PIX |\n| `chargeback.opened|chargeback.won|chargeback.lost|chargeback.canceled` | Infração resolvida |\n\n### Retry\n5 tentativas: 1min/5min/15min/1h/6h. Considera ack quando recebe HTTP 2xx.\n\n### Idempotência\nUse `transaction_id` como chave única (Redis NX, DB UNIQUE)." } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://api.bspay.co" }, { "key": "client_id", "value": "" }, { "key": "client_secret", "value": "" }, { "key": "token", "value": "" }, { "key": "signing_key", "value": "" }, { "key": "callback_secret", "value": "" }, { "key": "signature", "value": "" }, { "key": "timestamp", "value": "" }, { "key": "nonce", "value": "" } ] }