BitcoinRD para desarrolladores

Autenticación

Incluye tu API key en el header X-API-Key de cada request. Las claves de producción usan el prefijo brd_; las claves de sandbox usan brds_ y no mueven fondos reales.

Base URL de producción: https://otc.bitcoinrd.do. Usa el entorno sandbox para probar la integración antes de pasar a producción y nunca expongas una API key en código del navegador.

Ejemplo

X-API-Key: brd_your_api_key_here

Endpoints y parámetros

Todos los endpoints usan Content-Type: application/json y requieren autenticación mediante API key.

Estados de una orden

El campo status puede tomar estos valores durante el ciclo de vida de una orden:

• pending_payment — esperando el pago del cliente
• pending_deposit — esperando el depósito de crypto
• pending_confirmation — confirmando la operación en blockchain
• processing — en procesamiento interno
• completed — completada exitosamente
• cancelled — cancelada
• rejected — rechazada por el sistema

Webhooks y firma

Configura una URL HTTPS en tu perfil para recibir notificaciones cuando cambie el estado de una orden. Cada evento incluye el header x-bitcoinrd-signature con una firma HMAC-SHA256.

Calcula la firma sobre los bytes exactos del body JSON sin modificar, valida que timestamp no tenga más de cinco minutos y deduplica eventId de forma atómica antes de procesar el evento. Rechaza con HTTP 401 cualquier firma inválida.

Ejemplo

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  if (!signature || !secret) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const received = Buffer.from(signature);
  const calculated = Buffer.from(expected);
  return received.length === calculated.length &&
    crypto.timingSafeEqual(received, calculated);
}

app.post('/webhook/bitcoinrd', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-bitcoinrd-signature'];
  const secret = process.env.BITCOINRD_WEBHOOK_SECRET;
  if (!Buffer.isBuffer(req.body) || !verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  const { event, eventId, data, timestamp } = JSON.parse(req.body.toString('utf8'));
  console.log(event, eventId, data.id, data.status, timestamp);
  // Verifica timestamp y reclama eventId atómicamente antes de procesar data.
  res.status(200).send('OK');
});

Payload de ejemplo

{
  "event": "order.completed",
  "eventId": "2c6f1c6e-5cc7-4a6b-9e8b-2b7a6e7ad9d1",
  "data": {
    "id": 123,
    "type": "buy",
    "status": "completed",
    "cryptoCurrency": "BTC",
    "cryptoAmount": 0.0005,
    "fiatAmount": 5000,
    "fiatCurrency": "DOP",
    "partnerClientRef": "client-001",
    "createdAt": "2026-09-02T12:00:00.000Z",
    "updatedAt": "2026-09-02T12:05:00.000Z"
  },
  "timestamp": "2026-09-02T12:05:01.000Z"
}

Referencia completa

Consulta los contratos, respuestas y ejemplos interactivos en la referencia OpenAPI/Swagger de la API Partner.

Abrir la referencia completa de la API Partner (Swagger UI)