POST - Criar Fatura

Crie uma fatura de pagamento crypto. O comerciante envia o valor (USD), informações do pedido e URL de callback; o sistema retorna trans_id e url_payment para redirecionar o cliente à página de checkout.

Endpoint

POST https://api.payerscan.com/payment/crypto

Headers

Header	Obrigatório	Descrição
Content-Type	Sim	application/json
x-api-key	Sim	API Key da loja

Request Body (JSON)

Campo	Tipo	Obrigatório	Restrições	Descrição
merchant_id	string	Sim	Não vazio	Código do comerciante da loja (deve corresponder à API Key).
amount	number | string	Sim	> 0 e ≤ 1.000.000	Valor do pagamento (USD). Exemplo: 100, "100".
callback_url	string	Recomendado	Máx 500 caracteres, URL válida	URL para receber webhook nos status completed ou expired.
completed_url	string	Não	Máx 500 caracteres, URL válida	URL de redirecionamento após pagamento bem-sucedido.
expired_url	string	Não	Máx 500 caracteres, URL válida	URL de redirecionamento quando a fatura expira.
name	string	Não	Máx 255 caracteres	Nome/título da fatura.
description	string	Não	Máx 1000 caracteres	Descrição da fatura.
request_id	string	Não	Máx 255 caracteres	ID do pedido do comerciante para referência cruzada (retornado na resposta e webhook). Também usado para idempotência — veja notas abaixo.

Exemplo de Request

{
  "merchant_id": "MID-XXXXXXXXXX",
  "amount": 100,
  "name": "Top-up balance",
  "description": "Top-up the balance for username: [USERNAME]",
  "callback_url": "https://your-server.com/webhook/payment",
  "completed_url": "https://your-website.com/thank-you",
  "expired_url": "https://your-website.com/",
  "request_id": "ORDER_123456"
}

Response

Sucesso (HTTP 200)

{
  "status": "success",
  "data": {
    "request_id": "ORDER_123456",
    "trans_id": "TID-ABC123DEF4567890",
    "status": "waiting",
    "amount": "100",
    "url_payment": "https://app.payerscan.com/bill/TID-ABC123DEF4567890",
    "expires_in_minutes": 15
  }
}

Campo	Descrição
request_id	O valor que você enviou na requisição.
trans_id	Código único da fatura, usado para consulta e referência cruzada de webhook.
status	Sempre "waiting" quando recém-criada.
amount	Valor em USD (string).
url_payment	URL da página de checkout — redirecione o cliente para cá.
expires_in_minutes	Tempo de expiração da fatura (minutos).

Erros (4xx / 5xx)

Todos os erros seguem este formato:

{
  "status": "error",
  "message": "Descrição do erro",
  "error_code": "ERROR_CODE",
  "request_id": "ORDER_123456",
  "details": { }
}

HTTP	error_code	Descrição
400	VALIDATION_ERROR	Body inválido (campos obrigatórios ausentes, tipo errado, restrições excedidas). details.errors tem detalhes.
400	INVALID_MERCHANT_ID	merchant_id não corresponde à API Key da loja.
400	NO_PAYMENT_METHOD	Nenhum método de pagamento configurado na loja. Adicione pelo menos um endereço de carteira ou configure uma plataforma de câmbio antes de criar faturas.
401	MISSING_API_KEY	Nenhum header x-api-key fornecido.
401	INVALID_API_KEY	A API key é inválida ou não existe.
403	ACCOUNT_INACTIVE	A conta associada a esta API key está desativada.
403	STORE_INACTIVE	A loja associada a esta API key está desativada.
402	INSUFFICIENT_BALANCE	Saldo da loja insuficiente para taxas. details tem current_balance, required_fee, shortage, fee_rate_percent, discount_percent, invoice_amount.
429	RATE_LIMIT_EXCEEDED	Limite de requisições excedido (burst ou sustained). Tem limit_type, retry_after_seconds.
500	INTERNAL_ERROR	Erro do servidor.

Detalhes dos códigos de erro: Códigos de Erro da API.

Rate Limit

• Burst: 5 requisições/segundo (por API Key ou IP).
• Sustained: 60 requisições/minuto (por API Key ou IP).

Exceder limite → HTTP 429, body tem error_code: "RATE_LIMIT_EXCEEDED", retry_after_seconds.

Notas

• Método de pagamento: A loja deve configurar pelo menos um endereço de carteira ou plataforma de câmbio (Binance Pay, OKX, Bybit, MEXC, Gate.io, Bitget, etc.) antes de criar faturas. Se não configurado, a API retorna erro NO_PAYMENT_METHOD.
• Idempotência: Se você enviar um request_id que já existe para a mesma loja, a API retorna a fatura existente em vez de criar uma nova. A resposta incluirá idempotent: true para indicar isso. Isso evita faturas duplicadas ao tentar novamente requisições falhas.
• Taxas: As taxas são calculadas sobre o amount (USD) e deduzidas do saldo da loja. Garanta saldo suficiente antes de criar faturas. Durante o período de teste gratuito, as taxas são isentas.
• Callback: Sempre envie callback_url para receber webhooks completed/expired; caso contrário, você só pode verificar via GET https://api.payerscan.com/invoice/:trans_id.
• request_id: Recomendado enviar para fácil correspondência webhook-pedido e suporte à idempotência.