Pular para o conteúdo principal

Integração por API

Receba pagamentos em criptomoedas de carteiras cripto externas pela Merchant API.

Na integração por API, seu aplicativo cria faturas cripto, mostra as instruções de pagamento aos clientes e acompanha o status do pagamento pela API ou por notificações na Status URL.

Você pode usar a API de três formas:

  • Somente API com consulta de status — seu aplicativo monta toda a experiência de pagamento e consulta o status do pagamento pela API.

  • Somente API com notificações na Status URL — seu aplicativo monta toda a experiência de pagamento, e uma configuração do Hosted Checkout fornece a Status URL usada para as notificações de pagamento. A página do Hosted Checkout em si não é usada.

  • API + Hosted Checkout — seu backend usa a API para acompanhar e conciliar pedidos, enquanto o Hosted Checkout oferece a página de pagamento ao cliente.

Quando usar a integração por API​

Use a integração por API quando quiser controlar o fluxo de pagamento no seu próprio site, aplicativo, bot ou agente de IA.

A integração por API é útil quando:

  • Você quer criar sua própria interface de checkout.
  • Você precisa criar faturas cripto de forma programática.
  • Você quer mostrar as instruções de pagamento dentro do seu próprio produto.
  • Você precisa acompanhar o status do pagamento pelo backend.
  • Você quer receber notificações de status dos pagamentos no seu servidor.
  • Você quer combinar o Hosted Checkout com a conciliação de pedidos no backend.

Se quiser a integração mais rápida, com uma página de pagamento pronta, use a integração do Hosted Checkout.

Modelos de integração​

ModeloExperiência do clienteResponsabilidade do backendTratamento do status
Somente API + consultaCriada pelo seu aplicativoCriar a fatura, exibir os dados de pagamento, acompanhar o statusConsultar GET /api/orders
Somente API + Status URLCriada pelo seu aplicativoCriar a fatura, exibir os dados de pagamento, processar as notificaçõesStatus URL do Hosted Checkout, com consulta pela API para conciliação
API + Hosted CheckoutHospedada pela Volet.comAcompanhar pedidos e conciliar o status do pagamentoStatus URL do Hosted Checkout, com consulta pela API para conciliação

Antes de começar​

Para receber pagamentos cripto pela API, você precisa de:

  • Uma conta da Volet.com verificada.
  • Uma API configurada na seção Ferramentas de pagamento.
  • As seguintes permissões de API:
    • Realizar transações → Aceitar pagamentos cripto — para criar faturas cripto.
    • Buscar transação — para obter os pedidos de pagamento.
  • Uma configuração do Hosted Checkout cujo nome você possa enviar como sciName.

Veja Criar um gateway de pagamento para criar e configurar sua API e o Hosted Checkout.

Exigência atual de sciName

A implementação atual de GET /api/orders exige o nome de um Hosted Checkout (sciName) para obter um pedido.

Enquanto essa exigência não for removida, crie uma configuração do Hosted Checkout e envie o nome dela como sciName ao criar as faturas cripto que você precisa acompanhar.

Não é necessário redirecionar os clientes para a página do Hosted Checkout. A configuração pode ser usada apenas para fornecer o sciName necessário e, opcionalmente, as notificações na Status URL.

Autenticação​

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

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

CabeçalhoDescrição
Api-NameNome da API configurado na sua conta da Volet.com.
Account-EmailE-mail da conta da Volet.com dona da API.
Authentication-TokenToken SHA-256 gerado a partir de password:YYYYMMDD:HH (UTC), em que a senha é a definida na sua conta Volet.com, em Ferramentas de pagamento.

Por exemplo:

SHA256("MySecret123:20261026:14")

gera:

c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd

O valor do token muda a cada hora UTC. Gere um novo token imediatamente antes de cada requisição para não reutilizar um token gerado na hora anterior.

Apenas o token gerado é enviado à API. Nunca envie a senha da sua API.

Mantenha a senha 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.

Exemplo de requisição autenticada:

curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
-H "Content-Type: application/json" \
-H "Api-Name: my-store-api" \
-H "Account-Email: [email protected]" \
-H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
-d '{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"sciName": "Store",
"orderId": "ORDER-1001"
}'

Fluxo de pagamento somente com API​

