Saltar para o conteúdo principal
Em resumo
A API de Saque em Fiat da Blockradar converte stablecoins suportadas em fiat e envia para contas bancárias, mobile money e outros rails locais. O fluxo v2 descobre os métodos de pagamento disponíveis para um corredor, retorna um schema descrevendo exatamente o que cada método precisa, resolve campos como o nome da conta do beneficiário e, então, cota e executa o saque a partir de uma master wallet ou child address.
Interface de Saque em Fiat da Blockradar
Os métodos de pagamento v2 retornam um JSON Schema descrevendo os detalhes do beneficiário e do pagamento que sua aplicação deve coletar. Consulte Formulários Dinâmicos para renderizar, validar, resolver e enviar esses campos. O fluxo v1 está disponível na aba v1 · Legacy, mas não é mais recomendado.

Pré-requisitos

Antes de usar o Saque em Fiat, certifique-se de ter:
1

Compliance aprovado

Conclua o processo de Due Diligence no Dashboard: My Wallets → Settings → Compliance. Os requisitos de conformidade e os processos de aprovação variam por região, então você só precisa concluir os que se aplicam aos rails locais que seu produto usa.
2

Chave de API

Obtenha sua chave de API no Dashboard da Blockradar. Acesse Developers para gerá-la.
3

Wallet criada

Crie uma wallet pelo dashboard. Você precisará do walletId para as operações de saque.
4

Asset ID

Consulte os ativos fiat suportados usando Get Supported Assets. Use o id retornado como o assetId ao longo do fluxo.

Como funciona

O fluxo v2 é orientado por corredor: você escolhe um ativo, uma moeda e um valor e, então, descobre os métodos de pagamento que suportam esse corredor e coleta exatamente o que cada método exige.

Descobrir ativos

Consulte as stablecoins suportadas para saques.

Obter moedas e taxas

Liste as moedas de pagamento suportadas e obtenha a taxa atual.

Listar métodos de pagamento

Descubra os métodos disponíveis para o ativo, a moeda e o valor.

Obter requisitos

Recupere o JSON Schema que descreve os campos que o método precisa.

Resolver e cotar

Resolva campos como o nome da conta e, então, cote taxas e câmbio.

Executar

Envie paymentMethodData para processar o saque.

Moedas fiat suportadas

As moedas variam por corredor e provedor. Sempre obtenha a lista ao vivo com Get Supported Currencies em vez de fixá-la no código. O panorama abaixo mostra USD, EUR e os principais corredores da América Latina; veja a matriz completa de fiat por blockchain na página Moedas Fiat Suportadas.

Master Wallet vs Child Address

O Saque em Fiat está disponível em dois níveis:

Master Wallet

Realize saques a partir da master wallet. Ideal para operações de tesouraria.

Child Address

Realize saques a partir de uma child address específica. Útil para fluxos por usuário.

Endpoints

Os endpoints de descoberta (ativos, moedas, taxas, métodos de pagamento, requisitos, resolução) têm escopo na master wallet. Assim que você tiver um objeto paymentMethodData validado, poderá cotar e executar a partir da master wallet ou de uma child address.

Fluxo típico

  1. Consulte os ativos suportados para escolher a stablecoin a sacar.
  2. Obtenha moedas e taxa para o corredor escolhido e guarde o sessionId retornado.
  3. Liste os métodos de pagamento usando essa sessão.
  4. Obtenha os requisitos do método selecionado para receber seu schema.
  5. Resolva campos como o nome da conta e, então, colete e valide paymentMethodData.
  6. Obtenha uma cotação usando a mesma sessão para mostrar taxas e câmbio antes da execução.
  7. Execute usando a mesma sessão e acompanhe o status com webhooks.
O endpoint de taxas v2 inicia uma sessão de roteamento de provedor. Trate o sessionId dele como a referência oficial para o restante do fluxo: ele vincula a wallet, o ativo da wallet, a moeda, o valor, o lado do valor, o provedor e a rota de conversão por 20 minutos. Não misture uma sessão com valores de roteamento de outra solicitação de taxa. Se a API retornar FIAT_WITHDRAWAL_SESSION_EXPIRED ou FIAT_WITHDRAWAL_SESSION_UNAVAILABLE, solicite uma nova taxa e reinicie o fluxo.

Etapa 1: Obter ativos suportados

Consulte as stablecoins disponíveis para saque e pegue o id desejado como o assetId.

Etapa 2: Obter moedas e taxa

Liste as moedas de pagamento suportadas e, então, obtenha a taxa atual para o ativo, a moeda e o valor.
Rate Response

Etapa 3: Listar métodos de pagamento

