API Pix Blu

A API de Pix permite criar cobranças, consultar o status de um pagamento e realizar devoluções. Pode ser utilizada tanto por fornecedores quanto por varejistas.

Requisitos

  • Chave Pix criada na sua conta digital Blu. (Veja aqui como criar)

  • Token de autenticação para usar as APIs Para receber seu token, fale com seu Executivo de Contas ou com o suporte da Blu. Eles vão liberar o acesso para você.

Orientações

  • Preencha todos os campos obrigatórios ao fazer suas requisições.

  • Para obter o Pix copia e cola ou o QR Code, use a API Consultar Pix.

Criar Pix

POST https://api.blu.com.br/b2b/pix/

Este endpoint cria uma cobrança Pix com as informações enviadas, como valor e descrição, para que o cliente realize o pagamento.

Ele retorna um identificador único (UUID), que permite consultar o status da cobrança e obter o código QR ou o código de pagamento (copia e cola).

Headers

Chave
Valor
Origatório
Descrição

Authorization

<token_de_autenticação>

Sim

Token para autenticação da API

Content-Type

application/json

Sim

Indica que o corpo da requisição é JSON

Request Body

{
  "expires_at": "AAAA-MM-DD",
  "description": "Descrição Externa do Pix",
  "description_internal": "Descrição Interna do Pix",
  "value": "0.00"
}
Campo
Tipo
Obrigatório
Descrição

expires_at

string

Sim

Data de expiração da cobrança no formato AAAA-MM-DD. Após essa data, o Pix não poderá ser pago.

description

string

Não

Descrição externa que será exibida para o cliente no momento do pagamento.

description_internal

string

Não

Descrição interna, utilizada apenas para controle e organização pela empresa. Não aparece para o cliente.

value

string

Sim

Valor da cobrança em formato monetário, com duas casas decimais. Exemplo: "100.50" para representar R$ 100,50.

Responses

Pix criado com sucesso Codigo: 200 OK

{
    "transaction_token": "XXXXXXXX-XXXXXXXXXX-XXXXXXX-XXXXXXXX-XXXX-XXXXXXXXXXXXX"
}

O retorno da criação do Pix é um JSON com um único campo: o transaction_token (UUID). Esse token deve ser usado na API Consultar Pix para obter os dados do Pix e acompanhar o status da transação.

Exemplos de erro

{
    "message": "Usuário não encontrado para o token informado."
}

Curl da requisição

curl --location 'https://api.blu.com.br/b2b/pix/' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
        "expires_at": "AAAA-MM-DD",
        "description": "Descrição Externa do Pix",
        "description_internal": "Descrição Interna do Pix",
		"value": "0.00"
}'

Consultar Pix

GET https://api.blu.com.br/b2b/pix/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Este endpoint é responsável por consultar os dados e o status de um Pix criado via API, usando seu ID.

Query Parameters

Campo
Valor
Descrição
Obrigatório

transaction_token

<uuid_do_pix>

Identificador único (UUID) retornado na criação do Pix. É usado para realizar a consulta.

Sim

Headers

Chave
Valor
Descrição
Origatório

Authorization

<token_de_autenticação>

Token para autenticação da API

Sim

Responses

Consulta realizada com sucesso Código: 200 OK

{
    "id": "XXXXXXXXXXXXXX-XXXXXXX-XXXXXX-XXXXXXX-XXXXXXXXXXXX",
    "tx_id": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "transaction_token": "XXXXXXXX-XXXXXXX-XXXXXX-XXXXXXX-XXXXXX-XXXXXXXXXXXX",
    "status": "status retornado",
    "expires_at": "YYYY-MM-DD",
    "description": "Descrição do Pix",
    "description_internal": "Descrição do Pix no Portal Blu",
    "value": "00.00",
    "created_at": "YYYY-MM-DDTHH:MM:SS.SSSZ",
    "emv": "pix copia e cola",
    "qr_code_base64": "url do qr code"
}

Descrição dos campos

Campo
Tipo
Descrição

id

string

Identificador interno do Pix.

tx_id

string

Identificador da transação Pix (TXID).

transaction_token

string

Identificador usado para realizar a consulta do Pix.

status

string

Status atual da cobrança Pix. Exemplo: active, paid, expired.

expires_at

string

Data de expiração do Pix no formato YYYY-MM-DD. Após essa data, não poderá ser pago.

description

string

Descrição visível ao cliente.

description_internal

string

Descrição interna, usada apenas para controle.

value

string

Valor da cobrança, com duas casas decimais. Exemplo: "100.50".

created_at

string

Data e hora da criação da cobrança, no formato YYYY-MM-DDTHH:MM:SS.SSSZ.

emv

string

Código "copia e cola" do Pix.

qr_code_base64

string

Imagem do QR Code em formato base64.

Exemplos de erros

{
    "message": "Usuário não encontrado para o token informado."
}

Curl da requisição

curl --location --globoff 'https://api.blu.com.br/b2b/pix/{transaction-token}' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXX'

Devolução de Pix

