# Criar Pagamentos via QR Code Cartão Presente (Conta-para-Conta)

Este guia orienta você no processamento de um **pagamento via QR Code conta-para-conta** em um ambiente **Cartão Presente** usando a Getnet Regional API. Nesse fluxo, o terminal físico do estabelecimento solicita ao gateway um código QR EMV dinâmico, exibe-o ao cliente, e o cliente o lê com o aplicativo do seu banco para autorizar o pagamento diretamente da sua conta bancária.

<Callout type="warning">

Isso não é Pix. O fluxo de QR Code descrito aqui é um método de pagamento **conta-para-conta** processado por meio das redes Visa/Mastercard. Atualmente, está disponível **apenas para o Chile**. O suporte para países adicionais (Argentina via Transferencia 3.1, Brasil via Pix) será adicionado em versões futuras.

</Callout>

## Requisitos

Antes de iniciar uma solicitação de QR code, certifique-se do seguinte:

- **Credenciais da API**: Obtenha seu `client_id` e `client_secret` com a equipe de Suporte à Integração.
- **Autenticação**: Gere um Bearer token por meio do [endpoint de Autenticação](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/authentication).
- **Hardware do Terminal**: Um dispositivo físico (POS/TEF) capaz de exibir imagens ou texto de alta resolução para a renderização do QR code.
- **Número de Série**: O `serial_number` físico do dispositivo deve ser fornecido em cada requisição.
- **Bandeira do Cartão**: Atualmente disponível exclusivamente para **Visa** e **Mastercard**.

## Como Funciona

O fluxo de QR Code Cartão Presente tem três estágios:

| Estágio | Ator | Ação |
| --- | --- | --- |
| **1. Gerar** | Terminal → API | O terminal envia uma requisição `POST` para o endpoint de QR Code e recebe um payload QR EMV (`HTTP 201`). |
| **2. Exibir** | Terminal → Cliente | O terminal renderiza a string do QR como uma imagem escaneável em sua tela. O cliente a lê com seu aplicativo bancário. |
| **3. Confirmar** | API → Terminal | O pagamento é autorizado de forma assíncrona. O terminal confirma o status final via webhooks ou pelo endpoint Get Transaction. |

<Callout type="warning">

**Expiração**: Códigos QR gerados via este endpoint expiram após **1 minuto e 50 segundos**. Se o cliente não escanear e autorizar dentro deste intervalo, descarte o código e gere um novo.

</Callout>

## Processo de Pagamento via QR Code

### Passo 1: Criar a Requisição de QR Code

Envie uma requisição `POST` para o [endpoint QR Code](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/qrcode) para gerar o payload do QR EMV.

#### Campos da Requisição

| Campo | Tipo | Restrições | Descrição | Obrigatório |
| --- | --- | --- | --- | --- |
| `idempotency_key` | String | 1–64 chars, alfanumérico + `.-_` | Chave exclusiva para evitar requisições duplicadas. | **Sim** |
| `request_id` | String (UUID) | 36 chars | Identificador exclusivo para esta requisição. | **Sim** |
| `order_id` | String | 1–36 chars | Sua referência de pedido interno. | **Sim** |
| `amount` | Inteiro | Em centavos | Valor da transação (ex: `10000` = 100,00). | **Sim** |
| `currency` | String | ISO 4217 | Código da moeda (ex: `CLP`). | **Sim** |
| `payment_method` | Enum | `PURCHASE`, `INVOICE`, `COLLECTION` | O tipo de operação de pagamento. | **Sim** |
| `transaction_type` | Enum | `NO_INTEREST`, `WITH_INTEREST` | Se juros de parcelamento se aplicam. | **Sim** |
| `serial_number` | String | — | Número de série exclusivo do terminal físico. | **Sim** |
| `payment_id` | String (UUID) | 36 chars | Identificador de pagamento opcional, se pré-atribuído. | Não |
| `additional_data.fee.range_acquirer` | String | — | Código da faixa de taxa do adquirente. | Não |
| `additional_data.fee.range_issuer` | String | — | Código da faixa de taxa do emissor. | Não |

#### Exemplo de Requisição

```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"
}'
```

### Passo 2: Exibir o QR Code

