Integração por API

Envie pagamentos da sua conta da Volet.com para usuários da Volet.com e carteiras cripto externas pela Merchant API.

A Mass Payout API permite que seu aplicativo crie, valide e acompanhe transações de pagamento de forma programática.

Você pode usar a API em três cenários principais:

Pagamentos a usuários da Volet.com — envie fundos da sua conta da Volet.com para outra conta da Volet.com.
Pagamentos em cripto sem conversão — envie criptomoedas do mesmo saldo cripto para uma carteira cripto externa.
Pagamentos em cripto com conversão — envie criptomoedas para uma carteira cripto externa a partir de outro saldo compatível, como USD, EUR, USDT ou outra criptomoeda.

Como funcionam os pagamentos em massa pela API

A Merchant API cria uma transação de pagamento por requisição.

Para lotes de pagamentos em massa, seu backend prepara uma lista de destinatários e cria uma transação de pagamento separada para cada item do lote.

Um fluxo típico em lote:

Prepare um lote de pagamentos no seu sistema.
Consulte os saldos disponíveis nas suas carteiras da Volet.com.
Consulte limites, tarifas e cotações quando necessário.
Valide cada pagamento antes de criá-lo.
Crie as transações de pagamento pela API.
Armazene no seu sistema os IDs de transação retornados.
Acompanhe o status dos pagamentos pela API.
Concilie os pagamentos concluídos, com falha, cancelados ou estornados.

Antes de começar

Para enviar pagamentos em massa pela API, você precisa de:

Uma conta da Volet.com verificada.
Uma API configurada na seção Ferramentas de pagamento.
Saldo suficiente na sua conta da Volet.com.
Os dados dos destinatários exigidos por cada método de pagamento.

Veja Ativar pagamentos em massa para criar e configurar sua API.

Autenticação

As requisições à Merchant API exigem cabeçalhos de autenticação.

Inclua os seguintes cabeçalhos em cada requisição à API:

Cabeçalho	Descrição
`Api-Name`	Nome da API configurado na sua conta da Volet.com.
`Account-Email`	E-mail da conta da Volet.com dona da API.
`Authentication-Token`	Token de autenticação da requisição, gerado com o segredo da sua API.

Mantenha o segredo da API em sigilo. Nunca exponha credenciais da API nem tokens de autenticação em código frontend, apps móveis, bots ou scripts do lado do cliente.

Fluxo de pagamento recomendado

Antes de criar os pagamentos, seu backend deve validar e preparar cada item.

Fluxo recomendado:

Consulte os saldos das carteiras.
Consulte os limites mínimos do método de pagamento e da moeda escolhidos.
Consulte as tarifas ou taxas.
Consulte a cotação se o pagamento usar conversão.
Valide a solicitação de pagamento.
Crie a transação de pagamento.
Armazene o transactionId retornado.
Consulte periodicamente o status da transação até o pagamento atingir um estado final.

Etapa 1: consultar os saldos das carteiras

Use este método para consultar os saldos disponíveis nas suas carteiras da Volet.com antes de criar pagamentos.

Endpoint:

GET /api/account/balances

Exemplo de resposta:

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "amount": 2500,
    "currency": "USDT"
  }
]

Use walletId como carteira de origem ao criar as solicitações de pagamento.

Etapa 2: consultar limites e tarifas

Antes de enviar pagamentos, consulte os limites mínimos e as tarifas do método de pagamento e do par de moedas escolhidos.

Limites mínimos:

GET /api/account/limits/min

Tarifas:

GET /api/account/tariffs

Use estes métodos para evitar erros na criação de pagamentos causados por valores, moedas ou métodos de pagamento não compatíveis.

Etapa 3: consultar a cotação

Consulte a cotação quando o pagamento exigir conversão.

Endpoint:

POST /api/exchange-rate/information

Use antes de criar pagamentos em que a moeda de origem e a moeda do pagamento são diferentes.

Exemplos de uso:

Enviar USDT para uma carteira cripto externa a partir de um saldo em USD.
Enviar BTC para uma carteira cripto externa a partir de um saldo em EUR.
Converter um saldo cripto compatível em outra moeda de pagamento.

Método 1: enviar pagamentos a usuários da Volet.com

Use este método quando o destinatário tem uma conta da Volet.com.

Os fundos são transferidos internamente da sua conta da Volet.com para a conta da Volet.com do destinatário.

Este método não exige confirmação na blockchain e não usa endereços de carteiras cripto externas.

Validar pagamento a um usuário da Volet.com

Valide o pagamento antes de criar a transação.

