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.

Você pode usar a API de duas formas:

Somente API — seu aplicativo monta toda a experiência de pagamento e mostra ao cliente o endereço cripto, o valor, a rede e o prazo de expiração.
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 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	Criada pelo seu aplicativo	Criar a fatura, exibir os dados de pagamento, acompanhar o status	Consultar periodicamente o status do pagamento pela API
API + Hosted Checkout	Hospedada pela Volet.com	Criar ou acompanhar pedidos, conciliar o status do pagamento	Usar a Status URL do Hosted Checkout e a consulta de pedidos pela API

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.
Permissões de API para receber pagamentos cripto.
Uma configuração do Hosted Checkout, se você usar a API junto com o Hosted Checkout.

Veja Criar um gateway de pagamento 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 somente com API

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

O fluxo de pagamento:

Crie um pedido no seu sistema.
Opcionalmente, confira os dados da fatura antes de criá-la.
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.
Seu backend consulta o status do pagamento pela API.
Quando o pagamento for concluído, atualize o status do pedido no seu sistema.

Etapa 1: 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

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

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
}

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.
`senderCurrency`	Sim	Moeda e rede que o cliente deve usar para pagar.
`amount`	Sim	Valor do pagamento. A forma como ele é interpretado depende de `transferAction`.
`transferAction`	Sim	Define se o valor é o valor a enviar ou o valor a receber. Valores possíveis: `GIVE`, `GET`.
`note`	Não	Observação do pagamento ou descrição do pedido.
`sciName`	Não	Nome do Hosted Checkout ou da loja associado ao fluxo de pagamento.
`orderId`	Não	ID interno do seu pedido. 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.

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 creditada na sua conta.
`expirationDate`	Data e hora de expiração da fatura.
`expirationDateMillis`	Timestamp de expiração da fatura em milissegundos.

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

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 de instrução:

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 deve consultar o status do pagamento.

Endpoint:

GET /api/orders

Parâmetro de consulta obrigatório:

Parâmetro	Descrição
`orderId`	Identificador do pedido do lojista.

Parâmetro de consulta opcional:

Parâmetro	Descrição
`sciName`	Nome do Hosted Checkout ou da loja associado ao pedido.

Exemplo de requisição:

GET /api/orders?orderId=ORDER-1001&sciName=Store

Exemplo de resposta:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Status do pagamento

Use paymentStatus para decidir como atualizar o pedido no seu sistema.

Status	Significado	Ação recomendada
`CREATED`	A fatura foi criada e aguarda o pagamento.	Mantenha o pedido pendente.
`PROCESSING`	O pagamento foi detectado ou está em processamento.	Mantenha o pedido pendente e continue consultando.
`COMPLETED`	O pagamento foi concluído com sucesso.	Marque o pedido como pago e entregue o produto ou serviço.
`FAILED`	O pagamento falhou, expirou ou não pôde ser concluído.	Não entregue o pedido. Peça ao cliente que faça um novo pagamento.

Só considere o pedido pago depois que o status mudar para COMPLETED.

Fluxo API + Hosted Checkout

Use este modelo quando quiser que o Hosted Checkout cuide da página de pagamento do cliente, enquanto seu backend mantém o controle via API sobre o acompanhamento e a conciliação de pedidos.

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 orderId na 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 também consulta o pedido pela API para conciliação.

Nesse modelo, o Hosted Checkout cuida da página de pagamento, da escolha do método de pagamento, das instruções de pagamento e dos redirecionamentos do cliente.

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

Tratamento do status com o Hosted Checkout

Ao usar o 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 para a Status URL e a consulta de pedidos pela API para atualizar o status do pedido de forma confiável.

Abordagem recomendada:

Receba a notificação do Hosted Checkout na Status URL.
Verifique a assinatura da notificação.
Atualize o status do pedido se a notificação for válida.
Use a consulta de pedidos pela API como alternativa ou verificação de conciliação.

Tratamento de erros

Os erros da Merchant API retornam uma resposta de erro estruturada.

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 pedido duplicado.
Tente de novo apenas quando for seguro.

Checklist de testes

Antes de receber pagamentos cripto reais, teste o fluxo completo.

Em integrações somente com API, verifique:

Conferência da fatura.
Criação da fatura.
Exibição do endereço de pagamento.
Exibição da tag de destino ou do memo, quando necessário.
Tratamento da expiração da fatura.
Consulta periódica do status do pedido.
Tratamento de pagamentos concluídos.
Tratamento de pagamentos com falha ou expirados.
Tratamento de orderId duplicados.

Em integrações API + Hosted Checkout, verifique também:

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

Observações importantes

Integrações somente com API não usam os callbacks do Hosted Checkout.
Seu backend deve consultar o status do pagamento pela API.
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é o status do pagamento ser COMPLETED.
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.

Criar um gateway de pagamento — crie e configure sua API
Receber pagamentos cripto custodiais — como funcionam os pagamentos cripto custodiais
Integração do Hosted Checkout — use a página de pagamento hospedada
Referência da API — documentação completa de métodos, parâmetros e respostas

Quando usar a integração por API​

Modelos de integração​

Antes de começar​

Autenticação​

Fluxo somente com API​

Etapa 1: conferir os dados da fatura​

Etapa 2: criar uma fatura cripto​

Campos da requisição da fatura​

Campos da resposta da fatura​

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

Etapa 4: consultar o status do pagamento​

Status do pagamento​

Fluxo API + Hosted Checkout​

Tratamento do status com o Hosted Checkout​

Tratamento de erros​

Checklist de testes​

Observações importantes​

Relacionados​

Quando usar a integração por API

Modelos de integração

Antes de começar

Autenticação

Fluxo somente com API

Etapa 1: conferir os dados da fatura

Etapa 2: criar uma fatura cripto

Campos da requisição da fatura

Campos da resposta da fatura

Etapa 3: mostrar as instruções de pagamento

Etapa 4: consultar o status do pagamento

Status do pagamento

Fluxo API + Hosted Checkout

Tratamento do status com o Hosted Checkout

Tratamento de erros

Checklist de testes

Observações importantes

Relacionados