API de Pagamento em Massa em Cripto: Automatize Pagamentos de Forma Não Custodial

O que a API de pagamento em massa de criptomoedas realmente faz

Uma única POST /v1/payout chamada reserva os fundos para todo o lote, valida cada destinatário e cria um lote de pagamento que você pode rastrear. Essa é a forma honesta de uma API de pagamento em massa de criptomoedas em um gateway com um saldo interno da Payora: a API automatiza submissão, validação, status e webhooks, enquanto a liberação segue a aprovação, assinatura ou fluxo de liberação configurado para a conta. Um lote criado não é a mesma coisa que um pagamento confirmado na blockchain, e os destinatários não devem ser marcados como pagos até que o status e a evidência da transação provem isso. Se essa troca parecer aceitável, a API transforma uma folha de pagamento manual ou execução de afiliados em duas ou três linhas de código.

Este é um guia para desenvolvedores. Ele copia o contrato exato do documentação da API para que você possa enviar contra ele hoje: os endpoints, a assinatura HMAC, o Idempotency-Key, a validação rigorosa 422, o payout.sent webhook, e como cancelar libera o saldo retido. Se você quiser a visão geral do produto primeiro, leia o pagamentos em massa página.

Por que a submissão e a liberação são separadas

Quando você envia um lote — do gabinete ou através da API — a Payora reserva o total mais a taxa de movimentação por item no seu saldo interno, então o lote não pode ser gasto em excesso. O lote então segue o fluxo de aprovação, assinatura ou liberação configurado para a conta. Trate isso como um fluxo de trabalho de pagamento revisado, não como prova de que o dinheiro já chegou a cada destinatário.

O modelo de segurança que você deseja é simples: não faça de "chamada de API, moedas instantaneamente desaparecidas" seu modelo mental, a menos que esse seja explicitamente o produto que você escolheu. Produtos de pagamento totalmente automáticos no estilo hot-wallet podem ser mais rápidos, mas também aumentam o raio de impacto de uma violação de conta ou servidor. Os passos operacionais atuais da Payora devem ser verificados na documentação do produto e nas configurações da conta antes de tratar um lote como liberado.

Autenticação e assinatura de solicitação

A API de pagamento em massa de criptomoedas usa a mesma autenticação que o restante da Payora. Cada solicitação carrega três cabeçalhos: X-Payora-Key, X-Payora-Timestamp (segundos Unix, desvio de ±120s), e X-Payora-Signature. A assinatura é um HMAC-SHA256 sobre o timestamp, um ponto literal e o corpo da solicitação bruta exata:

X-Payora-Signature = hex(HMAC-SHA256(api_secret, timestamp + "." + raw_body))

Assine os bytes que você realmente envia, antes de qualquer reserialização. Se seu cliente HTTP re-encodar o JSON, capture o corpo bruto primeiro e faça o hash disso. Este é o mesmo esquema usado para verificar webhooks de entrada, coberto em Verificação de assinatura de webhook HMAC-SHA256.

POST /v1/payout: enviar um lote

Envie uma moeda, até 500 itens, e uma nota opcional. Cada item é um endereço, um valor como uma string e um opcional tag — a tag de destino XRP ou o memo XLM quando o ativo precisar de um.

curl -X POST https://api.payora.money/v1/payout \
  -H "X-Payora-Key: pk_live_9f3c8a12" \
  -H "X-Payora-Timestamp: 1753280400" \
  -H "X-Payora-Signature: 7b1e0c4d9a55f2..." \
  -H "Idempotency-Key: payroll-2026-07" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "items": [
      {"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "250.00"},
      {"address": "TXk9mP2v7wQ3nR5tYb1cD8eF4gH6jK0lMn", "amount": "1800.00", "tag": ""}
    ],
    "note": "July contractors"
  }'

Ao sucesso você recebe 201 com um lote que você pode rastrear. O total é a soma dos valores, fee é a taxa de movimentação do seu plano (1,5% no Gratuito) mais a taxa de rede da moeda, e ambos já estão retidos contra seu saldo:

{
  "batch_id": "po_7Qd2K8xM4b",
  "status": "pending",
  "currency": "USDT",
  "item_count": 2,
  "total": "2050.00",
  "fee": "20.50",
  "items": [
    {"index": 0, "address": "TR7NHqjeKQ...", "amount": "250.00", "status": "pending"},
    {"index": 1, "address": "TXk9mP2v7w...", "amount": "1800.00", "status": "pending"}
  ]
}