Use este fluxo quando seu aplicativo cuida de toda a experiência de pagamento cripto.

  1. Crie um pedido no seu sistema.
  2. Opcionalmente, confira os dados calculados da fatura.
  3. Crie uma fatura cripto pela API.
  4. Mostre ao cliente o endereço de pagamento, o valor, a moeda, a rede e o prazo de expiração.
  5. O cliente envia o pagamento de uma carteira cripto.
  6. Acompanhe o pagamento por GET /api/orders, por notificações na Status URL ou pelos dois.
  7. Quando o pagamento for concluído, atualize o status do pedido no seu sistema.

Etapa 1 (opcional): conferir os dados da fatura​

Antes de criar uma fatura, você pode conferir os valores calculados.

Use esta etapa para ver antecipadamente o valor do remetente, o valor do destinatário, a conversão de moeda e o prazo de expiração antes de criar a fatura de fato.

Endpoint:

POST /api/invoice/crypto-invoice/check

Veja Verificação de fatura cripto na referência da API.

Exemplo de requisição:

{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com"
}

Exemplo de resposta:

{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com",
"senderAmount": 100,
"receiverAmount": 100,
"expirationDate": "2026-01-15T10:30:00",
"expirationDateMillis": 1768473000000
}

Esta etapa não cria um endereço de pagamento nem inicia o pagamento.

Etapa 2: criar uma fatura cripto​

Crie uma fatura cripto quando o cliente estiver pronto para pagar.

Endpoint:

POST /api/invoice/crypto-invoice/deposit

Veja Criação de fatura cripto de depósito na referência da API.

Exemplo de requisição:

{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com"
}

A resposta traz os dados de pagamento que seu aplicativo deve mostrar ao cliente.

Exemplo de resposta:

{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com",
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"addressOldFormat": null,
"destinationTag": null,
"senderAmount": 100,
"receiverAmount": 100,
"expirationDate": "2026-01-15T10:30:00",
"expirationDateMillis": 1768473000000
}

Os valores destes exemplos são ilustrativos. Os valores reais de senderAmount e receiverAmount dependem das moedas escolhidas, da taxa de câmbio e das taxas aplicáveis.

Campos da requisição da fatura​

CampoObrigatórioDescrição
receiverCurrencySimMoeda creditada na sua conta da Volet.com após a conclusão do pagamento. Veja os valores aceitos na referência da API.
senderCurrencySimMoeda e rede que o cliente deve usar para pagar, por exemplo USDT_TRC20.
amountSimValor do pagamento. A forma como ele é interpretado depende de transferAction.
transferActionSimDefine a qual lado amount se refere. Valores possíveis: GIVE, GET. Veja GIVE e GET.
noteNãoObservação do pagamento ou descrição do pedido. Até 255 caracteres.
sciNameNão*Nome do Hosted Checkout definido na sua conta da Volet.com. Atualmente é obrigatório se você quiser obter o pedido por GET /api/orders ou receber notificações na Status URL pela configuração do Hosted Checkout.
orderIdNão*ID interno do seu pedido, até 64 caracteres. Necessário para obter o pagamento depois com GET /api/orders. Use um valor único para cada pagamento.
subMerchantURLNãoURL do site do sublojista, se o pagamento for processado em nome de outro lojista. Veja Sublojistas.

* O endpoint de criação de faturas pode aceitar o campo como opcional, mas ele é obrigatório para os fluxos de acompanhamento descritos neste guia.

GIVE e GET​

transferAction determina em qual moeda o amount da requisição é expresso.

ValorO que amount significa
GIVEO valor que o cliente envia, expresso em senderCurrency.
GETO valor a ser creditado na sua conta da Volet.com, expresso em receiverCurrency.

Os valores finais de senderAmount e receiverAmount retornados pela API podem ser diferentes por causa da taxa de câmbio e das taxas aplicáveis.

Códigos de moeda​

Alguns códigos de criptomoedas incluem a rede blockchain depois de um sublinhado.

Por exemplo:

  • USDT_TRC20 — USDT na Tron.
  • USDT_ERC20 — USDT na Ethereum.
  • USDC_SOL — USDC na Solana.

Os demais ativos usam um único código de moeda, como BTC, ETH ou TON.

Veja os valores aceitos em Moedas e tokens suportados e na referência da API.

Campos da resposta da fatura​

