# PIX QR Code ## Ciclo de Vida ### Fluxo de Criação e Pagamento ```mermaid sequenceDiagram participant P as Parceiro participant B as Banking API participant BC as Banco Central P->>B: POST /v1/account/{id}/pix/qrcode/dynamic B-->>P: 201 Created (status: CREATED) Note over B: QR Code gerado via provedor BC->>B: Pagamento recebido B-->>P: status: PAID ``` ### 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:** ```bash 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:** ```json { "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):** ```json { "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:** ```json { "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:** ```bash 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:** ```json { "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:** ```json { "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:** ```bash 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:** ```json { "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 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.barte.com/banking/api/pix-qrcode.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.