Royal Pay - Cryptocurrency Payment Gateway

Visão Geral

Bem-vindo à documentação da API Gateway RoyalPay. Esta API permite integrar pagamentos e recebimentos em criptomoedas de forma simples e segura.

Base URL

https://api.royal-pay.ai/gateway

Versão

v1.0.0

Filtros Aplicados

Todas as rotas utilizam apiKey para validação e apiKeyThrottle para limitação de taxa.

Autenticação

Todas as rotas requerem autenticação via API Key no header da requisição.

Headers Obrigatórios

http

X-API-Key: sua_api_key_aqui
Content-Type: application/json

Exemplo de Erro

json

{
  "error": "user_not_authenticated"
}

Status Code: 401 Unauthorized

Pagamentos (Payouts)

POST/gateway/payout

Cria um ou mais pagamentos (saques/transferências). Limite máximo de 50 pagamentos por requisição.

Request Body

json

[
  {
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "customer_info": "customer123",
    "crypto_currency": "USDT",
    "fiat_currency": "BRL",
    "process_by": "crypto_amount",
    "crypto_amount": "100.50",
    "reference_id": "ORDER-12345",
    "network": "Polygon",
    "feetakenfromamount": 0,
    "webhook_url": "https://seusite.com/webhook/payment"
  }
]

Parâmetros

Campo	Tipo	Obrigatório	Descrição
wallet	string	Sim	Endereço da carteira de destino (formato 0x...)
customer_info	string	Não	Identificador do cliente (máx. 200 caracteres)
crypto_currency	string	Sim	Símbolo da criptomoeda (ex: USDT, ETH)
fiat_currency	string	Não	Código da moeda fiat (ex: BRL, USD)
process_by	string	Sim	crypto_amount ou fiat_amount
crypto_amount	decimal	Não	Valor em cripto (se process_by = crypto_amount)
fiat_amount	decimal	Não	Valor em fiat (se process_by = fiat_amount)
reference_id	string	Sim	ID de referência único (máx. 255 caracteres)
network	string	Sim	Rede blockchain
feetakenfromamount	integer	Sim	Taxa deduzida: 0 (não) ou 1 (sim)
webhook_url	string	Sim	URL para webhook (máx. 756 caracteres)

Redes Suportadas

BNBEthereumBinanceSmartChainTronSolanaRipplePolygonAvalancheArbitrumOneCeloOptimismBaseCardanoDogecoinCronosOpBnbXlayer

Response Success (200 ou 207)

json

{
  "message": "payment_processing_completed",
  "summary": {
    "total_requested": 1,
    "successful": 1,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "reference_id": "ORDER-12345",
      "internal_reference": "PAY-20240115-ABCD1234",
      "crypto_amount": "100.50000000",
      "fiat_amount": "500.25",
      "crypto_currency": "USDT",
      "fiat_currency": "BRL",
      "network_fee": "0.50000000",
      "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "network": "Polygon",
      "status": "created"
    }
  ]
}

GET/gateway/list-payout

Lista todos os pagamentos criados via API.

Query Parameters

Campo	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página (padrão: 1)
per_page	integer	Não	Itens por página (padrão: 50, máx: 100)
status	string	Não	PENDING, COMPLETED ou FAILED
crypto_currency	string	Não	Filtrar por criptomoeda
network	string	Não	Filtrar por rede
date_from	date	Não	Data inicial (Y-m-d)
date_to	date	Não	Data final (Y-m-d)
reference_id	string	Não	Filtrar por reference_id

Response Success (200)

json

{
  "message": "payments_retrieved_success",
  "payments": [
    {
      "internal_reference": "PAY-20240115-ABCD1234",
      "reference_id": "ORDER-12345",
      "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "crypto_currency": "USDT",
      "fiat_currency": "BRL",
      "crypto_amount": "100.50000000",
      "fiat_amount": "500.25",
      "network": "Polygon",
      "status": "PENDING",
      "txid": "0x123abc...",
      "created_at": "2024-01-15 10:30:00"
    }
  ],
  "summary": {
    "total_pending": 5,
    "total_completed": 10,
    "total_failed": 2
  },
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 17,
    "total_pages": 1
  }
}

GET/gateway/check-payout/{internal_reference}

Consulta um pagamento específico pelo internal_reference.

