SDK para Node.js - ON RAMP by Mesadepagos

@mdpsdk/on-ramp es el SDK oficial para integrar la API de ON RAMP desde aplicaciones Node.js y TypeScript. Proporciona un cliente tipado para autenticación, cotizaciones, payins, payouts, consultas, fees, webhooks y wallets.

Ver @mdpsdk/on-ramp en npm

Consulta la versión publicada, el historial de versiones y el README del paquete.

Requisitos

Node.js 18 o superior.
Credenciales de partner para iniciar sesión.
Una API key válida para inicializar el cliente.

Utiliza el SDK desde tu backend. No expongas la API key, las credenciales ni el JWT en código ejecutado por el navegador.

Instalación

npm install @mdpsdk/on-ramp

Inicialización

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

const client = new OnRampClient({
  apiKey: process.env.ON_RAMP_API_KEY!,
  environment: 'sandbox',
})

Opción	Valores	Descripción
`apiKey`	`string`	API key utilizada para inicializar el cliente.
`environment`	`sandbox` \| `live`	Ambiente al que se enviarán las solicitudes.

Ambiente	URL
Sandbox	`https://sandbox-rampa.mesadepagos.com/api`
Live	`https://onramp.mesadepagos.com/api`

Autenticación

Inicia sesión con las credenciales del partner. El cliente guarda el JWT recibido y lo agrega automáticamente a las solicitudes posteriores.

const auth = await client.login({
  email: 'partner@example.com',
  password: process.env.ON_RAMP_PASSWORD!,
})

console.log(auth.user)

Si ya tienes un JWT activo, puedes configurarlo directamente:

client.setToken(process.env.ON_RAMP_JWT!)

Módulos disponibles

Módulo	Uso principal
`client.quotes`	Consultar cotizaciones de payin y payout.
`client.payin`	Crear depósitos mediante QR.
`client.payout`	Crear payouts bancarios, QR y cripto.
`client.consultas`	Consultar balances e historial de transacciones.
`client.fees`	Consultar y crear configuraciones de fees.
`client.webhooks`	Administrar webhooks y revisar sus logs.
`client.wallet`	Crear wallets, agregar assets y consultar balances.

Cotizaciones

Los enums exportados por el SDK reducen errores al enviar pares de monedas y tipos de transacción.

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

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

Payin mediante QR

const { data: qr } = await client.payin.createDepositQr({
  createDepositQrRequestDoc: {
    fiatAmount: 100,
    fiatCurrency: 'BOB',
    referenceId: 'ORDER-1001',
    country: 'BO',
    fundingSource: 'balance',
    description: 'Pago orden 1001',
    qrExpirationTime: '00:30:00',
  },
})

console.log(qr.transactionId)
console.log(qr.qrCodeBase64)

Para utilizar fondeo por conversión, agrega los datos del asset y la dirección de depósito:

const { data: qr } = await client.payin.createDepositQr({
  createDepositQrRequestDoc: {
    cryptoAmount: 10,
    asset: 'USDC',
    blockchain: 'Polygon',
    fiatCurrency: 'BOB',
    referenceId: 'ORDER-1002',
    country: 'BO',
    depositAddress: '0xYourCryptoAddress',
    fundingSource: 'conversion',
    description: 'Pago orden 1002',
    qrExpirationTime: '00:30:00',
  },
})

Payout bancario

const { data: payout } = await client.payout.createPayoutAch({
  createBankPayoutV3RequestDoc: {
    funding_source: 'balance',
    external_reference: 'ORDER-ACH-1001',
    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',
    },
  },
})

Puedes consultar posteriormente el estado utilizando el identificador de la transacción o la referencia externa:

const { data: status } = await client.payout.getPayoutBankStatus({
  transactionId: payout.transaction_id,
})

Wallets

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

const { data: wallet } = await client.wallet.createWallet({
  createWalletRequestDoc: { name: 'main_wallet' },
})

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

const { data: balance } = await client.wallet.getVaultBalance({
  id: wallet.walletId,
  symbol: AssetSymbol.Usdc,
})

Manejo de errores

Los errores HTTP conservan la respuesta de Axios, por lo que puedes consultar el código de estado y el payload devuelto por la API.

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

try {
  await client.quotes.getQuotes({})
} catch (error: any) {
  const details = error.response?.data as
    ErrorResponse | ValidationErrorResponse

  console.error(error.response?.status, details.message)
}

TypeScript

El paquete incluye sus declaraciones TypeScript y exporta los tipos de request, response, errores, paginación, enums y entidades utilizados por el cliente.

import type {
  CreateDepositQrRequest,
  CreateBankPayoutV3Request,
  TransactionHistoryResponse,
  WebhookResponse,
  WalletBalanceResponse,
} from '@mdpsdk/on-ramp'

Mantén el paquete actualizado con npm install @mdpsdk/on-ramp@latest para recibir los tipos y operaciones más recientes.

Ver @mdpsdk/on-ramp en npm

​Requisitos

​Instalación

​Inicialización

​Autenticación

​Módulos disponibles

​Cotizaciones

​Payin mediante QR

​Payout bancario

​Wallets

​Manejo de errores

​TypeScript

Requisitos

Instalación

Inicialización

Autenticación

Módulos disponibles

Cotizaciones

Payin mediante QR

Payout bancario

Wallets

Manejo de errores

TypeScript