Aceitar pagamentos ainda é 0%; a taxa de movimentação só se aplica quando o dinheiro sai. As taxas de rede são separadas e pagas na cadeia no momento da transmissão.

Validação rigorosa: nenhum destinatário descartado silenciosamente

A validação é tudo ou nada de propósito. Se qualquer endereço estiver malformado para a rede escolhida, ou qualquer valor tiver mais casas decimais do que a moeda suporta, o lote inteiro é rejeitado com 422 e os índices ofensivos. Nada é enfileirado, nada é retido.

HTTP/1.1 422 Unprocessable Entity
{
  "error": "validation_failed",
  "invalid_items": [3, 17],
  "message": "invalid address at index 3; amount exceeds coin precision at index 17"
}

Este é o comportamento que você deseja para a folha de pagamento. Um gateway que silenciosamente truncou 1800.123456789 ou pulou uma linha ruim pagaria menos ou descartaria uma pessoa, e você não perceberia até que alguém reclamasse. Corrija os índices sinalizados e reenvie todo o lote.

Idempotência: tentativas nunca pagam em dobro

As redes têm tempo limite. Um pedido de pagamento que falha no meio do caminho é perigoso para tentar novamente cegamente, então envie um Idempotency-Key cabeçalho — qualquer string única e estável para aquele lote lógico (um período de folha de pagamento, um grupo de faturas). Se um pedido com a mesma chave chegar novamente, a Payora retorna o original lote em vez de criar um segundo. Reutilize a chave para cada tentativa do mesmo lote; use uma chave nova para um lote genuinamente novo.

• Mesma chave, mesmo lote — seguro para tentar novamente após um tempo limite; você recebe o primeiro resultado de volta.
• Nova chave — um novo lote, uma nova retenção no seu saldo.
• Armazene o retornado batch_id assim que o tiver, para que você possa reconciliar mesmo que a resposta tenha sido perdida.

Reconcile com GET /v1/payout/{id}

Após o fluxo de liberação configurado avançar, consulte GET /v1/payout/{id} para o status atual e um por-item tx_hash quando a evidência da transação estiver disponível. GET /v1/payout lista lotes recentes para painéis e auditorias. Armazene o batch_id e cada índice de item contra seus próprios registros para que cada destinatário corresponda à evidência que você pode mostrar a eles.

Precisa puxar um de volta antes da liberação? POST /v1/payout/{id}/cancelcancela um lote ainda pendente e libera o saldo retido na íntegra. Uma vez que os itens são liberados na blockchain, eles são finais, como qualquer transação de criptomoeda — o cancelamento só funciona enquanto o lote está pendente.

O webhook payout.sent

Em vez de fazer polling para sempre, inscreva-se em payout.sent. Após o fluxo de liberação configurado ser concluído e a Payora ter evidências de transação para os itens do lote, a Payora dispara um webhook assinado usando a mesma assinatura HMAC que invoice.paid. Verifique da mesma forma — recompute a assinatura sobre o timestamp, ponto, corpo bruto e compare em tempo constante:

$expected = hash_hmac('sha256', $timestamp . '.' . $raw_body, $webhook_secret);
if (!hash_equals($expected, $signature_header)) { http_response_code(400); exit; }
// payload.event == "payout.sent", payload.batch_id, payload.items[].tx_hash

Somente após essa verificação passar você deve marcar a execução da folha de pagamento como completa, enviar recibos por e-mail ou atualizar os livros contábeis. Um webhook não verificado é apenas uma solicitação HTTP não confiável.

Uma lista de verificação mínima de integração

1. Crie uma conta e gere chaves de API em registrar; financie o saldo interno na moeda que você irá sacar.
2. Construa o corpo JSON bruto, assine-o (timestamp + "." + body) com HMAC-SHA256, anexe os três cabeçalhos mais um Idempotency-Key.
3. POST /v1/payout; em 201 persista o batch_id, em 422 corrija os índices sinalizados e reenvie.
4. Complete as etapas de aprovação, assinatura ou liberação configuradas para a conta.
5. Verifique o payout.sent webhook, ou faça polling GET /v1/payout/{id}, e registre cada tx_hash.

Esse é o ciclo completo. A API remove a parte tediosa e propensa a erros — construir, validar e rastrear um lote de 500 linhas — enquanto seus controles operacionais decidem quando um lote revisado é realmente liberado.

Comece a construir

Leia a seção da API de Pagamento em Massa do docs, pegue as chaves em registrar, e veja o recurso de ponta a ponta na pagamentos em massa página. Você pode automatizar a criação de lotes hoje e manter a liberação de pagamentos vinculada aos controles configurados para sua conta.