> ## 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 (Peru)

> A Localpayment permite que os comerciantes processem pagamentos instantâneos por meio do sistema de pagamento QR padronizado do Peru. Este guia descreve o processo para iniciar pagamentos baseados em QR Code através da API da Localpayment, detalhando os parâmetros necessários, o tratamento de respostas e a interpretação dos códigos de status para uma integração perfeita com a rede de pagamentos interoperável do Peru.

## Antes de começar

Certifique-se de ter:

* [Credenciais de API ](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso).

***

## Carteiras suportadas

* [Credenciais de API ](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso).

***

## Passo 1. Criar pagamento por QR Code

Para gerar um código QR para cobrança de pagamentos, envie uma solicitação `POST` ao endpoint [Criar Payin](https://docs.localpayment.com/pt-br/reference/payins.md) com parâmetros específicos de QR Code.

> [!NOTE]
>
> **Validade**
>
> Por padrão, uma ordem de pagamento por Transferência Bancária QR expira **1 dia após a sua criação**. Para personalizar o período de expiração (**1 a 7 dias**) de acordo com as necessidades da sua empresa, entre em contato com o seu gerente de contas para configuração.

### Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave específicos para pagamentos por QR Code:

| Objeto | Descrição | Obrigatório |
| - | - | - |
| `paymentMethod.type` | Deve ser `BankTransfer`. | ✅ |
| `paymentMethod.code` | Use `6080` para o QR do Peru. | ✅ |
| `sender` | Informações do remetente para fins de conformidade. | ✅ |
| `merchant` | Detalhes do comerciante/empresa. | ✅ |
| `paymentMethod` | Configuração do método de pagamento. | ✅ |
| `amount` | Valor da transação. | ✅ |
| `currency` | Código da moeda da transação. | ✅ |
| `country` | Deve ser `PER`. | ✅ |

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/payins.md) na solicitação.

> [!WARNING]
>
> **Limites de valor para o Peru:** Pagamentos via QR Code exigem um mínimo de 1 PEN e não podem exceder 500 PEN por transação. Cada usuário tem um limite diário de 2000 PEN em todas as transações.

### Exemplo de solicitação

Abaixo segue um exemplo usando `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}}"
    }
}
'
```

***

## Etapa 2. Lidar com a resposta

### Resposta bem-sucedida

A criação bem-sucedida de um pagamento por QR Code inclui os dados do código QR e os detalhes do pagamento:

```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 resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `qr.image` | Imagem PNG do código QR codificada em Base64. | Exibição direta sem geração adicional. |
| `qr.expirationDate` | Registro de data e hora em que o QR Code se torna inválido. | Exibir cronômetro de contagem regressiva e lidar com a lógica de expiração. |
| `qr.paymentInstructions` | Instruções de pagamento. | Exibir instruções de pagamento fáceis de usar. |
| `externalId` | Seu número de referência original. | Conciliação interna e correspondência de pedidos. |
| `status.code` | Estado atual da transação (`100` = `INPROGRESS`) | Determine os próximos passos no fluxo de pagamento. |
| `date.creationDate` | Quando a transação foi criada. | Análise e monitoramento de desempenho. |

### Resposta de erro

Quando a geração do QR Code falhar, você receberá informações detalhadas sobre o erro:

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

***

## Etapa 3. Exibir o código QR e processar o pagamento

1. **Exibição de QR Code**: Apresente o código QR ao cliente através do canal escolhido.
2. **Leitura do código QR pelo aplicativo do banco**: O cliente escaneia o código QR com o aplicativo móvel do banco.
3. **Autorização de pagamento**: O cliente confirma o pagamento em seu ambiente bancário.
4. **Confirmação em tempo real**: o Localpayment recebe notificação de pagamento instantaneamente.
5. **Atualização de status**: Seu sistema recebeu um webhook com a confirmação de pagamento.

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

### Melhores práticas para exibição de QR Code

* Tamanho mínimo de exibição: 250x250 pixels para digitalização em dispositivos móveis.
* Mantenha a proporção de 1:1 sem distorção.
* Garanta alto contraste (escuro sobre fundo claro).
* Adicione uma zona de silêncio (borda branca) ao redor do código QR.
* Inclua um texto alternativo (ex.: "Pagamento por código QR").
* Exibir instruções de pagamento claras.
* Gerenciar o tempo de vida (TTL) e a expiração.

***

## Etapa 4. Acompanhe o status da transação

Acompanhe o progresso do pagamento por QR Code através destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.

| Código | Status | Descrição |
| :- | :- | :- |
| `103` | `APPROVED` | O Payin foi confirmado, mas ainda não foi creditado. |
| `200` | `Completed` | O Payin foi concluído. |
| `811` | `Rejected` | O valor solicitado é maior ou menor que os valores máximo/mínimo permitidos. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Ambiente de Sandbox

Utilize o ambiente de teste para realizar os procedimentos:

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

### Cenários de teste de QR

Verifique se sua integração lida com esses cenários:

1. **Pagamento concluído com sucesso**: Leitura do código QR e fluxo de pagamento finalizados.
2. **Expiração de QR Code**: Lide com códigos QR expirados de forma adequada.
3. **Múltiplas tentativas de pagamento**: o mesmo código QR foi lido várias vezes.
4. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Próximos passos

Após implementar pagamentos por QR Code, considere estas funcionalidades adicionais:

> [card] [Reembolsar a transação](https://docs.localpayment.com/pt-br/docs/refund-apm-payment.md)
>
> Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação para obter detalhes.

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Você pode obter informações detalhadas sobre as transações usando a API Localpayment.


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