> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesadepagos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Integrate ON RAMP into Node.js and TypeScript applications with the official SDK.

`@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.

<Card title="View @mdpsdk/on-ramp on npm" icon="package" href="https://www.npmjs.com/package/@mdpsdk/on-ramp">
  Review the published version, version history, and package README.
</Card>

## Requirements

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

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

## Installation

```bash theme={null}
npm install @mdpsdk/on-ramp
```

## Initialization

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
import { CurrencyPair, QuoteTransactionType } from '@mdpsdk/on-ramp'

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

## QR Payin

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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:

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

## Wallets

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
import type {
  CreateDepositQrRequest,
  CreateBankPayoutV3Request,
  TransactionHistoryResponse,
  WebhookResponse,
  WalletBalanceResponse,
} from '@mdpsdk/on-ramp'
```

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