Geração de QR Code Dinâmico (Cobrança Imediata)

Diagrama do Fluxo

Representação documental dos 10 passos descritos nesta jornada de QR Code Dinâmico. O recebimento via webhook depende da configuração de webhook (passo 3).

Jornada

Passo 1: Criar Chave Pix

Para o funcionamento do QR Code dinâmico é necessário possuir uma chave Pix cadastrada na conta, para isso acesse o App e crie uma chave Pix que ficará vinculada aos QR Codes gerados.

Passo 2: Gerar Token de Autenticação

Endpoint: POST /api/bank-services/security/auth/tokens

Primeiro passo obrigatório para todas as operações.

curl --location --request POST 'https://api-dev.finway.com.br/api/bank-services/security/auth/tokens' \
--header 'client_id: [seu_client_id]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "client_credentials",
    "client_id": "[seu_client_id]",
    "client_secret": "[seu_client_secret]"
}'

Resposta esperada:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

informação

Importante: Use o access_token no header x-buildersbank-authorization nas próximas requisições.

Passo 3: Configuração do Webhook

Endpoint: PUT /api/bank-services/holders/me/webhook/{CHAVE_PIX}

Para receber a confirmação de pagamento do QR Code é necessário configurar a url através da API de Webhook, a url é vinculada a Chave Pix utilizada na geração do QR Code.

curl --location --request PUT 'https://api-dev.finway.com.br/api/bank-services/holders/me/webhook/{CHAVE_PIX}' \
--header 'X-BuildersBank-Authorization: [token]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "webhookUrl": "https://meudominio.com/pix",
  "headers": {
      "x-api-key": "XXX"
  }'

Passo 4: Criar Cobrança

Endpoint: POST /api/bank-services/cob

Cria a cobrança.

{
"calendario": {
  "expiracao": 86400
},
"devedor": {
  "nome": "Elder",
  "cpf": "33188542046"
},
"valor": {
  "original": "11.00"
},
"chave": "64156062040",
"solicitacaoPagador": "Serviço realizado.",
"infoAdicionais": [
  {
    "nome": "Campo 1",
    "valor": "Informação Adicional1 do PSP-Recebedor"
  },
  {
    "nome": "Campo 2",
    "valor": "Informação Adicional2 do PSP-Recebedor"
  }
]
}

Validações automáticas:

• Chave válida
• Token valido

{
  "chave": "64156062040",
  "txid": "4107ac6bdaf44956b431bb339f2cc9e9",
  "location": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4107ac6bdaf44956b431bb339f2cc9e95204000053039865802BR5925Paulo Eduardo Silva Caval6007Eusebio62070503***63043B9C",
  "status": "ATIVA",
  "solicitacaoPagador": "Serviço realizado.",
  "calendario": {
      "criacao": "2025-12-09T00:38:37.208Z",
      "expiracao": 86400
  },
  "devedor": {
      "nome": "Elder",
      "cpf": "33188542046"
  },
  "valor": {
      "original": "11.00",
      "modalidadeAlteracao": 0
  },
  "pixCopiaECola": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4107ac6bdaf44956b431bb339f2cc9e95204000053039865802BR5925Paulo Eduardo Silva Caval6007Eusebio62070503***63043B9C",
  "infoAdicionais": [
      {
          "nome": "Campo 1",
          "valor": "Informação Adicional1 do PSP-Recebedor"
      },
      {
          "nome": "Campo 2",
          "valor": "Informação Adicional2 do PSP-Recebedor"
      }
  ],
  "revisao": 0
}

Passo 5: Consultar Cobrança

Endpoint: GET /api/bank-services/cob/{TXID}

Resposta

{
  "chave": "64156062040",
  "txid": "4107ac6bdaf44956b431bb339f2cc9e9",
  "location": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4107ac6bdaf44956b431bb339f2cc9e95204000053039865802BR5925Paulo Eduardo Silva Caval6007Eusebio62070503***63043B9C",
  "status": "ATIVA",
  "solicitacaoPagador": "Serviço realizado.",
  "calendario": {
      "criacao": "2025-12-09T00:38:37.208Z",
      "expiracao": 86400
  },
  "devedor": {
      "nome": "Elder",
      "cpf": "33188542046"
  },
  "valor": {
      "original": "11.00",
      "modalidadeAlteracao": 0
  },
  "pixCopiaECola": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4107ac6bdaf44956b431bb339f2cc9e95204000053039865802BR5925Paulo Eduardo Silva Caval6007Eusebio62070503***63043B9C",
  "infoAdicionais": [
      {
          "nome": "Campo 1",
          "valor": "Informação Adicional1 do PSP-Recebedor"
      },
      {
          "nome": "Campo 2",
          "valor": "Informação Adicional2 do PSP-Recebedor"
      }
  ],
  "revisao": 0
}