POST https://api.blu.com.br/b2b/pix/refund

Este endpoint realiza a devolução total ou parcial de um Pix já pago. A partir dos dados enviados, ele registra a devolução para que o valor seja retornado ao pagador.

Headers

Chave
Valor
Descrição
Origatório

Authorization

<token_de_autenticação>

Token para autenticação da API

Sim

Request Body

{
  "movement_id": "string",
  "value": "number",
  "reason": "string"
}
Campo
Tipo
Descrição
Obrigatório

movement_id

string

Identificador da movimentação do Pix que será devolvido.

Sim

value

string

Valor da devolução, que pode ser parcial ou total.

Não

reason

string

Motivo da devolução, uma breve descrição do estorno.

Sim

Responses

Pix devolvido com sucesso Código: 200 OK

{
    "client_transaction": {
        "uuid": "XXXXXXX-XXXXXX-XXXXX-XXXXXXXX-XXXXXXXXXXXXX",
        "gross_value": "-00.00",
        "happened_at": "YYYY-MM-DDTHH:MM:SS.SSS-00:00",
        "released_at": "YYYY-MM-DD",
        "status": "status"
    }
}

Importante! A API de Devolução de Pix não impede que você informe um valor maior do que o pago. Mas a devolução só acontece e aparece na seção refunds da Consulta Pix se o valor for igual ou menor ao valor pago.

Exemplos de erro

{
    "message": "Usuário não encontrado para o token informado."
}

Curl da requisição

curl --location 'https://api.blu.com.br/b2b/pix/refund' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
        "movement_id": "XXXXXXXXXXXXXXXXXXXXXX",
        "reason": "Motivo para Devolução",
        "value": "00.00"
}'
1KB
Pix.postman_collection.zip
archive
Open

Webhook Pix

Esta ferramenta notifica seu sistema somente quando um Pix é pago. A Blu envia uma notificação com os detalhes da transação no momento em que o pagamento é confirmado.

API de teste

Use esta API para testar e visualizar o retorno do webhook quando o status de um Pix for atualizado.

PUT https://api.blu.com.br/b2b/webhook/pix

Orientações:

  • Forneça a URL de callback ao time responsável pela implantação, para que você receba as notificações.

  • Use o token de autenticação no header da requisição.

Header

Chave
Valor
Descrição
Obrigatório

Accept

version=1

Não

Content-Type

application/json

Não

Authorization

xxxxxxxxxxxxx

Token de operação.

Sim

Cookie

xxxxxxxxxxxxxxxxxxxxxx

Não

Webhook

"pix"

Tipo da cobrança

Sim

Body 

{
    "status" : "success"
}

Você também pode deixar o body da requisição vazio — o comportamento será o mesmo.

Responses

Código: 200 OK

{
  "created_at": "2025-05-12 14:59:49 -0300",
  "debit_party": {
    "account": "6353625",
    "bank": "18236120",
    "branch": "1",
    "personType": "NATURAL_PERSON",
    "taxId": "12000436774",
    "accountType": "TRAN",
    "name": "Vinicius Jonathan Lopes Silva"
  },
  "debt_id": "f83416e6-061b-4390-90e9-eaa6f7d1e637",
  "e2e_id": "E18236120202505121759s01407eef6b",
  "id": "9e23aecd-e438-455b-a137-4678314a3eca",
  "movement_id": "1000659076114",
  "pactual_id": "71926b53-8c78-452a-9391-6343b6625672",
  "receiver_uuid": "7747af88",
  "request_id": "8a2de775-d89e-45ea-99cd-e301279496f9",
  "updated_at": "2025-05-12 14:59:49 -0300",
  "value": "0.05"
}

Descrição dos campos

created_at

Data e hora em que a notificação foi gerada.

debit_party.account

Número da conta do pagador.

debit_party.bank

Código do banco do pagador.

debit_party.branch

Número da agência do pagador.

debit_party.personType

Tipo de pessoa do pagador

NATURAL_PERSON → Pessoa física LEGAL_PERSON → Pessoa jurídica

debit_party.taxId

CPF ou CNPJ do pagador, conforme o personType.

debit_party.accountType

Tipo de conta (TRAN para conta de transação, por exemplo).

CACC → Conta corrente SVGS → Conta poupança TRAN → Conta de pagamento SLRY → Conta salário

debit_party.name

Nome completo do pagador.

debt_id

Identificador interno da dívida relacionada ao Pix.

e2e_id

Identificador único da transação no padrão do Pix (End-to-End ID).

id

Identificador únicodo evento registrado.

movement_id

Código da movimentação financeira associada ao Pix.

pactual_id

Identificador interno utilizado pelo parceiro financeiro.

receiver_uuid

Identificador do recebedor dentro do ambiente da Blu.

request_id

Identificador da solicitação que originou o evento, útil para rastreamento.

updated_at

Data e hora da última atualização do status desta transação.

value

Valor envolvido no evento, geralmente o valor pago ou devolvido, em reais.

PreviousAPI Link de Pagamento

Last updated

Was this helpful?