API Pix

A API de Pix permite criar links de pagamento, consultar o status de um Pix e realizar devoluções de valores. Ela pode ser usada tanto por fornecedores quanto por varejistas.

Como começar a usar

Pra ter acesso, é só falar com a pessoa que te atende aqui na Blu — pode ser seu Executivo de Contas ou o time de suporte. Eles vão acionar o time responsável, que cuida de liberar o uso da API e te enviar o token de autenticação.

Requisitos

• Ter uma chave Pix registrada na sua conta digital Blu. (Saiba como criar uma)

• Ter o token de autenticação para uso das APIs.

Orientações

• Preencha todos os campos obrigatórios ao usar as APIs.

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

Criar Pix

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

Esta API é responsável por retornar o código para que sejam consultados os dados do Pix.

Objetivo

Possibilitar aos nossos fornecedores e varejistas possam criar cobranças Pix.

Headers

Name	Type	Description
Authorization*	string	Token de operação.

Request Body

Name	Type	Description
expires_at*	string	Obrigatório. Data em que o Pix irá expirar no formato YYYY-MM-DD.
description	string	Descrição do Pix que aparecerá para o pagador. Máximo 25 caracteres.
value*	string	Obrigatório. Valor a ser pago no Pix.
description_internal	string	Descrição interna para o portal Blu. Máximo 12 caracteres.

200: OK Pix criado

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

401: Unauthorized Token inválido

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

422: Unprocessable Entity expires_at no passado ou vazio

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

422: Unprocessable Entity value igual a zero, negativo ou vazio

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

O retorno da criação do Pix é apenas um uuid que deve ser usado na API Consultar Pix para então obter os dados do Pix e poder acompanha-lo.

O retorno da criação do Pix é um arquivo JSON, com um único campo:

Campos da Transação	Data Type	Descrição
transaction_token	string	uuid para ser utilizado na API Consultar Pix

Consultar Pix

O transaction_token retornado pela API de Criação do Pix será utilizado como parâmetro na url da requisição.

Consultar Pix

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

Esta API é responsável por consultar os dados do Pix criado via API e saber seu status.

Objetivo

Possibilitar aos nossos fornecedores e varejistas possam consultar os dados e status de um um Pix criado via API por meio de seu id.

Fique atento! para visualizar os exemplos dos responses abaixo, clique no botão > para abrir o campo de leitura.

Query Parameters

Name	Type	Description
transaction_token*	string	uuid do Pix

Headers

Name	Type	Description
Autorization*	string	Token de operação.

200: OK Consulta realizada - Pix Criado

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

401: Unauthorized Token inválido

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

404: Not Found uuid inválido

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

200: OK Consulta realizada - Pago

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

200: OK Consulta realizada - Devoluções

{
    "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"
                                [...]
                              }
                    }
                ]       
        }
    ]
}

Para realizar uma Devolução de Pix deve ser utilizado o campo movement_id que aparece após o pagamento do Pix.

O retorno da consulta do Pix é um arquivo JSON, contendo as informações do Pix e seu status. Abaixo vemos todos os campos que serão retornados:

Campos da Transação	Data Type	Descrição
id	string	id do Pix perante ao banco.
tx_id	string	id do Pix.
transaction_token	string	Token do Pix na Blu, utilizado para localizar o Pix.
status	string	Status do Pix.
expires_at	string	Data de expiração do Pix no formato AAAA-MM-DD.
description	string	Descrição externa do Pix inserida na criação.
description_internal	string	Descrição interna do Pix inserida na criação.
value	string	Valor do Pix.
created_at	string	Data de criação do Pix no formato AAAA-MM-DD.
emv	string	Link a ser utilizado para Pix Copia e Cola.
qr_code_base64	string	Dados para montar o qr code do Pix.

Devolução de Pix

Após o pagamento de um Pix é possível devolvê-lo de forma total ou parcial e para isso a API de Devolução de Pix deve ser utilizada. Para realizar a

Devolução de Pix

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

Esta API possibilita devolver total ou parcialmente um Pix criado via API.

Objetivo

Possibilitar aos nossos fornecedores e varejistas possam devolver valores cobrados via Pix.

Fique atento! para visualizar os exemplos dos responses abaixo, clique no botão > para abrir o campo de leitura.

Headers

Name	Type	Description
Authorization*	string	Token de operação.

Request Body

Name	Type	Description
movement_id*	string	Obrigatório. Id do pagamento do Pix.
reason	string	Descrição do motivo da devolução.
value*	string	Obrigatório. Valor da devolução.

200: OK Valores devolvidos

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

401: Unauthorized Token inválido

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

422: Unprocessable Entity value igual a zero, negativo ou vazio

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

A API Devolução de Pix não critica se o valor devolvido é ou não maior que o valor da transação. Contudo, a operação só é executada e aparece na sessão refunds da Consulta Pix se o valor ou igual ou menor que o valor do Pix pago.

Os cURLs para executar as APIs do Link de Pagamento são exibidos abaixo, bem como a collection com todas as APIs para ser importada no Postman está em anexo na página.

Criar Pix

cURL

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

NodeJs

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

cURL

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

NodeJs

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);
});

Devolver Pix

cURL

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

NodeJs

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

archive