Descubra os métodos de pagamento disponíveis para o corredor vinculado à sessão. Passe o sessionId retornado pela Etapa 2; opcionalmente, restrinja por country ou paymentMethodCategory.
Payment Methods Response
Quando um método tem requirementsRef, procure o schema dele em data.requirements[requirementsRef]. Vários métodos podem referenciar a mesma entrada, por isso a API retorna um schema compartilhado apenas uma vez. Um método sem requirementsRef não tem requisitos de formulário.
supportsPaymentMethodResolution: true significa que o schema do método pode incluir um campo x-resolution (como uma busca de nome de conta) que você resolve antes de cotar. Consulte a Etapa 5.

Etapa 4: Ler os requisitos do método de pagamento

Leia o JSON Schema do método selecionado no registro compartilhado requirements retornado na Etapa 3. Interprete-o e preencha-o com Formulários Dinâmicos. Isso não exige outra requisição à API.
O endpoint de requisitos continua disponível quando você precisar obter diretamente o schema mais recente para um ID de método de pagamento conhecido.
Requirements Response

Etapa 5: Resolver campos e montar paymentMethodData

Colete os campos em data.schema. Quando um campo carrega x-resolution (como accountName acima), chame o endpoint de resolução assim que seus campos dependsOn forem válidos e, então, armazene o resultado nesse campo.
Resolve Response
Depois de resolver e validar, seu paymentMethodData completo fica assim:

Etapa 6: Obter uma cotação

Sempre obtenha uma cotação antes de executar para poder exibir a taxa de câmbio, as taxas e o tempo estimado de chegada ao usuário. Envie o paymentMethodData validado.
Quote Response

Fixar o valor a receber

Escolha o lado do valor ao solicitar a taxa que cria a sessão. Por padrão, amount é o valor em stablecoin que você envia (amountSide: "source"). Para entregar um valor fiat exato, defina amountSide=target na requisição de taxas. A sessão resultante preserva essa escolha na cotação e na execução.
Com amountSide: "target", o destinatário recebe exatamente o valor fiat que você especificar — 155.000 NGN no exemplo acima — e o debitAmount da cotação mostra o stablecoin que será debitado, derivado da taxa e arredondado para cima até a precisão decimal do ativo, para que o pagamento nunca fique abaixo do valor. amountSide está disponível apenas nos endpoints v2.

Etapa 7: Executar o saque

Assim que o usuário aceitar a cotação, execute com os mesmos dados. Adicione um reference opcional para idempotência e rastreamento, além de metadata e note conforme necessário.

Resposta da execução

Sacar de uma Child Address

Para pagar a partir de uma child address específica, cote e execute nos endpoints com escopo de endereço usando os mesmos corpos de requisição:

Webhooks

Acompanhe o status do saque com os seguintes eventos de webhook:

Exemplo de payload do webhook

Para configuração de webhooks, estrutura do payload e tratamento de eventos, consulte a documentação de Webhooks.

Exemplo de fluxo completo

Uma implementação v2 completa mostrando o fluxo descobrir → requisitos → resolver → cotar → executar:

Respostas de erro

Boas práticas

Experiência do usuário

  • Resolva antes de cotar: Confirme o nome da conta do beneficiário via endpoint de resolução antes de mostrar uma cotação.
  • Mostre o custo total: Exiba a taxa de câmbio, a taxa de transação, a taxa de rede e o debitAmount.
  • Exponha o estado de processamento: Use webhooks para atualizar os usuários em tempo real.

Correção

  • Mantenha uma sessão por tentativa: Passe o sessionId retornado pelas taxas pelos métodos de pagamento, pela resolução, pela cotação e pela execução.
  • Reinicie sessões expiradas: Solicite uma nova taxa em vez de tentar novamente uma sessão expirada ou indisponível.
  • Use o schema retornado: Colete apenas os campos no schema de requisitos atual. Não fixe campos de beneficiário no código — consulte Formulários Dinâmicos.
  • Preserve as strings: Envie amount e os identificadores de conta como strings para evitar perda de precisão.
  • Use referências: Acompanhe os saques com um reference único para novas tentativas seguras.
  • Confirme via webhooks: Trate offramp.success como a fonte final da verdade.

Desempenho

  • Cacheie as listas de ativos e moedas: Atualize periodicamente em vez de a cada requisição.
  • Reobtenha as taxas a cada tentativa: Uma taxa v2 cria uma sessão de roteamento de 20 minutos para aquela tentativa de saque.
  • Repita em erros transitórios: Use backoff exponencial para respostas 5xx.

Referência da API

v2 (Recomendado)

Suporte