Path Parameters

Campo	Tipo	Obrigatório	Descrição
internal_reference	string	Sim	Referência interna (10-756 caracteres)

Response Success (200)

json

{
  "message": "payment_retrieved_success",
  "payment": {
    "internal_reference": "PAY-20240115-ABCD1234",
    "reference_id": "ORDER-12345",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "crypto_currency": "USDT",
    "crypto_amount": "100.50000000",
    "fiat_amount": "500.25",
    "network": "Polygon",
    "status": "COMPLETED",
    "txid": "0x123abc..."
  }
}

Recebimentos (Payins)

POST/gateway/payin

Cria um ou mais recebimentos (depósitos/invoices). Limite máximo de 50 recebimentos por requisição.

Request Body

json

[
  {
    "crypto_currency": "USDT",
    "fiat_currency": "BRL",
    "process_by": "fiat_amount",
    "fiat_amount": "500.00",
    "reference_id": "INVOICE-12345",
    "network": "Polygon",
    "webhook_url": "https://seusite.com/webhook/receipt",
    "expires_at": 14400,
    "customer_info": "customer123"
  }
]

Parâmetros

Campo	Tipo	Obrigatório	Descrição
crypto_currency	string	Sim	Símbolo da criptomoeda
fiat_currency	string	Não	Código da moeda fiat (se process_by = fiat_amount)
process_by	string	Sim	crypto_amount ou fiat_amount
crypto_amount	decimal	Não	Valor em cripto
fiat_amount	decimal	Não	Valor em fiat
reference_id	string	Sim	ID de referência único
network	string	Sim	Rede blockchain
webhook_url	string	Sim	URL para webhook (máx. 756 caracteres)
expires_at	integer	Não	Expiração em segundos (padrão: 14400)
customer_info	string	Não	Identificador do cliente

Response Success (200)

json

{
  "message": "deposit_processing_completed",
  "summary": {
    "total_requested": 1,
    "successful": 1,
    "failed": 0
  },
  "results": [
    {
      "reference_id": "INVOICE-12345",
      "internal_reference": "REC-20240115-XYZ789",
      "wallet": "0x9876abc...",
      "crypto_amount": "100.00000000",
      "fiat_amount": "500.00",
      "crypto_currency": "USDT",
      "fiat_currency": "BRL",
      "network": "Polygon",
      "status": "created"
    }
  ]
}

GET/gateway/list-payin

Lista todos os recebimentos criados via API.

Query Parameters

Campo	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página (padrão: 1)
per_page	integer	Não	Itens por página (padrão: 50, máx: 100)
status	string	Não	PENDING, COMPLETED ou FAILED
crypto_currency	string	Não	Filtrar por criptomoeda
network	string	Não	Filtrar por rede
date_from	date	Não	Data inicial (Y-m-d)
date_to	date	Não	Data final (Y-m-d)
reference_id	string	Não	Filtrar por reference_id

GET/gateway/check-payin/{internal_reference}

Consulta um recebimento específico pelo internal_reference.

Saldos

GET/gateway/balances

Retorna os saldos do usuário em todas as criptomoedas suportadas.

Response Success (200)

json

{
  "message": "balances_retrieved_success",
  "balances": {
    "balance_bitcoin": "0.05000000",
    "balance_ethereum": "1.25000000",
    "balance_tether": "1000.500000",
    "balance_usdcoin": "500.250000",
    "balance_binancecoin": "2.50000000",
    "balance_cardano": "100.000000",
    "balance_solana": "50.000000",
    "balance_polygon": "500.000000",
    "balance_tron": "1000.000000",
    "balance_avalanche": "10.000000",
    "balance_ripple": "500.000000",
    "balance_dogecoin": "10000.000000"
  }
}

Extratos

GET/gateway/statements

Retorna o extrato de transações com suporte a filtros avançados.

Query Parameters

Campo	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página (padrão: 1)
per_page	integer	Não	Itens por página (padrão: 50, máx: 50)
direction	string	Não	in (entrada) ou out (saída)
type	string	Não	DEPOSIT, WITHDRAWAL, RATE, FEE, ROYALTY, EXCHANGE
balance	string	Não	Saldo específico (ex: balance_bitcoin)
reference_id	string	Não	Filtrar por reference_id
date_from	date	Não	Data inicial (Y-m-d)
date_to	date	Não	Data final (Y-m-d)
amount_from	decimal	Não	Valor mínimo
amount_to	decimal	Não	Valor máximo

