Obter chaves de API
EnglishEspañolPortuguêsFrançaisTürkçeРусский
Obter chaves de API

A API de pagamentos cripto que você lê em dez minutos

Duas chamadas para receber, um webhook para confiar. Tudo abaixo é a API real.

Autenticação

Toda requisição do seu servidor usa HTTP Basic auth: o ID do projeto como nome de usuário e o segredo do projeto como senha. Mantenha o segredo no seu servidor; ele também assina seus webhooks.

https://payments.rubysoft.io/api

HTTP
Authorization: Basic base64(PROJECT_ID:PROJECT_SECRET)

Criar uma fatura

Use uma fatura quando o cliente paga um pedido específico. Envie o seu próprio ID de pedido de 24 caracteres como payload, o preço em USD, quanto o valor pode ficar abaixo (de 0 a 5%), o prazo de expiração e a URL que recebe os webhooks desta fatura.

payloadID do seu pedido, 24 caracteres hexadecimais (um ObjectId do MongoDB serve)
meta[price]Preço em USD
meta[tolerancePercent]Diferença a menos permitida, de 0 a 5
meta[expiresAt]Expiração, ISO 8601, no futuro
meta[webhookUrl]Para onde os eventos desta fatura são enviados
curl -G https://payments.rubysoft.io/api/invoice/load \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  --data-urlencode "payload=65f2c1a9e4b0d3f7a2c91e04" \
  --data-urlencode "meta[price]=120" \
  --data-urlencode "meta[tolerancePercent]=1" \
  --data-urlencode "meta[expiresAt]=2026-12-01T12:00:00Z" \
  --data-urlencode "meta[webhookUrl]=https://shop.example/webhooks/rubynex"

A resposta traz um objeto addresses indexado por rede. Mostre ao cliente as redes que você quer oferecer.

200 OK
{
  "id": "0b6f3c1e-8a52-4d7e-9c41-2f6a8d0e5b17",
  "payload": "65f2c1a9e4b0d3f7a2c91e04",
  "meta": {
    "type": "invoice",
    "status": "pending",
    "price": "120",
    "paid": "0",
    "expiresAt": "2026-12-01T12:00:00.000Z"
  },
  "addresses": {
    "tron": "T…",
    "ethereum": "0x…",
    "bsc": "0x…",
    "bitcoin": "bc1q…"
  }
}

Endereços de depósito permanentes

Use endereços permanentes para recargas: carteiras, jogos, corretoras, assinaturas. Envie o ID de 24 caracteres do seu cliente como payload e receba sempre os mesmos endereços.

cURL
curl -G https://payments.rubysoft.io/api/charge/load \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  --data-urlencode "payload=66a0b7d2c5e8f1a3b6d904c7"

# the same customer ID always returns the same addresses

Status da fatura

pendingAguardando pagamento
paidO valor total chegou
underpaidChegou menos que o preço
overpaidChegou mais de 1% acima do preço
expiredNenhum pagamento antes do prazo de expiração

Webhooks

Cada evento é um POST com corpo JSON e um cabeçalho X-Webhook-Signature: o HMAC-SHA256 do corpo bruto, com o segredo do projeto decodificado de hex como chave, em hex. Responda com qualquer status 2xx. Qualquer outra resposta gera reenvio: eventos de fatura a cada 15 segundos até a entrega, eventos de pagamento a cada 10 minutos, até 150 vezes.

Eventos

invoice:<status>Uma fatura mudou de status
pending-paymentUm pagamento foi detectado e aguarda confirmações
confirmed-paymentUm pagamento foi confirmado e creditado
failed-paymentUm pagamento não pôde ser processado
Webhook
POST /webhooks/rubynex
Content-Type: application/json
X-Webhook-Signature: 9c1fd2…e07a

{
  "id": "4e1a…c93f",
  "message": {
    "event": "invoice:paid",
    "data": { "id": "0b6f3c1e-…", "payload": "65f2c1a9e4b0d3f7a2c91e04" }
  },
  "attempt": 0,
  "timestamp": 1764590400
}

Verifique a assinatura

import crypto from 'node:crypto';
import express from 'express';

const secret = Buffer.from(process.env.RUBYNEX_SECRET, 'hex');

// keep the raw body: the signature covers its exact bytes
app.post('/webhooks/rubynex', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  const given = req.get('X-Webhook-Signature') ?? '';
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { message } = JSON.parse(req.body);
  if (message.event === 'invoice:paid') markOrderPaid(message.data.payload);
  res.sendStatus(200);
});

Confirmações por rede

RedeMoedasConfirmaçõesTempo até o crédito
TRONTRXUSDT1cerca de 3 s
EthereumETHUSDTUSDCDAI5cerca de 1 min
BNB Smart ChainBNBUSDTUSDCDAI10cerca de 8 s
PolygonPOLUSDTUSDCDAI20cerca de 40 s
BaseETHUSDTUSDC10cerca de 20 s
BitcoinBTC1cerca de 10 min
XRP LedgerXRP1cerca de 4 s
DogecoinDOGE3cerca de 3 min

Limites que vale conhecer

  • Pagamentos de $1 ou menos são ignorados como poeira
  • Tolerância de diferença a menos na fatura: até 5%
  • Uma fatura fica paga a mais quando chega mais de 1% acima do preço
  • O segredo de um projeto pode ser trocado uma vez a cada 5 minutos

Pronto para suas chaves?

Criamos seu projeto e enviamos o ID e o segredo.

Obter chaves de API