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

> Generate QR, cash, and card payments.

The Payin module lets you generate a QR code, initiate a cash payment, or initiate a card payment to receive payments in Bolivia.

## Create a QR Deposit

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

### Conditional fields by `fundingSource`

| Field            | `balance` | `conversion` |
| ---------------- | --------- | ------------ |
| `cryptoAmount`   | Optional  | Required     |
| `fiatAmount`     | Required  | Optional     |
| `depositAddress` | Optional  | Required     |
| `asset`          | Optional  | Required     |
| `blockchain`     | Optional  | Required     |

### Request (`fundingSource: conversion`)

```json theme={null}
{
  "cryptoAmount": 10,
  "asset": "USDC",
  "blockchain": "Polygon",
  "fiatCurrency": "BOB",
  "referenceId": "ORDER-1001",
  "country": "BO",
  "depositAddress": "0x0000000000000000000000000000000000000000",
  "fundingSource": "conversion",
  "description": "Payment for order 1001",
  "qrExpirationTime": "00:15:00"
}
```

### Request (`fundingSource: balance`)

```json theme={null}
{
  "fiatAmount": 100,
  "fiatCurrency": "BOB",
  "referenceId": "ORDER-1002",
  "country": "BO",
  "fundingSource": "balance",
  "description": "Payment for order 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"
}
```

## Create a Cash Deposit

The cash payin flow creates a cash deposit transaction using the same base data as the QR payin flow, without generating or returning QR data.

```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": "Cash payment for order 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"
}
```

## Card Payments

The card payment flow creates a transaction with the card details and confirms the operation in a second step.

### Endpoints

| Name                | Method | Path                                                     |
| ------------------- | ------ | -------------------------------------------------------- |
| Create card payment | `POST` | `/v2/transactions/card/payments`                         |
| Confirm transaction | `POST` | `/v2/transactions/card/payments/{transactionId}/confirm` |

### Create a Card Payment

Use this endpoint to initiate a card transaction. The response returns the transaction identifier and its initial status so you can continue with confirmation.

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

#### Request

```json theme={null}
{
  "externalReference": "ORDER-CARD-1001",
  "amount": 100.5,
  "currency": "BOB",
  "country": "BO",
  "description": "Payment for order 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"
  }
}
```

#### Card Types

| Code  | Type                  |
| ----- | --------------------- |
| `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."
}
```

### Confirm a Transaction

Use this endpoint to confirm a previously created transaction.

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

#### Path Parameters

| Parameter       | Type   | Required | Description                               |
| --------------- | ------ | -------- | ----------------------------------------- |
| `transactionId` | string | Yes      | Identifier of the transaction to confirm. |

#### 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."
}
```

#### Recommended Flow

1. Create the card payment with a unique `externalReference`.
2. Ask the end customer to confirm when the response status is `pendingConfirmation`.
3. Confirm the transaction using its `transactionId`.
4. Receive status changes through webhooks and reconcile them against transaction history.

#### Considerations

* This flow is coming soon and is not implemented in the code yet.
* Do not store sensitive card data, such as the CVV or full card number, outside the authorized flow.
* Send every request over HTTPS with `Authorization: Bearer {accessToken}`.

## Recommended Flow

1. Authenticate the partner.
2. Create the QR code with a unique reference.
3. Display `qrCodeBase64` to the end customer.
4. Receive status changes through webhooks.
5. Reconcile them against transaction history.