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
| Modelo | Experiência do cliente | Responsabilidade do backend | Tratamento do status |
|---|---|---|---|
| Somente API + consulta | Criada pelo seu aplicativo | Criar a fatura, exibir os dados de pagamento, acompanhar o status | Consultar GET /api/orders |
| Somente API + Status URL | Criada pelo seu aplicativo | Criar a fatura, exibir os dados de pagamento, processar as notificações | Status URL do Hosted Checkout, com consulta pela API para conciliação |
| API + Hosted Checkout | Hospedada pela Volet.com | Acompanhar pedidos e conciliar o status do pagamento | Status 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.
sciNameA 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ç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 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 "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.
- Crie um pedido no seu sistema.
- Opcionalmente, confira os dados calculados da fatura.
- Crie uma fatura cripto pela API.
- Mostre ao cliente o endereço de pagamento, o valor, a moeda, a rede e o prazo de expiração.
- O cliente envia o pagamento de uma carteira cripto.
- Acompanhe o pagamento por
GET /api/orders, por notificações na Status URL ou pelos dois. - 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
| Campo | Obrigatório | Descrição |
|---|---|---|
receiverCurrency | Sim | Moeda creditada na sua conta da Volet.com após a conclusão do pagamento. Veja os valores aceitos na referência da API. |
senderCurrency | Sim | Moeda e rede que o cliente deve usar para pagar, por exemplo USDT_TRC20. |
amount | Sim | Valor do pagamento. A forma como ele é interpretado depende de transferAction. |
transferAction | Sim | Define a qual lado amount se refere. Valores possíveis: GIVE, GET. Veja GIVE e GET. |
note | Não | Observação do pagamento ou descrição do pedido. Até 255 caracteres. |
sciName | Nã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. |
orderId | Nã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. |
subMerchantURL | Não | URL 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.
| Valor | O que amount significa |
|---|---|
GIVE | O valor que o cliente envia, expresso em senderCurrency. |
GET | O 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
| Campo | Descrição |
|---|---|
address | Endereço cripto para onde o cliente deve enviar o pagamento. |
addressOldFormat | Formato alternativo do endereço, se existir para a rede escolhida. |
destinationTag | Tag de destino, memo ou identificador adicional exigido por algumas redes. |
senderAmount | Valor que o cliente deve enviar. |
senderCurrency | Moeda e rede que o cliente deve usar. |
receiverAmount | Valor que deve ser creditado na sua conta. |
receiverCurrency | Moeda que deve ser creditada na sua conta. |
expirationDate | Data e hora de expiração da fatura. |
expirationDateMillis | Expiraçã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âmetro | Obrigatório | Descrição |
|---|---|---|
orderId | Sim | Identificador do pedido do lojista, até 64 caracteres. |
sciName | Sim* | 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
sciNameNo 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.
| Status | Significado | Ação recomendada |
|---|---|---|
PENDING | O pagamento ainda não chegou a um estado final de conclusão. | Mantenha o pedido pendente. |
COMPLETED | O pagamento foi concluído com sucesso. | Marque o pedido como pago e entregue o produto ou serviço. |
CANCELED | O pagamento foi cancelado. | Não entregue o pedido. |
REFUNDED | O 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
- Crie uma configuração do Hosted Checkout na sua conta da Volet.com.
- Configure a Status URL dela e selecione o método HTTP necessário.
- Use o nome do Hosted Checkout como
sciNameao criar faturas cripto pela API. - Mantenha o fluxo de pagamento do cliente no seu próprio aplicativo.
- Quando o status do pagamento muda, a Volet.com envia uma notificação para a Status URL configurada nesse Hosted Checkout.
- Verifique a assinatura da notificação antes de atualizar o pedido no seu sistema.
- Use
GET /api/orderscomo 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.
Assim, numa integração somente com API, o mesmo sciName tem duas funções:
- Permite que a implementação atual de
GET /api/ordersencontre 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:
- Crie um pedido no seu sistema.
- Redirecione o cliente para o Hosted Checkout com a sua integração do Hosted Checkout.
- Envie seu
orderIdna solicitação de pagamento do Hosted Checkout. - O cliente conclui o pagamento na página do Hosted Checkout.
- A Volet.com envia uma notificação de status do pagamento para a sua Status URL.
- Seu backend verifica a assinatura da notificação.
- Seu backend atualiza o status do pedido.
- 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:
- Receba a notificação do Hosted Checkout na Status URL.
- Verifique a assinatura da notificação.
- Atualize o pedido se a notificação for válida.
- Use
GET /api/orderscomo 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:
| Campo | Descrição |
|---|---|
errorMessage | Código de erro legível por máquina retornado pela API. |
errorType | Categoria do erro. |
errorId | Identificador do erro, que pode ser incluído em logs e solicitações de suporte. |
errorDescription | Descrição do erro legível por pessoas. |
errorField | Campo da requisição relacionado ao erro, se disponível. |
params | Parâmetros adicionais associados ao erro, se disponíveis. |
requestParams | Parâmetros da requisição associados ao erro, se disponíveis. |
Respostas HTTP 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. |
404 | O recurso solicitado não foi encontrado. |
500 | Erro 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
errorIdpara suporte e diagnóstico. - Verifique o
errorFieldquando disponível. - No tratamento programático de erros, use
errorMessage, nãoerrorDescription. - 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
orderIdesciName. - Consulta do pedido por
GET /api/orders. - Tratamento de pagamentos concluídos.
- Tratamento de pagamentos cancelados e reembolsados.
- Tratamento de
orderIdduplicados. - 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
sciNamee 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
paymentStatussejaCOMPLETED. - Use
expirationDateMillispara 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.
Relacionados
- Criar um gateway de pagamento — crie e configure a API e o Hosted Checkout
- Receber pagamentos cripto custodiais — como funcionam os pagamentos cripto custodiais
- Integração do Hosted Checkout — use a página de pagamento hospedada e as notificações na Status URL
- Moedas e tokens suportados — moedas e redes suportadas
- Referência da API — documentação completa de métodos, parâmetros e respostas