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

# Payin

> Generación de QR, cash y pagos con tarjeta.

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

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

```json theme={null}
{
  "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)

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

### Response

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

```http theme={null}
POST /v2/transactions/deposit/cash
```

### Request

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

### Response

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

```http theme={null}
POST /v2/transactions/card/payments
```

#### Request

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

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

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

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

1. Crear el pago con tarjeta enviando una `externalReference` única.
2. Solicitar la confirmación al cliente final si la respuesta queda en `pendingConfirmation`.
3. Confirmar la transacción usando `transactionId`.
4. 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

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