CampoDescrição
addressEndereço cripto para onde o cliente deve enviar o pagamento.
addressOldFormatFormato alternativo do endereço, se existir para a rede escolhida.
destinationTagTag de destino, memo ou identificador adicional exigido por algumas redes.
senderAmountValor que o cliente deve enviar.
senderCurrencyMoeda e rede que o cliente deve usar.
receiverAmountValor que deve ser creditado na sua conta.
receiverCurrencyMoeda que deve ser creditada na sua conta.
expirationDateData e hora de expiração da fatura.
expirationDateMillisExpiração da fatura como timestamp Unix em milissegundos.

Sempre mostre exatamente senderAmount, senderCurrency, address e destinationTag, se ele for retornado.

Use expirationDateMillis para calcular e exibir a expiração da fatura.

Etapa 3: mostrar as instruções de pagamento​

No modo somente API, seu aplicativo é responsável por mostrar as instruções de pagamento ao cliente.

Mostre no mínimo:

  • O valor a enviar.
  • A moeda e a rede blockchain.
  • O endereço cripto.
  • A tag de destino ou o memo, se necessário.
  • O prazo de expiração.
  • Um aviso para enviar os fundos apenas pela rede selecionada.

Exemplo:

Send exactly 100 USDT on Tron (TRC-20) to:

TXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This invoice expires at 2026-01-15 10:30 UTC.

Do not send funds on another network.

Em redes que exigem tag de destino ou memo, mostre-o com destaque ao lado do endereço.

Etapa 4: consultar o status do pagamento​

Depois de criar a fatura, seu backend pode obter o pedido de pagamento pela API.

Endpoint:

GET /api/orders

Veja Consulta de pedido de pagamento na referência da API.

Parâmetros de consulta atuais:

ParâmetroObrigatórioDescrição
orderIdSimIdentificador do pedido do lojista, até 64 caracteres.
sciNameSim*Nome do Hosted Checkout associado à fatura.

* Atualmente, a implementação da API exige sciName para obter um pedido.

Exemplo de requisição:

GET /api/orders?orderId=ORDER-1001&sciName=Store
Solução temporária para sciName

No momento, um pedido criado pela API não pode ser obtido de forma confiável apenas pelo orderId.

Crie uma configuração do Hosted Checkout, use o nome dela como sciName ao criar a fatura cripto e envie o mesmo valor para GET /api/orders.

Você pode usar essa solução sem exibir a página do Hosted Checkout ao cliente.

Exemplo de resposta:

{
"orderId": "ORDER-1001",
"sciName": "Store",
"paymentStatus": "PENDING",
"paymentMethod": "CRYPTO_INVOICE",
"paymentCreated": "2026-01-15T10:00:00",
"transaction": {
"id": "11111111-1111-4111-8111-111111111111",
"status": "PENDING",
"senderAmount": 100,
"senderCurrency": "USDT_TRC20",
"receiverAmount": 100,
"receiverCurrency": "USD",
"created": "2026-01-15T10:00:00"
},
"invoice": {
"created": "2026-01-15T10:00:00",
"received": "2026-01-15T10:12:00",
"invoiceStatus": "RECEIVED",
"externalStatus": "PAYMENT_RECEIVED",
"penalties": [],
"cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"initialSenderAmount": 100,
"actualReceivedAmount": 100,
"senderCurrency": "USDT_TRC20",
"cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
}
}

Se nenhum pedido correspondente for encontrado, a API pode retornar 404. Confira o orderId e o sciName antes de criar outra fatura para o mesmo pedido.

Status do pagamento​

Use o paymentStatus de nível superior para saber se o pagamento foi concluído.

StatusSignificadoAção recomendada
PENDINGO pagamento ainda não chegou a um estado final de conclusão.Mantenha o pedido pendente.
COMPLETEDO pagamento foi concluído com sucesso.Marque o pedido como pago e entregue o produto ou serviço.
CANCELEDO pagamento foi cancelado.Não entregue o pedido.
REFUNDEDO pagamento foi reembolsado.Atualize o pedido de acordo com seu fluxo de reembolso.

Só considere um pedido pago quando paymentStatus for COMPLETED.

A resposta também inclui campos específicos da fatura, como invoiceStatus, externalStatus e penalties. Eles podem trazer informações adicionais sobre a fatura cripto.

