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

# QR (Perú)

> Localpayment permite a los comercios procesar pagos instantáneos mediante el sistema estandarizado de pago QR de Perú. Esta guía describe el proceso para iniciar pagos basados ​​en QR a través de la API de Localpayment, detallando los parámetros necesarios, el manejo de las respuestas y la interpretación de los códigos de estado para una integración perfecta con la red de pagos interoperable de Perú.

## Antes de comenzar

Asegúrate de tener:

* [Credenciales API ](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).

***

## Carteras compatibles

* [Credenciales API ](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).

***

## Paso 1. Crear pago con código QR

Para generar un código QR para la recaudación de pagos, envía una solicitud `POST` al endpoint [Crear Payin](https://docs.localpayment.com/es/reference/payins.md) con parámetros específicos para códigos QR.

> [!NOTE]
>
> **Vencimiento**
>
> Por defecto, una orden de pago mediante transferencia bancaria QR caduca **1 día después de su creación**. Para personalizar el período de caducidad (**de 1 a 7 días**) según las necesidades de tu negocio, ponte en contacto con tu gestor de cuenta para la configuración.

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave específicos para los pagos mediante código QR:

| Objeto | Descripción | Requerido |
| - | - | - |
| `paymentMethod.type` | Debe ser `BankTransfer`. | ✅ |
| `paymentMethod.code` | Utiliza `6080` para QR de Perú. | ✅ |
| `sender` | Información del remitente para fines de cumplimiento. | ✅ |
| `merchant` | Datos del comerciante/negocio. | ✅ |
| `paymentMethod` | Configuración del método de pago. | ✅ |
| `amount` | Importe de la transacción. | ✅ |
| `currency` | Código de moneda de la transacción. | ✅ |
| `country` | Debe ser `PER`. | ✅ |

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/payins.md) en la solicitud.

> [!WARNING]
>
> **Límites de importe para Perú:** Los pagos con código QR requieren un mínimo de 1 PEN y no pueden exceder los 500 PEN por transacción. Cada usuario tiene un límite diario de 2000 PEN para todas las transacciones.

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `curl`:

```curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
    "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
    "paymentMethod": {
        "type": "Banktransfer",
        "code": "6080",
        "flow": "DIRECT"
    },
    "country": "PER",
    "currency": "PEN",
    "amount": 1001,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "QR Payment",
    "merchant": {
        "type": "COMPANY",
        "document": {
            "id": "12345678",
            "type": "DNI"
        },
        "name": "Test Company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "document": {
            "id": "87654321",
            "type": "DNI"
        },
        "name": "John",
        "lastname": "Doe",
        "email": "john.doe@example.com",
        "userReference": "{{$randomUserName}}"
    }
}
'
```

***

## Paso 2. Gestionar la respuesta.

### Respuesta exitosa

