# Crear pagos con código QR Tarjeta Presente (Cuenta-a-Cuenta)

Esta guía le orientará en el procesamiento de un **pago con código QR cuenta-a-cuenta** en un entorno **Tarjeta Presente** utilizando la Getnet Regional API. En este flujo, el terminal físico del comercio solicita un código QR EMV dinámico a la pasarela (gateway), lo muestra al cliente, y el cliente lo escanea con su aplicación bancaria para autorizar el pago directamente desde su cuenta bancaria.

<Callout type="warning">

Esto no es Pix. El flujo de código QR descrito aquí es un método de pago **cuenta-a-cuenta** procesado a través de las redes Visa/Mastercard. Actualmente está disponible **solo para Chile**. La compatibilidad con otros países (Argentina a través de Transferencia 3.1, Brasil a través de Pix) se añadirá en futuras versiones.

</Callout>

## Requisitos

Antes de iniciar una solicitud de código QR, asegúrese de lo siguiente:

- **Credenciales de la API**: Obtenga su `client_id` y `client_secret` a través del equipo de Soporte a la Integración.
- **Autenticación**: Genere un token Bearer a través del [punto de enlace de Autenticación](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/authentication).
- **Hardware del terminal**: Un dispositivo físico (POS/TEF) capaz de mostrar imágenes o texto de alta resolución para la representación del código QR.
- **Número de serie**: El `serial_number` físico del dispositivo debe proporcionarse en cada solicitud.
- **Compatibilidad de marcas**: Actualmente disponible exclusivamente para **Visa** y **Mastercard**.

## Cómo funciona

El flujo de código QR de Tarjeta Presente tiene tres etapas:

| Etapa | Actor | Acción |
| --- | --- | --- |
| **1. Generar** | Terminal → API | El terminal envía una solicitud `POST` al punto de enlace de código QR y recibe una carga de datos QR EMV (`HTTP 201`). |
| **2. Mostrar** | Terminal → Cliente | El terminal representa la cadena QR como una imagen escaneable en su pantalla. El cliente la escanea con su aplicación bancaria. |
| **3. Confirmar** | API → Terminal | El pago se autoriza de forma asíncrona. El terminal confirma el estado final a través de webhooks o del punto de enlace Get Transaction. |

<Callout type="warning">

**Caducidad**: Los códigos QR generados a través de este punto de enlace caducan a los **1 minuto y 50 segundos**. Si el cliente no escanea y autoriza dentro de este plazo, descarte el código y genere uno nuevo.

</Callout>

## Proceso de pago con código QR

### Paso 1: Crear la solicitud de código QR

Envíe una solicitud `POST` al [punto de enlace de código QR](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/qrcode) para generar la carga de datos del QR EMV.

#### Campos de la solicitud

| Campo | Tipo | Restricciones | Descripción | Obligatorio |
| --- | --- | --- | --- | --- |
| `idempotency_key` | String | 1–64 caracteres, alfanumérico + `.-_` | Clave única para evitar solicitudes duplicadas. | **Sí** |
| `request_id` | String (UUID) | 36 caracteres | Identificador único para esta solicitud. | **Sí** |
| `order_id` | String | 1–36 caracteres | Su referencia interna del pedido. | **Sí** |
| `amount` | Entero | En céntimos | Importe de la transacción (p. ej., `10000` = 100,00). | **Sí** |
| `currency` | String | ISO 4217 | Código de moneda (p. ej., `CLP`). | **Sí** |
| `payment_method` | Enum | `PURCHASE`, `INVOICE`, `COLLECTION` | El tipo de operación de pago. | **Sí** |
| `transaction_type` | Enum | `NO_INTEREST`, `WITH_INTEREST` | Si se aplican intereses por cuotas. | **Sí** |
| `serial_number` | String | — | Número de serie único del terminal físico. | **Sí** |
| `payment_id` | String (UUID) | 36 caracteres | Identificador de pago opcional si se ha asignado previamente. | No |
| `additional_data.fee.range_acquirer` | String | — | Código del rango de tasa del adquirente. | No |
| `additional_data.fee.range_issuer` | String | — | Código del rango de tasa del emisor. | No |

#### Ejemplo de solicitud

```bash
curl --location --request POST 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/qrcode' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'x-transaction-channel-entry: XX' \
--data-raw '{
  "idempotency_key": "cp-qr-visa-001",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-101",
  "amount": 10000,
  "currency": "CLP",
  "payment_method": "PURCHASE",
  "transaction_type": "NO_INTEREST",
  "serial_number": "CL00027L"
}'
```

### Paso 2: Mostrar el código QR

Si la solicitud tiene éxito, se devuelve `HTTP 201` con un cuerpo JSON que contiene la cadena EMV `qr_code` dentro de `additional_data`. Represente esta cadena como una imagen escaneable en la pantalla del terminal.