Endpoint:

POST /api/withdrawal/validation/internal-other

Exemplo de requisição:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

A validação verifica os dados do pagamento sem criar uma transação.

Criar pagamento a um usuário da Volet.com

Após a validação bem-sucedida, crie a transação de pagamento.

Endpoint:

POST /api/withdrawal/internal-other

Exemplo de requisição:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Exemplo de resposta:

{
  "transactionId": "11111111-1111-4111-8111-111111111111",
  "paymentMethodType": "INTERNAL_OTHER",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 25,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.13,
  "comment": "Payout batch 2026-06-26 / recipient 001"
}

Armazene o transactionId retornado no seu sistema e use-o para acompanhar o status do pagamento.

Opcional: validar as contas da Volet.com dos destinatários

Se o seu fluxo coleta os e-mails dos destinatários antes de criar os pagamentos, você pode verificar se as contas da Volet.com existem antes de criar as solicitações.

Endpoint:

GET /api/account/exists

Você também pode conferir os dados do titular da conta quando o seu fluxo exigir verificações adicionais do destinatário.

Endpoint:

GET /api/account/matching

Use estes métodos para reduzir pagamentos com falha causados por dados incorretos do destinatário.

Método 2: enviar pagamentos em cripto sem conversão

Use este método quando quiser enviar criptomoedas do mesmo saldo cripto para uma carteira cripto externa.

Por exemplo:

Enviar USDT do seu saldo em USDT para um endereço USDT TRC-20 externo.
Enviar BTC do seu saldo em BTC para um endereço BTC externo.
Enviar ETH do seu saldo em ETH para um endereço ETH externo.

O destinatário não precisa de conta da Volet.com.

Validar pagamento em cripto sem conversão

Valide o pagamento em cripto antes de criar a transação.

Endpoint:

POST /api/withdrawal/validation/cryptowallet

Exemplo de requisição:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Use o destCurrency correto para o token e a rede blockchain do pagamento.

Em redes que exigem memo, tag de destino ou identificador semelhante, inclua-o no campo address.memo.

Exemplo:

{
  "address": {
    "address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
    "memo": "123456"
  }
}

Criar pagamento em cripto sem conversão

Após a validação bem-sucedida, crie a transação de pagamento.

Endpoint:

POST /api/withdrawal/cryptowallet

Exemplo de requisição:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Exemplo de resposta:

{
  "transactionId": "22222222-2222-4222-8222-222222222222",
  "paymentMethodType": "CRYPTO_WALLET",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000002",
  "fullCommission": 0.25,
  "comment": "Payout batch 2026-06-26 / recipient 002"
}

Método 3: enviar pagamentos em cripto com conversão

Use este método quando o saldo de origem e a moeda do pagamento forem diferentes.

Por exemplo:

Enviar USDT para uma carteira externa a partir de um saldo em USD.
Enviar BTC para uma carteira externa a partir de um saldo em EUR.
Enviar USDC por uma rede compatível a partir de outro saldo compatível.

O destinatário recebe criptomoedas em uma carteira cripto externa. A conversão é feita durante o fluxo de pagamento.

Validar pagamento em cripto com conversão

Valide o pagamento antes de criar a transação.

Endpoint:

POST /api/withdrawal/validation/crypto-external

Exemplo de requisição:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Use srcCurrency para definir a moeda do saldo de origem e destCurrency para definir a criptomoeda e a rede enviadas ao destinatário.

Criar pagamento em cripto com conversão

Após a validação bem-sucedida, crie a transação de pagamento.

Endpoint:

POST /api/withdrawal/crypto-external

Exemplo de requisição:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Exemplo de resposta:

{
  "transactionId": "33333333-3333-4333-8333-333333333333",
  "paymentMethodType": "CRYPTO_EXTERNAL",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.50,
  "comment": "Payout batch 2026-06-26 / recipient 003"
}

Campos da requisição

Campos comuns das solicitações de pagamento:

