InícioReferência

Criação de Cobrança PIX

AutenticaçãoCopied!

Antes de iniciar qualquer integração, você deve obter sua API Key para autenticação na plataforma.

Para mais detalhes, consulte a documentação de autenticação.

Autenticação

IntegraçãoCopied!

Esta integração permite gerar uma cobrança via PIX para que uma pessoa física ou jurídica realize o pagamento. A resposta conterá o QR Code (em base64) e a chave PIX.

Preparação da RequisiçãoCopied!

  1. Obtenha sua API Key: Utilize a chave para autenticar suas requisições.

  2. Monte o corpo da requisição: Garanta que o JSON enviado siga as regras abaixo:

    • Parâmetros obrigatórios: Os campos como type, fullName, document, transaction etc. devem ser enviados corretamente.

    • Validação do documento: O campo document deve conter um CPF ou CNPJ válido, obedecendo as regras de validação dos dígitos verificadores.

    • Valor da transação: O campo value deve ser um número float positivo (maior que zero) com até duas casas decimais.

    • Data de vencimento: O campo dueDate deve ser uma data igual ou posterior à data atual.

    • Identificador único: O campo externalId deve ser único no ecossistema, possibilitando a identificação interna da transação.

Exemplo de Corpo da Requisição
{
    "type":"PIX",
    "payer": {
        "fullName":"John Marvin",
        "document":"12312312387",
        "contact":{
            "phone":"+5537988996655",
            "mail":"[email protected]"
        },
        "address":{
            "zipCode":"60000000",
            "street":"Street Name",
            "neighboor":"Neighboor Name",
            "number":"123",
            "city":"City Name",
            "state":"State Name",
            "country":"Country Name"
        }
    },
    "transaction":{
        "value":100,
        "description":"Description",
        "dueDate":"2021-01-01",
        "externalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
}

Exemplo de Requisição (CURL)

Após preparar a chave de autenticação e o corpo da requisição, faça a chamada para o endpoint:

curl --request POST \
  --url https://api.firebanking.com.br/payment \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 123' \
  --data '{
  "type": "PIX",
  "payer": {
    "fullName": "John Marvin",
    "document": "12312312387",
    "contact": {
      "phone": "+5537988996655",
      "mail": "[email protected]"
    },
    "address": {
      "zipCode": "60000000",
      "street": "Street Name",
      "neighboor": "Neighboor Name",
      "number": "123",
      "city": "City Name",
      "state": "State Name",
      "country": "Country Name"
    }
  },
  "transaction": {
    "value": 100,
    "description": "Description",
    "dueDate": "2021-01-01",
    "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}'

Tratamento da RespostaCopied!

Resposta de Sucesso (Status 200)

Em caso de sucesso, a resposta retornará um JSON contendo:

Campo

Tipo

Descrição

transactionId

string

Identificador único gerado para cobrança/transação

status

string

Status da cobrança/transação.

Inicialmente, "WAITING_PAYMENT“ é o status padrão após gerar uma cobrança e aguardar o pagamento do usuário

pixQrCode

string

Imagem QRCode codificado em Base64 (data:image/png;base64)

pixCode

string

Código PIX Copia e Cola

generateTime

string | timestamp

Data/momento da geração do pagamento

paymentLink

string

URL para link de pagamento

Exemplo:

{
    "transactionId":"cd722e93-032f-45e1-b638-87a2490dcea7",
    "status":"WAITING_PAYMENT",
    "pixQrCode":"iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXXAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2kGu5DqSRNFmI/a/ZfbwVw7+Q2XLM2UWfs4CBKdIKQIXOvfe+z8AAAAAABDuf98eAAAAAAAA...",
    "pixCode":"00020101021226880014br.gov.bcb.pix2566qrcode-h.firebanking.com.br/QR/cob/EEA7B851BBAFFB546073CE80810F56AA0F95204000053039865802BR5925VICTOR NERY TEIXEIRA CONS6009Sao Paulo610905726-10062070503***630498E0",
    "generateTime":"2023-04-14T02:58:04.997Z",
    "paymentLink":"https://pay.firebanking.com.br/cd722e93-032f-45e1-b638-87a2490dcea7"
}

Exemplo de Exibição do QR CodeCopied!

Para exibir o QR Code em uma página web, utilize:

<img src="data:image/png;base64,[O_SEU_CODIGO_pixQrCode]">

Ficando parecido com:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYA...">
Resposta com Erro (Status 400, 404 ou 500)

Caso ocorra algum erro, a API retornará um status diferente de 200 acompanhado de uma mensagem de erro. Exemplo:

{
    "message": "Payer document and full name are required."
}

Para informações completas sobre os códigos de erro e os parâmetros disponíveis, consulte a referência completa da API.

[POST] /pix/v1/payment

Gera uma cobrança imediata via PIX (Cash In)