Response Success (200)

json

{
  "message": "statements_retrieved_success",
  "statements": [
    {
      "direction": "out",
      "type": "WITHDRAWAL",
      "reference_id": "ORDER-12345",
      "amount": 100.5,
      "balance": "balance_tether",
      "internal_reference": "PAY-20240115-ABCD1234",
      "created_at": "2024-01-15 10:30:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 2,
    "total_pages": 1
  }
}

GET/gateway/statements/summary

Retorna estatísticas resumidas do extrato.

json

{
  "message": "statement_summary_retrieved_success",
  "summary": {
    "total_statements": 150,
    "by_direction": { "in": 80, "out": 70 },
    "by_type": {
      "deposits": 50,
      "withdrawals": 45,
      "fees": 25,
      "rates": 20
    },
    "recent_activity": 25
  }
}

Resumos e Informações

GET/gateway/summary

Retorna um resumo completo com tokens aceitos, fiats e configurações do usuário.

json

{
  "message": "summary_retrieved_success",
  "data": {
    "accepted_tokens": [
      {
        "symbol": "USDT",
        "contract_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
        "network": "Polygon",
        "min_receipt": "10",
        "max_receipt": "unlimited",
        "min_withdrawal": "20",
        "max_withdrawal": "10000",
        "network_fee": "1"
      }
    ],
    "accepted_fiats": [
      { "code": "BRL", "name": "Real Brasileiro", "symbol": "R$" },
      { "code": "USD", "name": "US Dollar", "symbol": "$" }
    ],
    "user_info": {
      "minimum_payment": "10",
      "receipt_rate": "1",
      "payment_rate": "1.5"
    }
  }
}

GET/gateway/summary/tokens

Retorna apenas os tokens aceitos e ativos.

GET/gateway/summary/fiats

Retorna apenas as moedas fiat aceitas.

Preços

GET/gateway/get-price

Obtém a cotação entre duas moedas (cripto ou fiat).

Query Parameters

Campo	Tipo	Obrigatório	Descrição
currency1	string	Sim	Moeda de origem (ex: BNB, USD)
currency2	string	Sim	Moeda de destino (ex: BRL, ETH)

Response Success (200)

json

{
  "success": true,
  "data": {
    "from": "BNB",
    "to": "BRL",
    "price": "650.00",
    "type": "crypto_to_fiat",
    "last_updated": "2024-01-15T10:30:00+00:00"
  }
}

Tipos de Conversão

same_currencyMesma moeda (retorna 1)

fiatFiat para fiat

crypto_to_fiatCripto para fiat

crypto_to_cryptoCripto para cripto

GET/gateway/get-currencies

Retorna todas as moedas disponíveis (cripto e fiat).

json

{
  "success": true,
  "data": {
    "currencies": [
      { "currency": "BRL", "name": "Real Brasileiro", "type": "fiat" },
      { "currency": "BNB", "name": "BNB", "type": "crypto" },
      { "currency": "ETH", "name": "ETH", "type": "crypto" }
    ],
    "total": 3
  }
}

Códigos de Erro

Erros de Autenticação

Código	Status	Descrição
user_not_authenticated	401	API Key inválida ou ausente

Erros de Validação

Código	Status	Descrição
invalid_parameters	400	Parâmetros inválidos ou ausentes
invalid_pagination	400	Paginação inválida
invalid_format	400	Formato de dados inválido
invalid_reference_id	400	Reference ID inválido
invalid_amount	400	Valor monetário inválido
invalid_date_range	400	Intervalo de datas inválido

Erros de Negócio

Código	Status	Descrição
insufficient_balance	400	Saldo insuficiente
limit_exceeded	400	Limite de transações excedido
max_payouts_exceeded	400	Máximo de 50 pagamentos por request
duplicate_reference_id	400	Reference ID duplicado
amount_out_of_limits	400	Valor fora dos limites min/max
price_unavailable	500	Cotação não disponível
no_wallet_available	500	Nenhuma carteira disponível

Webhooks

Webhooks são enviados automaticamente quando o status de uma transação muda.

Estrutura do Webhook (Pagamentos)

json

{
  "event": "payment.completed",
  "internal_reference": "PAY-20240115-ABCD1234",
  "reference_id": "ORDER-12345",
  "status": "COMPLETED",
  "crypto_amount": "100.50000000",
  "fiat_amount": "500.25",
  "crypto_currency": "USDT",
  "fiat_currency": "BRL",
  "network": "Polygon",
  "txid": "0x123abc...",
  "timestamp": "2024-01-15T10:35:00+00:00",
  "signature": "sha256_hash_here"
}

Estrutura do Webhook (Recebimentos)

json

{
  "event": "receipt.completed",
  "internal_reference": "REC-20240115-XYZ789",
  "reference_id": "INVOICE-12345",
  "status": "COMPLETED",
  "crypto_amount": "100.00000000",
  "received_amount": "100.00000000",
  "fiat_amount": "500.00",
  "crypto_currency": "USDT",
  "network": "Polygon",
  "txid": "0xabc123...",
  "timestamp": "2024-01-15T10:35:00+00:00",
  "signature": "sha256_hash_here"
}

Eventos de Webhook

Pagamentos

payment.created - Pagamento criado
payment.processing - Em processamento
payment.completed - Concluído
payment.failed - Falhou

Recebimentos

receipt.created - Recebimento criado
receipt.pending - Aguardando pagamento
receipt.completed - Recebido
receipt.expired - Invoice expirado
receipt.failed - Falhou

Verificação de Assinatura

php

$signature = hash_hmac('sha256', $payload, $ipn_secret);
if (!hash_equals($signature, $receivedSignature)) {
    // Webhook inválido
}

Boas Práticas

Gestão de API Keys

Mantenha suas API Keys em segurança
Nunca exponha API Keys em código client-side
Rotacione suas keys periodicamente
Use diferentes keys para dev e produção

Tratamento de Erros

Sempre verifique o campo error na resposta
Implemente retry logic com backoff exponencial
Monitore e registre todos os erros

Webhooks

Use HTTPS para URLs de webhook
Valide a assinatura usando ipn_secret
Implemente idempotência no processamento
Responda rapidamente (< 5s)

Performance

Use paginação para grandes conjuntos de dados
Aproveite o cache de 5 minutos em endpoints de summary
Faça batch de operações (até 50 por vez)

Segurança

Valide todos os dados recebidos
Use reference_id únicos e imprevisíveis
Não exponha internal_reference publicamente
Monitore atividades suspeitas

Rate Limiting

O filtro apiKeyThrottle limita o número de requisições por período de tempo.

http

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705321200

Exemplos de Uso

Criar um Pagamento

bash

curl -X POST https://api.royal-pay.ai/gateway/payout \
  -H "X-API-Key: sua_api_key" \
  -H "Content-Type: application/json" \
  -d '[{
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "crypto_currency": "USDT",
    "process_by": "crypto_amount",
    "crypto_amount": "100",
    "reference_id": "ORDER-12345",
    "network": "Polygon",
    "feetakenfromamount": 0,
    "webhook_url": "https://seusite.com/webhook"
  }]'

Criar Invoice (Recebimento)

bash

curl -X POST https://api.royal-pay.ai/gateway/payin \
  -H "X-API-Key: sua_api_key" \
  -H "Content-Type: application/json" \
  -d '[{
    "crypto_currency": "USDT",
    "fiat_currency": "BRL",
    "process_by": "fiat_amount",
    "fiat_amount": "500",
    "reference_id": "INV-12345",
    "network": "Polygon",
    "webhook_url": "https://seusite.com/webhook",
    "expires_at": 3600
  }]'

Consultar Saldos

bash

curl -X GET https://api.royal-pay.ai/gateway/balances \
  -H "X-API-Key: sua_api_key"

Listar Pagamentos com Filtros

bash

curl -X GET "https://api.royal-pay.ai/gateway/list-payout?status=COMPLETED&page=1&per_page=10&date_from=2024-01-01" \
  -H "X-API-Key: sua_api_key"

Obter Cotação

bash

curl -X GET "https://api.royal-pay.ai/gateway/get-price?currency1=BNB&currency2=BRL" \
  -H "X-API-Key: sua_api_key"