PIX QR Code

Ciclo de Vida

Fluxo de Criação e Pagamento

Status

Status	Descrição
CREATED	QR Code criado, aguardando pagamento
PROCESSING	Pagamento em processamento
PAID	QR Code pago com sucesso
FAILED	Falha no processamento do pagamento
EXPIRED	QR Code expirado sem pagamento

---

POST /v1/account/{id}/pix/qrcode/dynamic

Cria um QR Code PIX dinâmico associado à conta informada. A chave PIX ativa da conta é utilizada automaticamente.

Path Parameters:

Parâmetro	Tipo	Descrição
id	UUID	ID da conta bancária (UUID v4)

Request:

curl --request POST \
  --url 'https://api-banking.barte.com/v1/account/53bcb30e-c2df-4316-bbff-161ee01e34be/pix/qrcode/dynamic' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100.00,
    "description": "Pagamento de serviço",
    "expiration": 86400,
    "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
    "payer": {
      "name": "John Doe",
      "document": "12345678901"
    }
  }'

Campos — Request

Campo	Tipo	Obrigatório	Validação
amount	BigDecimal	Sim	Deve ser maior que zero. Ex: 100.00
description	String	Não	Descrição do pagamento. Ex: Pagamento de serviço
expiration	Integer	Não	Tempo de expiração em segundos. Default: 86400 (24 horas). Ex: 3600
externalId	String	Não	ID de referência do parceiro. Ex: f1619a39-429f-4cc5-97fe-2da75b2e7f44
payer	Object	Não	Dados do pagador (ver tabela abaixo)

Campos — Payer

Campo	Tipo	Obrigatório	Validação
name	String	Não	Nome completo do pagador. Ex: John Doe
document	String	Não	CPF (11 dígitos) ou CNPJ (14 dígitos). Ex: 12345678901

Response — 201 Created:

{
  "id": "53bcb30e-c2df-4316-bbff-161ee01e34be",
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
  "status": "CREATED",
  "description": "Pagamento de serviço",
  "pixKey": "486c486b-ddcd-495a-837a-be52f5989f3e",
  "amount": 100.00,
  "expiration": 86400,
  "expiresAt": "2026-03-13T19:16:15.46418",
  "qrCode": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/pc/p/v2/56b07da2bef94006adede26591fcf8b65204000053039865802BR5925NEW COMPANY BANKING 008706009SAO PAULO61080807215562070503***630446CD",
  "payer": {
    "name": "John Doe",
    "document": "12345678901"
  }
}

Campos — Response

Campo	Tipo	Descrição
id	UUID	ID do QR Code gerado
accountId	UUID	ID da conta bancária associada
externalId	String	ID de referência do parceiro (se informado)
status	String	Status do QR Code. Ver tabela de status
description	String	Descrição do pagamento
pixKey	String	Chave PIX utilizada para geração do QR Code
amount	BigDecimal	Valor em reais. Ex: 100.00
expiration	Integer	Tempo de expiração em segundos
expiresAt	String	Data/hora de expiração (ISO 8601). Ex: 2026-03-13T19:16:15.46418
qrCode	String	Payload do QR Code PIX (EMV)
payer	Object	Dados do pagador (se informado)
payer.name	String	Nome do pagador
payer.document	String	CPF ou CNPJ do pagador

Response — 400 Bad Request (validação):

{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request amount - Amount must be greater than zero"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-03-12T19:16:15Z"
  }
}

Response — 404 Not Found:

{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Account 53bcb30e-c2df-4316-bbff-161ee01e34be not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-03-12T19:16:15Z"
  }
}

Status Codes:

Status	Descrição
201 Created	QR Code criado com sucesso
400 Bad Request	Dados inválidos ou campos obrigatórios ausentes
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Sem acesso à conta
404 Not Found	Conta não encontrada

---

GET /v1/account/{id}/pix/qrcode/{qrcodeId}

Consulta os detalhes de um QR Code PIX por ID. O status de expiração é verificado e atualizado automaticamente.

O qrcodeId pode ser tanto o ID interno (UUID) quanto o externalId do QR Code.

Path Parameters:

Parâmetro	Tipo	Descrição
id	UUID	ID da conta bancária (UUID v4)
qrcodeId	UUID	ID do QR Code ou externalId