La creación exitosa de un pago mediante código QR incluye los datos del código QR y los detalles del pago:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
  "internalId": "bd3c82a3-7b97-4e43-bcce-f59eb31ef5ef",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "6080",
    "flow": "DIRECT"
  },
  "country": "PER",
  "currency": "PEN",
  "amount": 1001,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "PEN",
    "fxQuote": 1,
    "amount": 1001
  },
  "payment": {
    "currency": "PEN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1001
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "PEN",
    "fxSource": 6.812851,
    "fxQuote": 1,
    "amount": 1,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "qr": {
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADRUlEQVR4Xu2XbY7bMAxEeQPe/5a8Acs3dBaxdoH2TzsBaiF1Hek5ED9m5I3+k1Fxzvw4HuwYD3aMBzvGgx3jf8MqIjoyMruq5y6LT6QWzFizXHzLiOyoIbMH1ZoXq6ie9dm04Lmt1/UTsFmevTc5DuYnhP4UjL2TWPbepDZI7wdgkAM1WQaf5dSDWvNiU+b6cXxT1gns+IuYBllFwWycuk8UX2tGbHaqG7KaSCXJNZaDqr0Y2wdIbLBWOI0TTiO4sZKKm9wWaNKjfImNxYrNJNDAE0yR38amCejKvw1rloMGaFD8L/YuFYETUw75F9dpJpducstDVmymr5M2VsvF6Tup3YCsWHFWkN0irynV8NxkWw5txuQyazVFAAQip7mHYMCYZvOIBHsBURuQcDdGJoNuhJTTFCPoTy/GKx7+MhrZJgBuqduOlY4zHCbJMiQfWc299P8e0wmWePR26Kyp5vNEXL9jw4oZXWbDQEVDgq6arZg2r2/IebugOEEQkxfbHpxpNSTVVn9S+HovvQVT2TEXVEyW6c9E45tfJ1akkdzSlUEsBIKS7pEasFlsGpEpsjyx8MejQnBjFH4deRKrBLPKe0LRB1bsldGJBQXLAzHq7xZtwCj93HGmBXfYs5rgXnoHpk0jGAJRvWciddytZpwYrajyr6JBCKOurnRieg9GMjCq+2B8aE031myewwKAYBA0qsl3G/RgxfY5LBolA8kNg3DcmKLozSdmGLKYYe6ld2Aa8jx1IjtP9MLNW+k9WJFOAsFjSPDAaFoHixlLmhJ32RPjKr2u+zNWrPakDUqu+aQVetVsxbgiYKymYAYvgqJjvdhan0KA4pM8kvSnGZv/k87EAy/N6OHzaHNgyqgMkGl2/VILGTdjVyB6SVGquRYJvlXBgnH8hyY4Rnjni+tY82O82dGTgWbUooXh6IXPjHFDF8pq1v+Qsm7v+bdguntZjSybcBScFyuOjUsq0nPJZJLbr99wYfr0vq6wb4im7kRkxuTO1Jl19egqmi74CEzbxakLTaOXvNbtGAJWpdWcs39yK7vxYpCw64LklzQTzy0EC7aSIZRELLxBYYbQ76V3YL8dD3aMBzvGgx3jwY7xYMeoX9xXVTGl7tqkAAAAAElFTkSuQmCC",
        "expirationDate": "2025-04-21T16:14:26.0596069",
        "paymentInstructions": "<b><i>From Yape, Plin or other entity aplications, scan the QR code and complete the payment process</i></b>"

  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company ",
    "document": {
      "id": "12345678",
      "type": "DNI"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "87654321",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "fullName": "John Doe"
  },
  "date": {
    "creationDate": "2024-11-15T17:05:11.772+00:00",
    "processedDate": "2024-11-15T17:05:13.656446231",
    "expirationDate": "2024-11-15 23:59"
  },
  "errors": []
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `qr.image` | Imagen PNG del código QR codificada en Base64. | Visualización directa sin generación adicional. |
| `qr.expirationDate` | Marca de tiempo en la que el código QR deja de ser válido. | Muestra un temporizador de cuenta regresiva y gestiona la lógica de expiración. |
| `qr.paymentInstructions` | Instrucciones de pago. | Mostrar instrucciones de pago fáciles de usar. |
| `externalId` | Tu número de referencia original. | Conciliación interna y cotejo de pedidos. |
| `status.code` | Estado actual de la transacción (`100` = `INPROGRESS`) | Determinar los siguientes pasos en el flujo de pagos. |
| `date.creationDate` | Cuando se creó la transacción. | Análisis y seguimiento del rendimiento. |

### Respuesta de error

Si falla la generación del código QR, recibirás información detallada sobre el error:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "96989760-c262-4607-b99c-dfbf8af42f52",
  "status": {
    "code": "812",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "812",
      "detail": "External Id already used - duplication"
    }
  ]
}
```

***

## Paso 3. Mostrar el código QR y procesar el pago.

1. **Visualización de código QR**: Presenta el código QR al cliente a través del canal elegido.
2. **Escaneo mediante la aplicación bancaria**: El cliente escanea el código QR con la aplicación móvil de su banco.
3. **Autorización de pago**: El cliente confirma el pago en su entorno bancario.
4. **Confirmación en tiempo real**: Localpayment recibe una notificación de pago instantánea.
5. **Actualización de estado**: Tu sistema recibe un webhook con la confirmación del pago.

![](https://mintcdn.com/localpayment-1fee3d41/R2R5JIQRe6pRQ97b/images/docs/c5341035dc1e7605024222eba3a99022db6774a16999a6a057264070aa1af9b6-qr-per.png?fit=max\&auto=format\&n=R2R5JIQRe6pRQ97b\&q=85\&s=429ca765d3d65ead8fde562bdea86a40)

### Mejores prácticas para la visualización de códigos QR

* Tamaño mínimo de pantalla: 250x250 píxeles para escaneo móvil.
* Mantén una relación de aspecto de 1:1 sin distorsión.
* Asegúrate de que haya un alto contraste (fondo oscuro sobre fondo claro).
* Agrega una zona de silencio (borde blanco) alrededor del código QR.
* Incluye texto alternativo (por ejemplo, "Pago mediante código QR").
* Mostrar instrucciones de pago claras.
* Gestionar el tiempo de vida (TTL) y la expiración.

***

## Paso 4. Seguimiento del estado de la transacción

Supervisa el progreso del pago mediante código QR a través de estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

La API de Localpayment proporciona varios códigos de estado para indicar el progreso y el resultado del pago en la respuesta.

| Código | Estado | Descripción |
| :- | :- | :- |
| `103` | `APPROVED` | El payin se confirmó, pero aún no se ha abonado. |
| `200` | `Completed` | El payin se ha completado. |
| `811` | `Rejected` | La cantidad solicitada es mayor o menor que los valores máximos/mínimos permitidos. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Probando tu integración

### Entorno de pruebas

Utiliza el entorno de prueba para realizar las pruebas:

```
https://api.stage.localpayment.com/api/payin/
```

### Escenarios de prueba de QR

Verifica que tu integración gestione estos escenarios:

1. **Pago exitoso**: Completa el escaneo del código QR y el proceso de pago.
2. **Caducidad de los códigos QR**: Gestiona correctamente los códigos QR caducados.
3. **Múltiples intentos de pago**: Se escaneó el mismo código QR varias veces.
4. **Actualizaciones de estado**: Gestión de webhooks y sondeo de estado.

***

## Próximos pasos

Tras implementar los pagos mediante código QR, ten en cuenta estas funcionalidades adicionales:

> [card] [Reembolsar la transacción](https://docs.localpayment.com/es/docs/refund-apm-payment.md)
>
> Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación para obtener más detalles.

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.


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