Não deduza o status final do pedido a partir de valores não documentados de externalStatus ou penalties. Use-os apenas se a sua integração tratar explicitamente os valores retornados pela API.

cryptoCurrencyTransactionId é o identificador da transação cripto retornado pela API. Não presuma que o formato dele é o de um hash de transação da blockchain, a menos que isso tenha sido confirmado para o fluxo de pagamento escolhido.

Receber notificações na Status URL​

Consultar GET /api/orders não é a única forma de acompanhar as faturas cripto criadas pela API.

No momento, a configuração da API na sua conta da Volet.com não tem campos para URLs de webhook. Porém, você pode usar a Status URL configurada para um gateway do Hosted Checkout para receber notificações de status dos pagamentos das faturas criadas pela API.

Neste fluxo, não é preciso exibir o Hosted Checkout nem redirecionar os clientes para ele.

Configurar as notificações na Status URL​

  1. Crie uma configuração do Hosted Checkout na sua conta da Volet.com.
  2. Configure a Status URL dela e selecione o método HTTP necessário.
  3. Use o nome do Hosted Checkout como sciName ao criar faturas cripto pela API.
  4. Mantenha o fluxo de pagamento do cliente no seu próprio aplicativo.
  5. Quando o status do pagamento muda, a Volet.com envia uma notificação para a Status URL configurada nesse Hosted Checkout.
  6. Verifique a assinatura da notificação antes de atualizar o pedido no seu sistema.
  7. Use GET /api/orders como verificação de conciliação ou alternativa quando necessário.

Exemplo de requisição de fatura:

{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001"
}

Neste exemplo, Store é o nome da configuração do Hosted Checkout que contém a Status URL.

O cliente continua vendo a sua própria interface de pagamento. A página de pagamento do Hosted Checkout não é aberta.

observação

Assim, numa integração somente com API, o mesmo sciName tem duas funções:

  • Permite que a implementação atual de GET /api/orders encontre o pedido.
  • Vincula a fatura criada pela API à configuração do Hosted Checkout usada para as notificações na Status URL.

Para os parâmetros das notificações e a verificação da assinatura, veja Integração do Hosted Checkout.

Consulta e notificações na Status URL​

Você pode usar:

  • A consulta pela API.
  • As notificações na Status URL.
  • As duas juntas.

Em integrações que usam notificações na Status URL, a consulta pela API ajuda na conciliação se uma notificação atrasar ou se o seu endpoint ficar temporariamente indisponível.

Não crie uma fatura duplicada só porque uma consulta de status ou a entrega de uma notificação falhou.

Fluxo API + Hosted Checkout​

Use este modelo quando quiser que o próprio Hosted Checkout ofereça a página de pagamento ao cliente, enquanto seu backend usa a API para acompanhamento e conciliação.

O fluxo de pagamento:

  1. Crie um pedido no seu sistema.
  2. Redirecione o cliente para o Hosted Checkout com a sua integração do Hosted Checkout.
  3. Envie seu orderId na solicitação de pagamento do Hosted Checkout.
  4. O cliente conclui o pagamento na página do Hosted Checkout.
  5. A Volet.com envia uma notificação de status do pagamento para a sua Status URL.
  6. Seu backend verifica a assinatura da notificação.
  7. Seu backend atualiza o status do pedido.
  8. Opcionalmente, seu backend consulta o pedido pela API para conciliação.

Nesse modelo, o Hosted Checkout cuida de:

  • A página de pagamento.
  • A escolha do método de pagamento.
  • As instruções de pagamento.
  • Os redirecionamentos do cliente.

A API ainda pode ser usada para obter o pedido de pagamento pelo orderId e pelo sciName e conciliar o status no seu sistema.

Tratamento do status com o Hosted Checkout​

Ao usar a página do Hosted Checkout, não dependa apenas dos redirecionamentos para a Success URL ou a Failed URL.

Os redirecionamentos do cliente fazem parte do fluxo do navegador e nem sempre chegam ao seu servidor.

Use a notificação na Status URL para atualizar o pedido no backend e a consulta de pedidos pela API para conciliação quando necessário.

Abordagem recomendada:

  1. Receba a notificação do Hosted Checkout na Status URL.
  2. Verifique a assinatura da notificação.
  3. Atualize o pedido se a notificação for válida.
  4. Use GET /api/orders como alternativa ou verificação de conciliação.

