@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 | URL | |---|---| | sandbox | https://sandbox-rampa.mesadepagos.com/api | | live | https://onramp.mesadepagos.com/api |

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

import { CurrencyPair, QuoteTransactionType } from '@mdpsdk/on-ramp';

const quotes = await client.quotes.getQuotes({
  pair: CurrencyPair.UsdcBob,
  transactionType: QuoteTransactionType.DepositExpress,
});

| CurrencyPair | Valor | |---|---| | UsdcBob | USDC/BOB | | BobUsdc | BOB/USDC | | UsdtBob | USDT/BOB | | BobUsdt | BOB/USDT |

| QuoteTransactionType | Valor | |---|---| | DepositExpress | deposit_express | | WithdrawalExpress | withdrawal_express | | WithdrawalAch | withdrawal_ach |

Payin

Crear QR de depósito

const qr = await client.payin.createDepositQr({
  createDepositQrRequestDoc: {
    fiatAmount: 100,
    fiatCurrency: 'BOB',
    referenceId: 'ref-001',
    country: 'BO',
    fundingSource: 'balance',
    description: 'Pago de prueba',
    qrExpirationTime: '00:30:00',
  },
});

// qr.data.transactionId
// qr.data.qrCodeBase64
// qr.data.transactionStatus

Para fondear con crypto (fundingSource: 'conversion'), agregá:

{
  fundingSource: 'conversion',
  asset: 'USDC',
  blockchain: 'Polygon',
  depositAddress: '0xYourCryptoAddress',
  cryptoAmount: 10,
}

Payout

Bancos disponibles

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

const { data } = await client.payout.getBanks({ country: Country.Bo });
// data.banks — array de bancos

| Country | | |---|---| | Bo Br Co Cl Pe | Cn Cr Py Uy Pa Gt |

Payout bancario

const payout = await client.payout.createPayoutAch({
  createBankPayoutV3RequestDoc: {
    funding_source: 'balance',
    external_reference: 'ref-001',
    transaction: {
      country: 'BO',
      entity_type: 'individual',
      amount: 100,
      bank_code: '001',
      description: 'Pago a proveedor',
      destination_account: '12345678',
      first_name: 'Juan',
      last_name: 'Perez',
      document_type: 'national_id',
      destination_id_number: '12345678',
      currency_type: 'BOB',
    },
  },
});

Estado de un payout bancario

const status = await client.payout.getPayoutBankStatus({
  transactionId: 'transaction-id-or-external-reference',
});

Payout QR

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

Escanear / validar QR antes de pagar

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

Payout crypto

const cryptoPayout = await client.payout.createPayoutCrypto({
  createPayoutCryptoRequestDoc: {
    walletId: 'wallet-id',
    destinationWallet: '0xDestinationAddress',
    amount: '10.5',
    asset: 'USDC',
    blockchain: 'Polygon',
    externalReference: 'ref-001',
  },
});

Consultas

Balance de payouts

const { data } = await client.consultas.getBalancePayouts();

Historial de transacciones

import { TransactionType, TransactionStatus } from '@mdpsdk/on-ramp';

const { data } = await client.consultas.getTransactionHistory({
  type: TransactionType.DepositExpress,
  transactionStatus: TransactionStatus.CompletedTransaction,
  page: 1,
  limit: 20,
});

// data.transactions — array de transacciones
// data.pagination   — info de paginación

| TransactionType | Valor | |---|---| | DepositExpress | deposit_express | | DepositCash | deposit_cash | | DepositCrypto | deposit_crypto | | DepositCard | deposit_card | | WithdrawalExpress | withdrawal_express | | WithdrawalAch | withdrawal_ach | | WithdrawalCrypto | withdrawal_crypto | | WithdrawalPix | withdrawal_pix | | WithdrawalWire | withdrawal_wire | | WithdrawalSwift | withdrawal_swift | | WithdrawalSepa | withdrawal_sepa | | Prefunding | prefunding |

