Emissão de QR Code estático

O QR Code estático foi planejado para ser utilizado em cobranças direcionadas a mais de um pagador. Ou seja, o mesmo QR Code pode ser usado várias vezes por pagadores diferentes.

Esse tipo de QR Code traz apenas informações sobre o recebedor do pagamento e possibilita definir um valor fixo ou editar o valor a ser pago pelo usuário pagador no momento de realizar a transação.

📘
Nota
O QR Code estático não possui validade e nem está sujeito a multas e juros.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

A chave de endereçamento Pix seja válida. Caso contrário, não será possível fazer a emissão.

⚠️
Importante
Se a chave de endereçamento atrelada ao QR Code for excluída após sua emissão, o QR Code ficará inválido para pagamento.

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/pix/qrCodeStatic

--request POST 'https://sandbox.hiperbanco.com.br/pix/qrCodeStatic' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
    "addressingKey": {
        "type": "EVP",
        "value": "ae518747-d422-4e51-b9e3-ee4882e9f4eb"
    },
    "amount": 1,
    "recipientName": "Andre Ferreira Batista",
    "conciliationId": "7tbg3oSIXADVuIrGeWYQs8E5k",
    "location": {
        "city": "Maceió",
        "zipCode": "57070552"
    }
}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
version	cutting-edge	Essa propriedade garante que o response da API seja retornado no formato JSON
Authorization	Bearer token	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
addressingKey	object	Obrigatório. Objeto que deverá conter informações sobre a chave de endereçamento.	—
addressingKey.type	string	Obrigatório. Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE", "EMAIL" ou "EVP".	—
addressingKey.value	string	Obrigatório. Valor da chave.	Consulte a tabela Chave de endereçamento para obter instruções de preenchimento deste campo.
amount	number	Valor do QR Code gerado.	—
recipientName	string	Nome do recebedor da transação. Campo obsoleto, não é necessário enviá-lo.	—
conciliationId	string	Identificador utilizado para conciliação dos pagamentos. Importante: para obter o conciliationID na decodificação do QR Code estático, envie-o nesta requisição.	Não aceita caracteres especiais. Apenas caracteres alfanuméricos (a–z, A–Z, 0–9). Tamanho máximo: 25 caracteres.
categoryCode	string	MCC (Merchant Category Code) é um número de quatro dígitos listado na ISO 18245 para serviços financeiros de varejo. Caso o usuário recebedor o possua, ele deve ser informado. Valor default: 0000.	—
location	object	Obrigatório. Objeto que deverá conter informações sobre a localidade do recebedor da transação.	—
location.city	string	Obrigatório. Nome da cidade do recebedor da transação.	O valor máximo é de 15 caracteres para esse campo.
location.zipCode	string	Obrigatório. Código postal do recebedor da transação.	—

👍
Dica
Para mais detalhes, recomendamos a leitura do item 2.7. Iniciação via QR Code Dinâmico, disponível no Manual de padrões para iniciação do Pix.

Chave de endereçamento

Chave	Instrução de preenchimento
CPF	11 dígitos, sem caracteres especiais.
CNPJ	14 dígitos, sem caracteres especiais.
EMAIL	Todos os caracteres em minúsculo. Tamanho máximo de 72 caracteres.
PHONE	Número de telefone celular, composto por símbolo ‘+’, seguido pelo código do país, DDD e número de celular com até nove dígitos. Ex.: +5523415162342.
EVP	Tamanho máximo de 36 caracteres. Exemplo: 123e4967-e89b-12d3-a456-426655440000.

{
    "addressingKey": {
        "type": "EVP",
        "value": "123e4567-e89b-12d3-a456-426614174000"
    },
    "amount": 1,
    "recipientName": "João da Silva",
    "conciliationId": "A1B2C3D4E5F6G7H8I9J0K1L2M",
    "categoryCode": "0000",
    "location": {
        "city": "São Paulo",
        "zipCode": "01001000"
    }
}

Resposta (Response)

O status code 200 indicará que a solicitação foi aceita com sucesso.

Sendo bem-sucedido, o retorno irá trazer o seguinte campo em formato JSON:

Nome	Tipo	Descrição
encodedValue	string	Código em base64, que contém todas as informações sobre o pagamento.

{ 
    "encodedValue": "MDAwMjAxMjYzMzAwMRici5nb3YuYmNiLnBpeDAxMTEwNTY3ODQwNDg0OTUyMDQwMDAwNTMwMzk4NjU0MDUxMC4wMTU4MDJCUjU5MTVGZXJuYW5kbyBTZWd1aW02MDA5U2FvIFBhdWxvNjEwODA0MjA1MDAwNjIwNzA1MDMqKio2MzA0Njc5Ng==" 
}

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Descrição
400	ENTRY_NOT_FOUND	Entry not found.	A chave que está sendo informada para gerar um QR Code não existe.
408	REQUEST_TIMEOUT	Transaction exceeded request limit timeout.	A requisição excedeu o tempo limite da solicitação.
422	EMV_FIELD_LENGTH_OUT_OF_RANGE	EMV Merchant Account Information field length out of range allowed.	Comprimento do campo EMV (Merchant Account Information) fora do intervalo permitido.
422	ADDRESSING_KEY_NOT_FOUND	The addressing key informed was not found for this account.	A chave Pix informada não está cadastrada na conta que está sendo usada pra gerar o QR Code.
422	QR_CODE_NOT_AVAILABLE	The requested QR Code is not available. If you have decoded it recently, please wait a few seconds and try again.	O QR Code solicitado não está disponível. Se você o escaneou recentemente, aguarde alguns segundos e tente novamente.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Evento	Descrição
PIX_QRCODE_WAS_CREATED	Um QR Code para pagamento via Pix foi emitido.