Request:

curl --request GET \
  --url 'https://api-banking.barte.com/v1/account/53bcb30e-c2df-4316-bbff-161ee01e34be/pix/qrcode/a1b2c3d4-5678-90ab-cdef-1234567890ab' \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
  "type": "cob",
  "status": "PAID",
  "qrCode": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/pc/p/v2/56b07da2bef94006adede26591fcf8b65204000053039865802BR5925NEW COMPANY BANKING 008706009SAO PAULO61080807215562070503***630446CD",
  "amount": 100.00,
  "description": "Pagamento de serviço",
  "expiration": 86400,
  "expiresAt": "2026-03-13T19:16:15.46418",
  "pixKey": "486c486b-ddcd-495a-837a-be52f5989f3e",
  "keyType": "EVP",
  "payerName": "John Doe",
  "payerDocument": "12345678901",
  "recipientName": "John Ham",
  "city": "Sao Paulo",
  "postalCode": "01234567"
}

Campos — Response

Campo	Tipo	Descrição
id	UUID	ID do QR Code
externalId	String	ID de referência do parceiro (se informado)
type	String	Tipo do QR Code: cob (cobrança imediata) ou cobv (cobrança com vencimento)
status	String	Status atual do QR Code. Ver tabela de status
qrCode	String	Payload do QR Code PIX (EMV)
amount	BigDecimal	Valor em reais. Ex: 100.00
description	String	Descrição do pagamento
expiration	Integer	Tempo de expiração em segundos
expiresAt	String	Data/hora de expiração (ISO 8601)
pixKey	String	Chave PIX utilizada
keyType	String	Tipo da chave PIX. Ex: EVP, CPF, CNPJ, EMAIL, PHONE
payerName	String	Nome do pagador (se informado na criação)
payerDocument	String	CPF ou CNPJ do pagador (se informado na criação)
recipientName	String	Nome do recebedor
city	String	Cidade do recebedor
postalCode	String	CEP do recebedor

Response — 404 Not Found:

{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "PIX QR Code a1b2c3d4-5678-90ab-cdef-1234567890ab not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-03-12T19:16:15Z"
  }
}

Status Codes:

Status	Descrição
200 OK	QR Code encontrado
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Sem acesso à conta
404 Not Found	QR Code não encontrado

---

GET /v1/account/{id}/pix/qrcode

Lista os QR Codes PIX de uma conta com paginação. O status de expiração é verificado automaticamente.

Path Parameters:

Parâmetro	Tipo	Descrição
id	UUID	ID da conta bancária (UUID v4)

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
pix-type	String	Sim	Tipo do QR Code: cob ou cobv
page	Integer	Não	Número da página (zero-based). Default: 0
size	Integer	Não	Itens por página. Default: 20
sort	String	Não	Ordenação. Campos permitidos: createdAt, updatedAt. Ex: createdAt,desc

Request:

curl --request GET \
  --url 'https://api-banking.barte.com/v1/account/53bcb30e-c2df-4316-bbff-161ee01e34be/pix/qrcode?pix-type=cob&page=0&size=10&sort=createdAt,desc' \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

{
  "content": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "externalId": "f1619a39-429f-4cc5-97fe-2da75b2e7f44",
      "status": "PAID",
      "amount": 100.00,
      "expiresAt": "2026-03-13T19:16:15.46418"
    },
    {
      "id": "b2c3d4e5-6789-01bc-defa-2345678901bc",
      "externalId": null,
      "status": "EXPIRED",
      "amount": 50.00,
      "expiresAt": "2026-03-12T10:00:00.000000"
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    }
  },
  "totalElements": 2,
  "totalPages": 1,
  "last": true,
  "first": true,
  "numberOfElements": 2,
  "empty": false
}

Campos — Objeto do Array content

Campo	Tipo	Descrição
id	UUID	ID do QR Code
externalId	String	ID de referência do parceiro (se informado)
status	String	Status do QR Code. Ver tabela de status
amount	BigDecimal	Valor em reais. Ex: 100.00
expiresAt	String	Data/hora de expiração (ISO 8601)

Status Codes:

Status	Descrição
200 OK	Lista retornada com sucesso
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Sem acesso à conta
404 Not Found	Conta não encontrada