> ## 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.

# SDK para Node.js

> Integra ON RAMP desde aplicaciones Node.js y TypeScript con el SDK oficial.

`@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](https://www.npmjs.com/package/@mdpsdk/on-ramp)**
>
> 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.

> [!WARNING]
>
> 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

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

## Inicialización

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

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

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

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

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

## Payin mediante QR

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

```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: 'Pago orden 1002',
    qrExpirationTime: '00:30:00',
  },
})
```

## Payout bancario

```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: '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:

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

## 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.

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

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.