Passo 6: Cancelar Cobrança

Endpoint: PATCH /api/bank-services/cob/{TXID}

{
"status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}

Resposta

{
  "chave": "64156062040",
  "txid": "4107ac6bdaf44956b431bb339f2cc9e9",
  "location": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4107ac6bdaf44956b431bb339f2cc9e95204000053039865802BR5925Paulo Eduardo Silva Caval6007Eusebio62070503***63043B9C",
  "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR",
  "solicitacaoPagador": "Serviço realizado.",
  "calendario": {
      "criacao": "2025-12-09T00:38:37.208Z",
      "expiracao": 86400
  },
  "devedor": {
      "nome": "Elder",
      "cpf": "33188542046"
  },
  "valor": {
      "original": "11.00",
      "modalidadeAlteracao": 0
  },
  "pixCopiaECola": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4107ac6bdaf44956b431bb339f2cc9e95204000053039865802BR5925Paulo Eduardo Silva Caval6007Eusebio62070503***63043B9C",
  "infoAdicionais": [
      {
          "nome": "Campo 1",
          "valor": "Informação Adicional1 do PSP-Recebedor"
      },
      {
          "nome": "Campo 2",
          "valor": "Informação Adicional2 do PSP-Recebedor"
      }
  ],
  "revisao": 0
}

Passo 7: Consultar Cobrança Concluída

Endpoint: GET /api/bank-services/cob/{TXID}

Resposta

{
  "txid": "7fb2c51cc252407e95d9035a72c6bd4a",
  "chave": "89619467817",
  "location": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/7fb2c51cc252407e95d9035a72c6bd4a5204000053039865802BR5914Lewis Hamilton6009Sao Paulo62070503***6304C995",
  "status": "CONCLUIDA",
  "solicitacaoPagador": "Serviço realizado.",
  "calendario": {
      "criacao": "2025-12-09T21:58:21.126Z",
      "expiracao": 86400
  },
  "devedor": {
      "nome": "Elder",
      "cpf": "33188542046"
  },
  "valor": {
      "original": "15.00",
      "modalidadeAlteracao": 0
  },
  "pixCopiaECola": "https://brcode-h.sandbox.starkinfra.com/dynamic-qrcode/7fb2c51cc252407e95d9035a72c6bd4a.png",
  "infoAdicionais": [
      {
          "nome": "Campo 1",
          "valor": "Informação Adicional1 do PSP-Recebedor"
      },
      {
          "nome": "Campo 2",
          "valor": "Informação Adicional2 do PSP-Recebedor"
      }
  ],
  "pix": [
      {
          "endToEndId": "E4508883020251209185909358656168",
          "txid": "7fb2c51cc252407e95d9035a72c6bd4a",
          "valor": "15.00",
          "infoPagador": "Serviço realizado.",
          "horario": "2025-12-10T01:06:00.737Z",
          "devolucoes": []
      }
  ],
  "revisao": 0
}

Passo 8: Devolver Cobrança

Endpoint: PUT /api/bank-services/pix/{endToEndId}/devolucao/{DEVOLUCAO_ID} Ao fazer uma devolução deve ser informado um identificador único idempotente que ficará vinculado a ela.

Resposta

{
  "id": "1241234",
  "valor": "15.00",
  "horario": {
      "solicitacao": "2025-12-09T22:15:06.406Z"
  },
  "status": "EM_PROCESSAMENTO",
  "rtrId": "D36741675202512092215xzUg5VXzQFA"
}

Passo 9: Consultar Devolução

Endpoint: GET /api/bank-services/pix/{endToEndId}/devolucao/{DEVOLUCAO_ID}

Resposta

{
  "id": "1241234",
  "valor": "15.00",
  "horario": {
    "solicitacao": "2025-12-09T22:15:06.406Z",
    "liquidacao": "2025-12-09T22:15:06.406Z"
  },
  "status": "DEVOLVIDO",
  "rtrId": "D36741675202512092215xzUg5VXzQFA"
}

Passo 10: Recebimento do Webhook

A cada pagamento ou devolução de uma cobrança será feito uma requisição para o endpoint cadastrado no webhook, com o payload abaixo.

{
"pix": [
  {
    "endToEndId": "E4508883020251209195229073964130",
    "txid": "bb07a0edf44b491697ba31720fe934dd",
    "valor": "15.00",
    "horario": "2025-12-09T19:52:38.706",
    "devolucoes": [
      {
        "id": "3c38d724-1f0e-4195-8389-6764dd361a93",
        "valor": "15.00",
        "horario": {
          "solicitacao": "2025-12-09T22:55:57.330Z"
        },
        "rtrId": "D45088830202512092255StyYNF96tX3",
        "status": "DEVOLVIDO"
      }
    ]
  }
]
}