Payin - ON RAMP by Mesadepagos

El módulo Payin permite generar un QR, iniciar un pago en cash o iniciar un pago con tarjeta para recibir pagos en Bolivia.

Crear Depósito QR

POST /v2/transactions/deposit/qr

Campos condicionales según `fundingSource`

Campo	`balance`	`conversion`
`cryptoAmount`	Opcional	Requerido
`fiatAmount`	Requerido	Opcional
`depositAddress`	Opcional	Requerido
`asset`	Opcional	Requerido
`blockchain`	Opcional	Requerido

Request (fundingSource: conversion)

{
  "cryptoAmount": 10,
  "asset": "USDC",
  "blockchain": "Polygon",
  "fiatCurrency": "BOB",
  "referenceId": "ORDER-1001",
  "country": "BO",
  "depositAddress": "0x0000000000000000000000000000000000000000",
  "fundingSource": "conversion",
  "description": "Pago orden 1001",
  "qrExpirationTime": "00:15:00"
}

Request (fundingSource: balance)

{
  "fiatAmount": 100,
  "fiatCurrency": "BOB",
  "referenceId": "ORDER-1002",
  "country": "BO",
  "fundingSource": "balance",
  "description": "Pago orden 1002",
  "qrExpirationTime": "00:15:00"
}

Response

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "deposit_express",
  "transactionStatus": "pending_transaction",
  "requestedCryptoAmount": "10",
  "calculatedFiatAmount": "69.60",
  "exchangeRate": "6.96",
  "feeAmount": "0.00",
  "asset": "USDC",
  "country": "BO",
  "countryName": "Bolivia",
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceId": "ORDER-1001",
  "fiatCurrency": "BOB"
}

Crear Depósito Cash

El flujo de payin en cash permite crear una transacción de depósito en efectivo usando los mismos datos base del payin QR, pero sin generar ni devolver datos de QR.

POST /v2/transactions/deposit/cash

Request

{
  "cryptoAmount": 10,
  "asset": "USDC",
  "blockchain": "Polygon",
  "fiatCurrency": "BOB",
  "referenceId": "ORDER-CASH-1001",
  "country": "BO",
  "depositAddress": "0x0000000000000000000000000000000000000000",
  "fundingSource": "conversion",
  "description": "Pago cash orden 1001"
}

Response

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440010",
  "type": "deposit_express",
  "transactionStatus": "pending_transaction",
  "requestedCryptoAmount": "10",
  "calculatedFiatAmount": "69.60",
  "exchangeRate": "6.96",
  "feeAmount": "0.00",
  "asset": "USDC",
  "country": "BO",
  "countryName": "Bolivia",
  "referenceId": "ORDER-CASH-1001",
  "fiatCurrency": "BOB"
}

Pagos con Tarjeta

El flujo de pagos con tarjeta permite crear una transacción enviando los datos de la tarjeta y luego confirmar la operación en un segundo paso.

Endpoints

Nombre	Método	Ruta
Crear pago con tarjeta	`POST`	`/v2/transactions/card/payments`
Confirmar transacción	`POST`	`/v2/transactions/card/payments/{transactionId}/confirm`

Crear Pago con Tarjeta

Usa este endpoint para iniciar una transacción con tarjeta. La respuesta devuelve el identificador de la transacción y el estado inicial para continuar con la confirmación.

POST /v2/transactions/card/payments

Request

{
  "externalReference": "ORDER-CARD-1001",
  "amount": 100.5,
  "currency": "BOB",
  "country": "BO",
  "description": "Pago orden 1001",
  "card": {
    "cardType": "001",
    "holderName": "Juan Perez",
    "number": "4111111111111111",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "cvv": "123"
  },
  "customer": {
    "firstName": "Juan",
    "lastName": "Perez",
    "email": "juan.perez@example.com",
    "locality": "La Paz",
    "phoneNumber": "+59171234567",
    "postalCode": "0201"
  }
}

Tipos de Tarjeta

Código	Tipo
`001`	Visa
`002`	Mastercard
`003`	American Express
`004`	Discover
`007`	JCB
`042`	Maestro International
`050`	Hipercard
`054`	Elo

Response

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440100",
  "externalReference": "ORDER-CARD-1001",
  "type": "cardPayment",
  "status": "pendingConfirmation",
  "amount": "100.50",
  "currency": "BOB",
  "country": "BO",
  "authorization": {
    "requiresConfirmation": true,
    "confirmationMethod": "otp",
    "expiresAt": "2026-06-02T18:30:00.000Z"
  },
  "message": "Card payment created. Confirmation is required."
}

Confirmar Transacción

Usa este endpoint para confirmar la transacción creada previamente.

POST /v2/transactions/card/payments/{transactionId}/confirm

Path Params

Parámetro	Tipo	Requerido	Descripción
`transactionId`	string	Sí	Identificador de la transacción a confirmar.

Response

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440100",
  "externalReference": "ORDER-CARD-1001",
  "type": "cardPayment",
  "status": "completedTransaction",
  "amount": "100.50",
  "currency": "BOB",
  "country": "BO",
  "authorizationCode": "AUTH-789456",
  "message": "Card payment confirmed successfully."
}

Flujo Recomendado

Crear el pago con tarjeta enviando una externalReference única.
Solicitar la confirmación al cliente final si la respuesta queda en pendingConfirmation.
Confirmar la transacción usando transactionId.
Recibir cambios de estado por Webhooks y conciliar con el historial de transacciones.

Consideraciones

Este flujo estará disponible próximamente y aún no está implementado en el código.
No almacenes datos sensibles de tarjeta, como CVV o número completo de tarjeta, fuera del flujo autorizado.
Todos los requests deben enviarse por HTTPS y con Authorization: Bearer {accessToken}.

Flujo Recomendado

Autenticar al partner.
Crear el QR con una referencia única.
Mostrar qrCodeBase64 al cliente final.
Recibir cambios de estado por Webhooks.
Conciliar con el historial de transacciones.

​Crear Depósito QR

​Campos condicionales según fundingSource

​Request (fundingSource: conversion)

​Request (fundingSource: balance)

​Response

​Crear Depósito Cash

​Request

​Response

​Pagos con Tarjeta

​Endpoints

​Crear Pago con Tarjeta

​Request

​Tipos de Tarjeta

​Response

​Confirmar Transacción

​Path Params

​Response

​Flujo Recomendado

​Consideraciones

​Flujo Recomendado

Crear Depósito QR

Campos condicionales según `fundingSource`

Request (fundingSource: conversion)

Request (fundingSource: balance)

Response

Crear Depósito Cash

Request

Response

Pagos con Tarjeta

Endpoints

Crear Pago con Tarjeta

Request

Tipos de Tarjeta

Response

Confirmar Transacción

Path Params

Response

Flujo Recomendado

Consideraciones

Flujo Recomendado