Veja Integração do Hosted Checkout para o conteúdo da notificação e as regras de verificação da assinatura.

Tratamento de erros​

Os erros da Merchant API usam uma resposta estruturada com um ou mais erros em data.errors.

Exemplo de estrutura:

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}

Campos do erro:

CampoDescrição
errorMessageCódigo de erro legível por máquina retornado pela API.
errorTypeCategoria do erro.
errorIdIdentificador do erro, que pode ser incluído em logs e solicitações de suporte.
errorDescriptionDescrição do erro legível por pessoas.
errorFieldCampo da requisição relacionado ao erro, se disponível.
paramsParâmetros adicionais associados ao erro, se disponíveis.
requestParamsParâmetros da requisição associados ao erro, se disponíveis.

Respostas HTTP comuns:

Status HTTPSignificado
400A requisição está malformada ou contém parâmetros inválidos.
401Os cabeçalhos de autenticação estão ausentes ou são inválidos.
404O recurso solicitado não foi encontrado.
500Erro inesperado do servidor.

Os valores exatos de errorMessage dependem do endpoint e do erro. Não derive um código de erro do aplicativo apenas a partir do status HTTP.

Quando ocorrer um erro:

  • Registre o errorId para suporte e diagnóstico.
  • Verifique o errorField quando disponível.
  • No tratamento programático de erros, use errorMessage, não errorDescription.
  • Não crie automaticamente uma fatura duplicada após uma falha de requisição com resultado incerto.
  • Tente de novo apenas quando for seguro.

Testes e sandbox​

No momento, a Volet.com não oferece um sandbox nem um ambiente de staging para testes de integração.

Se você usa o Hosted Checkout, pode ver uma prévia da página de pagamento do cliente na página do Hosted Checkout para desenvolvedores. A prévia não é um sandbox e não substitui os testes de integração.

Para conhecer a API, o Hosted Checkout e o fluxo de pagamento antes de entrar em produção, fale com a equipe de vendas da Volet.com.

Checklist de testes​

Antes de receber pagamentos cripto reais, verifique o fluxo completo usado pela sua integração.

Em integrações somente com API:

  • Conferência da fatura, se usada.
  • Criação da fatura.
  • Exibição correta do endereço de pagamento.
  • Exibição da tag de destino ou do memo, quando necessário.
  • Exibição correta da moeda e da rede.
  • Tratamento da expiração da fatura.
  • Armazenamento de orderId e sciName.
  • Consulta do pedido por GET /api/orders.
  • Tratamento de pagamentos concluídos.
  • Tratamento de pagamentos cancelados e reembolsados.
  • Tratamento de orderId duplicados.
  • Tratamento de erros da API.

Se você usa notificações na Status URL:

  • A configuração do Hosted Checkout contém a Status URL correta.
  • O mesmo nome do Hosted Checkout é enviado como sciName.
  • As notificações chegam ao seu backend.
  • As assinaturas das notificações são verificadas.
  • Notificações duplicadas são tratadas com segurança.
  • A consulta pela API pode ser usada para conciliação.

Se você usa a página de pagamento do Hosted Checkout, verifique também:

  • Redirecionamento do cliente para o Hosted Checkout.
  • Redirecionamento para a Success URL.
  • Redirecionamento para a Failed URL.
  • Entrega das notificações na Status URL.
  • Validação da assinatura das notificações.
  • Consulta de pedidos pela API para conciliação.

Observações importantes​

  • Em integrações somente com API, os clientes não precisam acessar o Hosted Checkout.
  • A consulta atual de pedidos exige sciName.
  • Uma configuração do Hosted Checkout pode ser usada apenas para o sciName e as notificações na Status URL, sem exibir a página do Hosted Checkout.
  • Use sempre um orderId único para cada pagamento.
  • Sempre mostre exatamente o endereço, o valor, a moeda, a rede e a tag de destino retornados pela API.
  • Não marque um pedido como pago até que paymentStatus seja COMPLETED.
  • Use expirationDateMillis para calcular a expiração da fatura.
  • Pagamentos em cripto dependem das confirmações da blockchain e das condições da rede.
  • Enviar fundos para o endereço ou a rede errados pode causar a perda permanente dos fundos.
  • Não crie automaticamente outra fatura após um timeout com resultado incerto ou um erro temporário da API.