Uma requisição bem-sucedida retorna `HTTP 201` com um corpo JSON contendo a string EMV `qr_code` dentro de `additional_data`. Renderize esta string como uma imagem escaneável na tela do terminal.

#### Campos da Resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `payment_id` | String (UUID) | Identificador exclusivo para este pagamento. Use isso para consultar o status final. |
| `seller_id` | String (UUID) | Identificador da conta do vendedor. |
| `request_id` | String (UUID) | Ecoa o `request_id` enviado na requisição. |
| `idempotency_key` | String | Ecoa a `idempotency_key` enviada na requisição. |
| `order_id` | String | Ecoa o `order_id` enviado na requisição. |
| `amount` | Inteiro | Valor da transação em centavos. |
| `currency` | String | Código de moeda ISO 4217. |
| `status` | Enum | Resultado da geração do código QR: `APPROVED`, `DENIED`, `ERROR`, ou `ACCEPTED`. |
| `reason_code` | String (2 chars) | Código de retorno do gateway ou adquirente. |
| `reason_message` | String | Mensagem de retorno legível do gateway. |
| `additional_data.transaction_id` | String | Identificador de transação gerado pelo gateway. |
| `additional_data.creation_date_qrcode` | String (ISO 8601) | Timestamp de quando o código QR foi criado. |
| `additional_data.expiration_date_qrcode` | String (ISO 8601) | Timestamp de quando o código QR expira (110 segundos após a criação). |
| `additional_data.qr_code` | String | A string do QR code EMV para renderizar como uma imagem escaneável. |
| `additional_data.qr_code_emv_type` | Enum | Tipo de código QR: `static` ou `dynamic`. |
| `additional_data.third_party_qr_code_id` | String | Identificador do código QR gerado pelo provedor terceirizado. |
| `additional_data.third_party_order_id` | String | Identificador do pedido gerado pelo provedor terceirizado. |

#### Exemplo de Resposta (`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 o **código QR foi gerado com sucesso** — **não** indica que o cliente pagou. Você deve verificar o status real da transferência de fundos separadamente usando o `payment_id`.

</Callout>

**Para processar a resposta:**

1. Extraia `additional_data.qr_code` e renderize-o como uma imagem QR escaneável na tela do POS.
2. Inicie um cronômetro de contagem regressiva usando `expiration_date_qrcode` para descartar automaticamente os códigos expirados.
3. Armazene o `payment_id` para consultar o status de autorização final no Passo 3.

### Passo 3: Verificar o Status da Transação

Depois que o cliente escanear o código QR, verifique se o pagamento foi concluído usando um destes métodos:

- **Webhooks**: Configure sua integração para receber notificações assíncronas de status de pagamento.
- **Consulta (Polling)**: Chame o [endpoint 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}) com o `payment_id` retornado no Passo 2.

## Respostas de Erro

| Código HTTP | Descrição |
| --- | --- |
| `400 Bad Request` | Requisição malformada ou campos obrigatórios ausentes. |
| `401 Unauthorized` | Bearer token inválido ou expirado. |
| `404 Not Found` | Recurso referenciado não encontrado. |
| `422 Unprocessable Entity` | A requisição foi bem-formada, mas falhou na validação da lógica de negócio. |
| `429 Too Many Requests`| Limite de taxa excedido. |
| `500 Internal Error` | Erro inesperado no servidor. |
| `503 Service Unavailable`| Serviço temporariamente indisponível. |
| `504 Gateway Timeout`| O gateway não recebeu uma resposta em tempo hábil. |

## Próximos Passos

Agora que você entende os pagamentos via QR Code, explore estes recursos relacionados de Cartão Presente:

- **[Pagamentos de Passo Único](/pt/global-api/sep-card-present/payment-guides-cp/single-step-payment-cp)**: Processe vendas padrão com chip e tarja magnética.
- **[Pagamentos Pré-autorizados](/pt/global-api/sep-card-present/payment-guides-cp/pre-auth-payment-cp)**: Gerencie fluxos em dois passos para reservas e capturas atrasadas.
- **Cancelar um Pagamento**: Estorne uma transação capturada anteriormente.
- **Requisitos do Terminal**: Verifique se o seu dispositivo suporta capacidades de exibição de QR.
- **Fluxo Cartão Presente**: Revise os diagramas de sequência de baixo nível para todos os fluxos.