Node.js SDK - ON RAMP by Mesadepagos

@mdpsdk/on-ramp is the official SDK for integrating the ON RAMP API into Node.js and TypeScript applications. It provides a typed client for authentication, quotes, payins, payouts, queries, fees, webhooks, and wallets.

View @mdpsdk/on-ramp on npm

Review the published version, version history, and package README.

Requirements

Node.js 18 or later.
Partner credentials for login.
A valid API key for client initialization.

Use the SDK from your backend. Do not expose the API key, credentials, or JWT in code that runs in the browser.

Installation

npm install @mdpsdk/on-ramp

Initialization

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

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

Option	Values	Description
`apiKey`	`string`	API key used to initialize the client.
`environment`	`sandbox` \| `live`	Environment to which requests are sent.

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

Authentication

Log in with the partner credentials. The client stores the returned JWT and automatically adds it to subsequent requests.

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

console.log(auth.user)

If you already have an active JWT, set it directly:

client.setToken(process.env.ON_RAMP_JWT!)

Available Modules

Module	Primary use
`client.quotes`	Retrieve payin and payout quotes.
`client.payin`	Create QR deposits.
`client.payout`	Create bank, QR, and crypto payouts.
`client.consultas`	Retrieve balances and transaction history.
`client.fees`	Retrieve and create fee configurations.
`client.webhooks`	Manage webhooks and review delivery logs.
`client.wallet`	Create wallets, add assets, and retrieve balances.

Quotes

The enums exported by the SDK reduce errors when sending currency pairs and transaction types.

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

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

QR Payin

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

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

For conversion funding, include the asset and deposit address data:

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: 'Payment for order 1002',
    qrExpirationTime: '00:30:00',
  },
})

Bank Payout

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: 'Supplier payment',
      destination_account: '12345678',
      first_name: 'Juan',
      last_name: 'Perez',
      document_type: 'national_id',
      destination_id_number: '12345678',
      currency_type: 'BOB',
    },
  },
})

You can then retrieve the status using the transaction identifier or external reference:

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,
})

Error Handling

HTTP errors preserve the Axios response, allowing you to inspect the status code and API response payload.

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

The package includes TypeScript declarations and exports the request, response, error, pagination, enum, and entity types used by the client.

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

Keep the package current with npm install @mdpsdk/on-ramp@latest to receive the latest types and operations.

View @mdpsdk/on-ramp on npm

​Requirements

​Installation

​Initialization

​Authentication

​Available Modules

​Quotes

​QR Payin

​Bank Payout

​Wallets

​Error Handling

​TypeScript

Requirements

Installation

Initialization

Authentication

Available Modules

Quotes

QR Payin

Bank Payout

Wallets

Error Handling

TypeScript