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."
}

{
    "success": false,
    "message": "A validação falhou: Data de expiração não pode estar no passado",
    "statusCode": 422
}

{
    "success": false,
    "message": "A validação falhou: Valor deve ser maior que 0",
    "statusCode": 422
}

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"
}'

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.blu.com.br/b2b/pix/',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "expires_at": "AAAA-MM-DD",
    "description": "Descrição Externa do Pix",
    "description_internal": "Descrição Interna do Pix",
    "value": "0.00"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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.

{
    "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",
    "payment_inbounds": [
        {
            "data": {
                "id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                "type": "payment_inbound",
                "attributes": {
                    "debit_party": {
                        "account": "XXXXXXXXXXX",
                        "bank": "XXXXXXXX",
                        "branch": "XXX",
                        "personType": "XXXXXXXX",
                        "taxId": "XXXXXXXXXXXX",
                        "accountType": "XXXXXX",
                        "name": "Nome de quem pagou o Pix"
                    },
                    "pactual_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                    "autorizathion_code": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    "movement_id": "XXXXXXXX",
                    "value": "00.00",
                    "debt_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                    "created_at": "YYYY-MM-DDTHH:MM:SS.SSSZ",
                    "description": "Descrição do Pix",
                    "receiver_key": null,
                    "tx_id": "XXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
    ]
}

Descrição dos campos adicionais quando o Pix for pago

Lista contendo os dados do pagamento realizado. payment_inbounds

Campo

Tipo

Descrição

data.id

string

Identificador do pagamento.

data.type

string

Tipo do objeto, normalmente payment_inbound.

attributes.debit_party.account

string

Número da conta de quem realizou o pagamento.

attributes.debit_party.bank

string

Banco do pagador.

attributes.debit_party.branch

string

Agência do pagador.

attributes.debit_party.personType

string

Tipo de pessoa: física ou jurídica.

attributes.debit_party.taxId

string

CPF ou CNPJ do pagador.

attributes.debit_party.accountType

string

Tipo de conta: corrente, poupança etc.

attributes.debit_party.name

string

Nome de quem realizou o pagamento.

attributes.pactual_id

string

Identificador interno do pagamento.

attributes.autorizathion_code

string

Código de autorização do Pix.

attributes.movement_id

string

Identificador do movimento. Usado para devoluções.

attributes.value

string

Valor efetivamente pago.

attributes.debt_id

string

Identificador da dívida relacionada ao pagamento.

attributes.created_at

string

Data e hora da criação do pagamento.

attributes.description

string

Descrição do Pix.

attributes.receiver_key

string

Chave Pix de recebimento.

attributes.tx_id

string

Identificador da transação Pix.

Quando houver devoluções de Pix, o campo refunds estará presente dentro de payment_inbounds.

{
    "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",
    "payment_inbounds": [
        {
            "data": {
                "id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                "type": "payment_inbound",
                "attributes": {
                    "debit_party": {
                        "account": "XXXXXXXXXXX",
                        "bank": "XXXXXXXX",
                        "branch": "XXX",
                        "personType": "XXXXXXXX",
                        "taxId": "XXXXXXXXXXXX",
                        "accountType": "XXXXXX",
                        "name": "Nome de quem pagou o Pix"
                    },
                    "pactual_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                    "autorizathion_code": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    "movement_id": "XXXXXXXX",
                    "value": "00.00",
                    "debt_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                    "created_at": "YYYY-MM-DDTHH:MM:SS.SSSZ",
                    "description": "Descrição do Pix",
                    "receiver_key": null,
                    "tx_id": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    "refunds": [
                        {
                            "data": {
                                "id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                                "type": "refund",
                                "attributes": {
                                    "value": "00.00",
                                    "client_transaction_refund_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                                    "requester_uuid": "XXXXXXX",
                                    "status": "confirmed",
                                    "return_identification_transiting_id": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
                                    "reason": "Mensagem de Devolução",
                                    "requested_at": "YYYY-MM-DDTHH:MM:SS.SSSZ",
                                    "liquidated_at": null,
                                    "payment_inbound_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                                    "original_e2e_id": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
                                    "original_pactual_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX",
                                    "pactual_id": "XXXXXXXXXXXXX-XXXXXX-XXXXXX-XXXXX-XXXXXXXXXXXX"
                                [...]
                              }
                    }
                ]       
        }
    ]
}

Campo

Tipo

Descrição

data.id

string

Identificador da devolução.

data.type

string

Tipo do objeto: refund.

attributes.value

string

Valor devolvido.

attributes.client_transaction_refund_id

string

Identificador do cliente para a devolução.

attributes.requester_uuid

string

Identificador de quem solicitou a devolução.

attributes.status

string

Status da devolução: confirmed, pending etc.

attributes.return_identification_transiting_id

string

Identificação de retorno do Pix.

attributes.reason

string

Motivo da devolução.

attributes.requested_at

string

Data e hora de solicitação da devolução.

attributes.liquidated_at

string

Data e hora da liquidação da devolução, se houver.

attributes.payment_inbound_id

string

Referência ao pagamento original.

attributes.original_e2e_id

string

Identificador original do Pix (End to End ID).

attributes.original_pactual_id

string

Identificador interno original do pagamento.

attributes.pactual_id

string

Identificador da devolução no sistema.

Exemplos de erros

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

{
    "message": "Nenhum pix encontrado para o identificador informado."
}

Curl da requisição

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

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.blu.com.br/b2b/pix/{transaction-token}',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXX'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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."
}

{
    "success": false,
    "message": "A validação falhou: Valor deve ser maior que 0",
    "statusCode": 422
}

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"
}'

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.blu.com.br/b2b/pix/refund',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "movement_id": "XXXXXXXXXXXXXXXXXXXXXX",
    "reason": "Motivo para Devolução",
    "value": "00.00"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

1KB

Pix.postman_collection.zip

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

version=1

Não

Content-Type

application/json

Não

Authorization

xxxxxxxxxxxxx

Token de operação.

Sim

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"
}

{
	"message": "Cliente não possuí callback cadastrado"
}

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 1 month ago

Was this helpful?