Campo	Obrigatório	Usado em	Descrição
`srcWalletId`	Não	Todos os métodos	ID da carteira de origem na sua conta da Volet.com.
`amount`	Sim	Todos os métodos	Valor do pagamento. A forma como ele é interpretado depende de `action`.
`action`	Sim	Todos os métodos	Modo do valor. Valores possíveis: `GIVE`, `GET`.
`note`	Não	Todos os métodos	Observação interna ou descrição do pagamento.
`srcCurrency`	Não	Pagamentos a usuários da Volet.com, pagamentos em cripto com conversão	Moeda de origem do pagamento.
`destCurrency`	Sim	Todos os métodos	Moeda creditada ao destinatário ou enviada à carteira cripto externa.
`destEmail`	Não	Pagamentos a usuários da Volet.com	E-mail da conta da Volet.com do destinatário.
`destWalletId`	Não	Pagamentos a usuários da Volet.com	ID da carteira do destinatário, quando aplicável.
`address.address`	Sim	Pagamentos em cripto externos	Endereço da carteira cripto do destinatário.
`address.memo`	Não	Pagamentos em cripto externos	Memo, tag de destino ou identificador semelhante, se exigido pela rede escolhida.
`receiverInfo`	Não	Pagamentos em cripto externos	Informações do destinatário, como nome, e-mail, data de nascimento ou razão social, quando exigidas.

`GIVE` e `GET`

Use action para definir como o valor do pagamento deve ser interpretado.

Ação	Significado
`GIVE`	O valor é tratado como o valor a enviar a partir da origem.
`GET`	O valor é tratado como o valor que o destinatário deve receber, quando compatível.

Em pagamentos com conversão de moeda, consulte a cotação antes de criar o pagamento. Assim seu sistema pode mostrar ou armazenar os valores de origem e de destino previstos antes de a transação ser criada.

Acompanhamento do status dos pagamentos

Depois de criar um pagamento, armazene o transactionId retornado.

Use a consulta de transações para obter o status mais recente do pagamento.

Endpoint:

GET /api/transactions/{id}

Você também pode pesquisar no histórico de transações.

Endpoint:

GET /api/transactions

Filtros úteis:

Filtro	Descrição
`paymentDirections`	Filtrar por `DEPOSIT` ou `WITHDRAWAL`.
`transactionStatus`	Filtrar por status da transação.
`wallets`	Filtrar por IDs de carteira.
`startDate` / `endDate`	Filtrar por período de criação.
`searchLabel`	Pesquisar por rótulo de texto, quando aplicável.
`offset` / `limit`	Paginar os resultados.
`sortOrder`	Ordenar os resultados por data de criação.

Status das transações

Use o status da transação para atualizar o status do pagamento no seu próprio sistema.

Status	Significado	Ação recomendada
`CREATED`	A transação de pagamento foi criada.	Armazene a transação e continue acompanhando.
`READY_TO_PROCESS`	O pagamento está pronto para processamento.	Continue acompanhando.
`PENDING`	O pagamento está pendente.	Continue acompanhando.
`PROCESSING`	O pagamento está em processamento.	Continue acompanhando.
`EXCHANGING`	A conversão de moeda está em andamento.	Continue acompanhando.
`COMPLETED`	O pagamento foi concluído.	Marque o pagamento como concluído no seu sistema.
`CANCELLING`	O cancelamento está em andamento.	Aguarde o status final.
`CANCELED`	O pagamento foi cancelado.	Marque o pagamento como cancelado.
`REFUNDING`	O estorno está em andamento.	Aguarde o status final.
`REFUNDED`	O pagamento foi estornado.	Marque o pagamento como estornado.

Só considere o pagamento concluído depois que o status mudar para COMPLETED.

Cancelar pagamentos

Algumas transações podem ser canceladas enquanto o cancelamento ainda for permitido.

Endpoint:

DELETE /api/transactions/{transactionId}

A possibilidade de cancelamento depende do método de pagamento, do status da transação e da etapa de processamento.

Não conte com o cancelamento de pagamentos em cripto depois que a transação for transmitida para a blockchain. Confirme todos os endereços, moedas, redes e valores dos destinatários antes de criar o pagamento.

Recomendações para processamento em lote

Em pagamentos em massa, seu backend deve gerenciar o ciclo de vida do lote.

Abordagem recomendada:

Atribua um ID interno ao lote de pagamentos.
Atribua um ID interno a cada pagamento.
Valide cada item antes de criar as transações.
Crie transações apenas para os itens validados.
Armazene a correspondência entre o ID interno do item e o transactionId retornado.
Acompanhe cada transação separadamente.
Tente de novo apenas os itens com falha ou não criados.
Concilie os status finais antes de marcar o lote como concluído.

Evite enviar pagamentos duplicados. Se seu aplicativo repetir uma requisição após um timeout, verifique primeiro se já foi criada uma transação para aquele item.

Tratamento de erros

Os erros da Merchant API retornam respostas de erro estruturadas.

Casos de erro comuns:

Status HTTP	Significado
`400`	A requisição está malformada ou contém parâmetros inválidos.
`401`	Os cabeçalhos de autenticação estão ausentes ou são inválidos.
`403`	A API não tem permissão para usar a operação solicitada.
`404`	O recurso solicitado não foi encontrado.
`500`	Erro inesperado do servidor.