#### Campos de la respuesta

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `payment_id` | String (UUID) | Identificador único de este pago. Utilícelo para consultar el estado final. |
| `seller_id` | String (UUID) | Identificador de la cuenta del vendedor. |
| `request_id` | String (UUID) | Repite el `request_id` enviado en la solicitud. |
| `idempotency_key` | String | Repite la `idempotency_key` enviada en la solicitud. |
| `order_id` | String | Repite el `order_id` enviado en la solicitud. |
| `amount` | Entero | Importe de la transacción en céntimos. |
| `currency` | String | Código de moneda ISO 4217. |
| `status` | Enum | Resultado de la generación del código QR: `APPROVED`, `DENIED`, `ERROR` o `ACCEPTED`. |
| `reason_code` | String (2 caracteres) | Código de retorno de la pasarela o del adquirente. |
| `reason_message` | String | Mensaje de retorno de la pasarela en lenguaje natural. |
| `additional_data.transaction_id` | String | Identificador de la transacción generado por la pasarela. |
| `additional_data.creation_date_qrcode` | String (ISO 8601) | Marca de tiempo de creación del código QR. |
| `additional_data.expiration_date_qrcode` | String (ISO 8601) | Marca de tiempo en la que caduca el código QR (110 segundos tras su creación). |
| `additional_data.qr_code` | String | La cadena del código QR EMV para representar como imagen escaneable. |
| `additional_data.qr_code_emv_type` | Enum | Tipo de código QR: `static` o `dynamic`. |
| `additional_data.third_party_qr_code_id` | String | Identificador del código QR generado por el proveedor externo. |
| `additional_data.third_party_order_id` | String | Identificador del pedido generado por el proveedor externo. |

#### Ejemplo de respuesta (`HTTP 201`)

```json
{
  "payment_id": "03ec0ede-3bc9-42dd-a71b-1c3a670b2b89",
  "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "idempotency_key": "cp-qr-visa-001",
  "order_id": "ORDER-101",
  "amount": 10000,
  "currency": "CLP",
  "status": "APPROVED",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "additional_data": {
    "transaction_id": "890005df15a2-0b1e-4c6e-8ece",
    "qr_code": "00020101021241260009cl.getnet98097605970315204...",
    "qr_code_emv_type": "dynamic",
    "creation_date_qrcode": "2026-02-19T14:48:00.000Z",
    "expiration_date_qrcode": "2026-02-19T14:49:50.000Z",
    "third_party_qr_code_id": "61260970G",
    "third_party_order_id": "61260970G"
  }
}
```

<Callout type="note">

`status: "APPROVED"` significa que el **código QR se ha generado correctamente**, pero **no** indica que el cliente haya pagado. Debe verificar el estado real de la transferencia de fondos por separado utilizando el `payment_id`.

</Callout>

**Para procesar la respuesta:**

1. Extraiga `additional_data.qr_code` y represéntelo como una imagen QR escaneable en la pantalla del TPV (POS).
2. Inicie un temporizador de cuenta atrás utilizando `expiration_date_qrcode` para descartar automáticamente los códigos caducados.
3. Guarde el `payment_id` para consultar el estado de la autorización final en el Paso 3.

### Paso 3: Verificar el estado de la transacción

Una vez que el cliente haya escaneado el código QR, verifique que el pago se haya completado utilizando uno de estos métodos:

- **Webhooks**: Configure su integración para recibir notificaciones asíncronas del estado del pago.
- **Consulta (Polling)**: Llame al [punto de enlace Get Transaction](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/{payment_id}) con el `payment_id` devuelto en el Paso 2.

## Respuestas de error

| Código HTTP | Descripción |
| --- | --- |
| `400 Bad Request` | Solicitud mal formada o falta de campos obligatorios. |
| `401 Unauthorized` | Token Bearer no válido o caducado. |
| `404 Not Found` | Recurso referenciado no encontrado. |
| `422 Unprocessable Entity` | Solicitud bien formada pero falló la validación de la lógica de negocio. |
| `429 Too Many Requests` | Límite de frecuencia excedido. |
| `500 Internal Error` | Error inesperado en el servidor. |
| `503 Service Unavailable`| Servicio temporalmente no disponible. |
| `504 Gateway Timeout` | La pasarela no recibió una respuesta a tiempo. |

## Pasos siguientes

Ahora que conoce los pagos con código QR, explore estas funciones relacionadas de Tarjeta Presente:

- **[Pagos de un solo paso](/es/global-api/sep-card-present/payment-guides-cp/single-step-payment-cp)**: Procese ventas estándar de lectura de chip y banda magnética.
- **[Pagos preautorizados](/es/global-api/sep-card-present/payment-guides-cp/pre-auth-payment-cp)**: Gestione flujos en dos pasos para reservas y capturas diferidas.
- **Cancelar un pago**: Revierta una transacción capturada previamente.
- **Requisitos del terminal**: Verifique que su dispositivo admita la visualización de códigos QR.
- **Flujo de Tarjeta Presente**: Revise los diagramas de secuencia de bajo nivel de todos los flujos.