@mdpsdk/on-ramp

Official Node.js SDK for the MDP On-Ramp API.

Installation

npm install @mdpsdk/on-ramp

Setup

import { OnRampClient } from '@mdpsdk/on-ramp';

const client = new OnRampClient({
  apiKey: 'your-api-key',
  environment: 'sandbox', // 'sandbox' | 'live'
});

| Environment | |---| | sandbox | | live |

Authentication

Login con tus credenciales. El JWT se guarda automáticamente y se inyecta en todos los requests siguientes.

const auth = await client.login({
  email: '[email protected]',
  password: 'your-password',
});

// auth.accessToken — JWT generado
// auth.user        — información del usuario

Si ya tenés un JWT activo podés setearlo directamente:

client.setToken('your-jwt-token');

Quotes

Cotizaciones disponibles para operaciones de payin y payout.

// Todas las cotizaciones
const quotes = await client.quotes.getQuotes({});

// Filtradas por par y tipo de transacción
const quote = await client.quotes.getQuotes({
  pair: 'USDC/BOB',               // 'USDC/BOB' | 'BOB/USDC' | 'USDT/BOB' | 'BOB/USDT'
  transactionType: 'deposit_express', // 'deposit_express' | 'withdrawal_express' | 'withdrawal_ach'
});

Respuesta:

{
  transactionType: 'deposit_express',
  pair: 'USDC/BOB',
  serviceExchangeRate: 6.96,
  partnerExchangeRate: 6.89,
  partnerPctFee: 1.0,
  timeStamp: '2024-01-01T00:00:00Z',
}

Payin

Crear QR de depósito

Genera un QR para que el usuario final realice un pago en fiat y recibas crypto.

const depositQr = await client.payin.createDepositQr({
  createDepositQrRequestDoc: {
    cryptoAmount: 10,
    asset: 'USDC',               // 'USDC' | 'USDT'
    blockchain: 'Polygon',       // 'Polygon' | 'Ethereum' | 'TRON'
    fiatCurrency: 'BOB',         // 'BOB' | 'USD'
    referenceId: 'ref-001',      // referencia única del partner
    country: 'BO',
    depositAddress: '0xYourCryptoAddress',
    fundingSource: 'balance',    // 'balance' | 'conversion'
    description: 'Pago de prueba',
    qrExpirationTime: '00:30:00',
  },
});

Payout

Obtener bancos disponibles

const banks = await client.payout.getBanks({});
// Retorna lista de bancos con código y nombre

Payout bancario (ACH / transferencia)

const payout = await client.payout.createPayoutAch({
  createBankPayoutRequestDoc: {
    funding_source: 'balance',     // 'balance' | 'conversion'
    external_reference: 'ref-001',
    asset_deposit: 'USDC',
    blockchain: 'Polygon',
    transaction: {
      country: 'BO',
      entity_type: 'individual',   // 'individual' | 'company'
      amount: 100,
      bank_code: '001',
      description: 'Pago a proveedor',
      destination_account: '12345678',
      first_name: 'Juan',
      last_name: 'Perez',
      document_type: 'national_id', // 'national_id' | 'tax_id' | 'passport' | 'foreign_id'
      destination_id_number: '12345678',
      currency_type: 'BOB',         // 'BOB' | 'USD'
    },
  },
});

Payout QR

const payoutQr = await client.payout.createPayoutQr({
  createPayoutQrRequestDoc: {
    image: 'base64-encoded-qr-image',
    external_reference: 'ref-001',
    asset_deposit: 'USDC',
    blockchain: 'Polygon',
    funding_source: 'balance',
  },
});

Escanear QR (validar antes de pagar)

const scanned = await client.payout.scanPayoutQr({
  validateQrRequestDoc: {
    image: 'base64-encoded-qr-image',
  },
});

Consultas

Balance de payout

const balance = await client.consultas.getBalancePayouts();

// balance.data: { type, balance, fiat, lastCredit, lastDebit }

Historial de transacciones

const history = await client.consultas.getTransactionHistory({
  page: 1,
  limit: 20,
});

Fees

Obtener fees configurados

const fees = await client.fees.getTenantFees({});

Crear fee

const fee = await client.fees.createTenantFee({
  createTenantFeeRequestDoc: {
    pair: 'USDC/BOB',
    transactionType: 'deposit_express',
    amount: 1.5,
    type: 'PERCENTAGE', // 'PERCENTAGE' | 'FIXED'
  },
});

Webhooks

Listar webhooks

const webhooks = await client.webhooks.getWebhooks();

Crear webhook

const webhook = await client.webhooks.createWebhook({
  createWebhookRequestDoc: {
    url: 'https://yourapp.com/webhook',
    description: 'Notificaciones de transacciones',
    status: 'ACTIVE', // 'ACTIVE' | 'INACTIVE' | 'SUSPENDED'
    events: {
      transaction: [
        'pending_transaction',
        'processing_transaction',
        'completed_transaction',
        'reject_transaction',
        'failed_transaction',
        'expired_transaction',
      ],
    },
  },
});

Obtener webhook por ID

const webhook = await client.webhooks.getWebhookById({ id: 'webhook-id' });

Actualizar webhook

await client.webhooks.updateWebhook({
  id: 'webhook-id',
  updateWebhookRequestDoc: {
    description: 'Descripción actualizada',
    status: 'INACTIVE',
  },
});

Ver logs de un webhook

const logs = await client.webhooks.getWebhookLogs({ webhookId: 'webhook-id' });

Manejo de errores

try {
  await client.payin.createDepositQr({ ... });
} catch (err) {
  console.error(err.response?.data); // error detallado de la API
  console.error(err.response?.status); // código HTTP
}

TypeScript

El SDK exporta todos los tipos necesarios:

import {
  OnRampClient,
  CreateDepositQrRequest,
  CreateBankPayoutRequest,
  QuoteResponse,
  WebhookResponse,
  TransactionHistoryItem,
  // ...
} from '@mdpsdk/on-ramp';