Quando ocorrer um erro:

Registre o errorId para suporte e diagnóstico.
Verifique o errorField para identificar o campo da requisição relacionado ao erro.
Não crie automaticamente um pagamento substituto até confirmar que nenhuma transação foi criada.
Tente de novo apenas quando for seguro.

Checklist de testes

Antes de enviar pagamentos em massa reais, teste o fluxo completo.

Para pagamentos a usuários da Volet.com:

Validação da conta do destinatário.
Validação do pagamento.
Criação do pagamento.
Acompanhamento do status da transação.
Cenários concluídos, cancelados e com falha.

Para pagamentos em cripto sem conversão:

Escolha correta do token e da rede.
Tratamento de endereço e memo.
Validação do pagamento.
Criação do pagamento.
Acompanhamento da transação na blockchain.
Tratamento de endereço incorreto ou rede não compatível.

Para pagamentos em cripto com conversão:

Consulta de saldo.
Consulta da cotação.
Validação do pagamento.
Criação do pagamento.
Status EXCHANGING e COMPLETED.
Conciliação dos valores entre as moedas de origem e de destino.

Para processamento em lote:

Tratamento de falhas parciais no lote.
Lógica de novas tentativas.
Prevenção de duplicidades.
Correspondência interna entre lotes e transações.
Relatório final de conciliação.

Observações importantes

A API cria uma transação de pagamento por requisição.
Seu backend é responsável pela orquestração dos lotes.
Sempre valide os pagamentos antes de criar as transações.
Sempre armazene os valores de transactionId retornados.
Use a consulta de transações ou o histórico para acompanhar o status final.
Não marque um pagamento como concluído até o status ser COMPLETED.
Em pagamentos em cripto, sempre verifique o endereço, o token, a rede e o memo do destinatário antes de criar a transação.
Enviar cripto para o endereço ou a rede errados pode causar a perda permanente dos fundos.
As credenciais da API nunca devem ser expostas no código frontend.

Ativar pagamentos em massa — configure sua API antes de enviar pagamentos
Enviar pagamentos a usuários da Volet.com — envie pagamentos internos para contas da Volet.com
Enviar pagamentos cripto custodiais — envie cripto para carteiras externas a partir da sua conta da Volet.com
Visão geral dos pagamentos em massa — compare os métodos e modelos de pagamento
Referência da API — documentação completa de métodos, parâmetros e respostas

Como funcionam os pagamentos em massa pela API​

Antes de começar​

Autenticação​

Fluxo de pagamento recomendado​

Etapa 1: consultar os saldos das carteiras​

Etapa 2: consultar limites e tarifas​

Etapa 3: consultar a cotação​

Método 1: enviar pagamentos a usuários da Volet.com​

Validar pagamento a um usuário da Volet.com​

Criar pagamento a um usuário da Volet.com​

Opcional: validar as contas da Volet.com dos destinatários​

Método 2: enviar pagamentos em cripto sem conversão​

Validar pagamento em cripto sem conversão​

Criar pagamento em cripto sem conversão​

Método 3: enviar pagamentos em cripto com conversão​

Validar pagamento em cripto com conversão​

Criar pagamento em cripto com conversão​

Campos da requisição​

GIVE e GET​

Acompanhamento do status dos pagamentos​

Status das transações​

Cancelar pagamentos​

Recomendações para processamento em lote​

Tratamento de erros​

Checklist de testes​

Observações importantes​

Relacionados​

Como funcionam os pagamentos em massa pela API

Antes de começar

Autenticação

Fluxo de pagamento recomendado

Etapa 1: consultar os saldos das carteiras

Etapa 2: consultar limites e tarifas

Etapa 3: consultar a cotação

Método 1: enviar pagamentos a usuários da Volet.com

Validar pagamento a um usuário da Volet.com

Criar pagamento a um usuário da Volet.com

Opcional: validar as contas da Volet.com dos destinatários

Método 2: enviar pagamentos em cripto sem conversão

Validar pagamento em cripto sem conversão

Criar pagamento em cripto sem conversão

Método 3: enviar pagamentos em cripto com conversão

Validar pagamento em cripto com conversão

Criar pagamento em cripto com conversão

Campos da requisição

`GIVE` e `GET`

Acompanhamento do status dos pagamentos

Status das transações

Cancelar pagamentos

Recomendações para processamento em lote

Tratamento de erros

Checklist de testes

Observações importantes

Relacionados