| TransactionStatus | Valor | |---|---| | PendingTransaction | pending_transaction | | ProcessingTransaction | processing_transaction | | CompletedTransaction | completed_transaction | | RejectTransaction | reject_transaction | | ExpiredTransaction | expired_transaction | | CancelledTransaction | cancelled_transaction | | FailedTransaction | failed_transaction | | ReceivedTransaction | received_transaction |

Fees

import { FeeType, FeeCurrencyPair, FeeStatus } from '@mdpsdk/on-ramp';

const { data: fees } = await client.fees.getTenantFees({
  type: FeeType.Percentage,
  pair: FeeCurrencyPair.UsdcBob,
  status: FeeStatus.Current,
});

| FeeType | | FeeStatus | | |---|---|---|---| | Fixed | FIXED | Current | CURRENT | | Percentage | PERCENTAGE | Old | OLD |

| FeeCurrencyPair | Valor | |---|---| | UsdcBob UsdcPen UsdcBrl UsdcClp UsdcCop | USDC pairs | | UsdtBob UsdtPen UsdtBrl UsdtClp UsdtCop | USDT pairs | | BobUsdc BobUsdt | BOB pairs |

Webhooks

Crear webhook

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

Listar, obtener y actualizar

const { data: all } = await client.webhooks.getWebhooks();

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

await client.webhooks.updateWebhook({
  id: 'webhook-id',
  updateWebhookRequestDoc: { status: 'INACTIVE' },
});

Logs

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

const { data } = await client.webhooks.getWebhookLogs({ page: 1, limit: 50 });
// data.logs

| WebhookStatus | Valor | |---|---| | Success | SUCCESS | | Error | ERROR |

Wallet

Listar wallets

const { data } = await client.wallet.getWallets();
// data.wallets[0].walletId

Crear wallet y agregar asset

const wallet = await client.wallet.createWallet({
  createWalletRequestDoc: { name: 'Mi Wallet' },
});

await client.wallet.addAssetToWallet({
  id: wallet.data.walletId,
  addAssetToWalletRequestDoc: { symbol: 'USDC', blockchain: 'Polygon' },
});

Balance del vault

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

const { data } = await client.wallet.getVaultBalance({
  id: 'wallet-id',
  symbol: AssetSymbol.Usdc,
});

| AssetSymbol | | Blockchain | | |---|---|---|---| | Usdc | USDC | Polygon | Polygon | | Usdt | USDT | Ethereum | Ethereum | | | | Tron | TRON | | | | Binance | Binance | | | | Sepolia | Sepolia |

Manejo de errores

import type { ErrorResponse, ValidationErrorResponse } from '@mdpsdk/on-ramp';

try {
  await client.payin.createDepositQr({ ... });
} catch (err: any) {
  const error = err.response?.data as ErrorResponse | ValidationErrorResponse;
  console.error(err.response?.status, error.message);
}

Referencia de tipos

import type {
  // Auth
  LoginRequest, LoginResponse, LoginUser,

  // Quotes
  QuoteResponse,

  // Payin
  CreateDepositQrRequest, CreateDepositQrResponse,

  // Payout
  CreateBankPayoutRequest, CreateBankPayoutV3Request,
  CreatePayoutCryptoRequest, CreatePayoutCryptoResponse,
  CreatePayoutQrRequest, CreatePayoutQrResponse,
  ValidateQrRequest, ValidateQrResponse, ValidateQrDetails,
  GetBanksResponse, Bank, BankTransaction, BankTransactionV3,
  PayoutBalanceResponse, DepositAddressTransactionResponse,

  // Consultas
  TransactionHistoryResponse, TransactionHistoryItem, TransactionItemResponse,

  // Fees
  TenantFeeResponse, CreateTenantFeeRequest, FeeSnapshot,

  // Webhooks
  WebhookResponse, CreateWebhookRequest, CreateWebhookResponse,
  UpdateWebhookRequest, WebhookLogsResponse, WebhookLogItem,

  // Wallet
  WalletResponse, WalletAssetResponse, WalletBalanceResponse,
  GetWalletsResponse, GetVaultBalanceResponse,

  // Errors
  ErrorResponse, ValidationErrorResponse, UnauthorizedResponse,
  InternalServerErrorResponse,

  // Common
  Pagination,
} from '@mdpsdk/on-ramp';