Pular para o conteúdo principal
O sandbox é um deployment separado do SpherePay que se comporta como produção e não movimenta nada de valor. Você o usa para construir sua integração, exercitar o ciclo de vida de uma transferência e rodar sua suíte de testes sem clientes reais, fundos reais ou documentos de identidade reais. Os corpos das suas requisições são idênticos nos dois lugares. Troque tanto a URL base quanto a chave: cada host aceita apenas as chaves do seu próprio ambiente.

O que é diferente

Todo o resto — endpoints, formatos de requisição, formatos de resposta, eventos de webhook, envelopes de erro — é o mesmo código. Esse é o ponto: o que você constrói no sandbox é o que roda em produção.

Obtenha uma chave de sandbox

As chaves de sandbox são criadas no dashboard, em modo sandbox, em Developers → API Keys. Elas começam com sandbox_secret_ para que você reconheça de imediato que a chave não é uma credencial de produção. Uma chave de sandbox funciona apenas em api.sandbox.spherepay.co, e uma chave de produção funciona apenas em api.spherepay.co. Não há roteamento entre os dois: apresente a chave errada e a requisição é rejeitada exatamente como qualquer chave desconhecida seria.
Mantenha as chaves de sandbox e de produção em configurações separadas. Apontar uma suíte de testes para produção porque uma chave foi colada na variável de ambiente errada movimenta dinheiro real.

Escolha uma rede

Envie os mesmos identificadores de rede que você usa em produção. O sandbox os resolve para redes de teste:
No sandbox isso chega à Sepolia. sol chega à Solana Devnet. Uma requisição de sandbox que nomeia uma rede sem configuração de teste é rejeitada em vez de cair em uma rede mainnet. Você não alcança a mainnet com uma chave de sandbox.

Emita tokens de teste

SPHEREUSDC é a stablecoin de teste do sandbox. Emita-a para qualquer endereço em qualquer uma das duas redes de teste com o faucet:
Gere a chave de idempotência uma vez por emissão e reutilize-a se tentar de novo, para que uma resposta perdida não emita duas vezes. A resposta é 202 Accepted com um id de emissão. A emissão é assíncrona, então consulte para obter o hash da transação:
amount usa 1000 por padrão e aceita no máximo 1000 por chamada. Uma emissão que levaria a carteira acima de 10000 SPHEREUSDC, contando as emissões pendentes, é recusada. Envie um cabeçalho Idempotency-Key para que uma nova tentativa retorne a mesma emissão em vez de emitir duas vezes. Reutilizar uma chave com parâmetros diferentes retorna 409.
O faucet emite tokens, não gas. Financie o saldo nativo da carteira a partir de um faucet público da Sepolia ou da Solana Devnet antes de enviar uma transação a partir dela.

Avance uma transferência

Em produção uma transferência percorre seu ciclo de vida conforme os depósitos chegam e os trilhos liquidam. No sandbox você a avança:
Cada avanço executa a mesma máquina de estados e o mesmo pipeline de webhooks que produção, então seus handlers de webhook recebem os eventos que receberão em produção, nos mesmos formatos. O endpoint é idempotente por estado. Avançar para o status em que a transferência já está retorna o resultado original e não emite nada, então uma chamada repetida ou concorrente é segura. Apenas algumas transições são válidas a partir de um dado status. Uma inválida retorna transfer/invalid-transition em vez de forçar a transferência para um estado inconsistente.
Essas rotas existem apenas no deployment de sandbox. Em api.spherepay.co elas retornam 404, então não há como avançar uma transferência real manualmente.

Endpoints de simulação

Estes endpoints existem apenas em https://api.sandbox.spherepay.co: A simulação de depósitos para offloader wallets e contas virtuais chegará em breve.

Limites de taxa

As rotas exclusivas do sandbox são limitadas por aplicação, não por IP, para que um runner de CI compartilhado não limite a si mesmo: Todos os demais endpoints seguem os limites de Limites de Taxa.

O que o sandbox não faz

  • Ele não contém fundos reais, então nada que você faça no sandbox move dinheiro.
  • Ele não executa verificação de identidade real. Os clientes que você cria não são analisados pela Sumsub.
  • Ele não é um ambiente de staging do SpherePay. Ele é implantado a partir do mesmo branch que produção, ao mesmo tempo.
Última modificação em 16 de novembro de 2026