Pix Troco

O Pix Troco permite ao cliente sacar dinheiro em espécie em estabelecimentos comerciais habilitados. No entanto, esse processo só pode ocorrer durante alguma compra realizada pelo cliente no local em que deseja fazer o saque.

Por exemplo, o cliente fez uma compra com valor de R$50,00 e deseja sacar R$30,00 em espécie. Nesse caso, o estabelecimento deverá emitir um QR Code com o valor de R$80,00.

Então, o cliente deverá fazer a decodificação do QR Code e realizar o pagamento de R$80,00 via Pix ao estabelecimento. Ao confirmar o recebimento, o estabelecimento entregará ao cliente os R$30,00 em espécie.

Etapas

Decodificação do QR Code

A API de decodificação do Bankly está preparada para ler QR Codes estáticos e QR Codes dinâmicos, gerados por qualquer instituição financeira.

Endpoint

Para consumo do endpoint de decodificação de QR Code, preencha os seguintes campos obrigatórios:

x-bkly-pix-user-id: no header da requisição, informe o número do documento do cliente que está solicitando a leitura do QR Code. Insira apenas números, sem formatação;
x-correlation-id: um GUID v4, gerado randomicamente. A cada requisição, deve-se gerar um novo GUID v4;
encodedValue: conteúdo do QR Code em base64.

-location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/qrcodes/decode' \   
--header 'Accept: application/json' \   
--header 'Content-Type: application/json' \   
--header 'api-version: 1.0' \   
--header 'x-bkly-pix-user-id: {{clientDocument}}' \   
--header 'x-correlation-id: {{correlationId}}' \ 
--header 'Authorization: Bearer {{accessToken}}' \   
--data-raw '{   
    "encodedValue": "MDAwMjAxMjY5MTAwMTRici5nb3YuYmNiLnBpeDI1Njlxci1oLnNhbmRib3gucGl4LmJjYi5nb3YuYnIvcmVzdC9hcGkvYzZmYzgxNzc4MTMyNGE3MmIyMGRkNGFjNjhhZDFhZTk1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTAzUGl4NjAwOEJSQVNJTElBNjIwNzA1MDMqKio2MzA0NjlCMg=="   
    }'

Retorno

A seguir, destacamos alguns campos retornados na decodificação do QR Code de Pix Troco:

changeAmountType: indica a possibilidade de alteração do valor do QR Code. Se esse campo retornar ALLOWED, será permitido alterar o valor. Caso o retorno seja NOT_ALLOWED, não será permitido realizar a alteração do valor trazido pelo QR Code;
agentType: informa o tipo de estabelecimento comercial. Ele pode retornar:
- STORE;
- OTHER_BUSINESSES.
qrCodePurpose: indica a razão da emissão do QR Code. Nesse contexto, será “CHANGE” (troco);
totalValue: informará o valor total da compra ou transferência;
changeValue: valor do troco em espécie.

{
   "endToEndId": "E1314008820211215210930963375974",
   "conciliationId": "c6fc817781324a72b20dd4ac68ad1ae9",
   "addressingKey": {
      "type": "EVP",
      "value": "4004901d-bd85-4769-8e52-cb4c42c506dc"
   },
   "qrCodeType": "DYNAMIC",
   "payer": {
      "type": "CUSTOMER",
      "name": "Peter Parker",
      "document": {
         "value": "12345678900",
         "type": "CPF"
      }
   },
   "holder": {
      "type": "BUSINESS",
      "name": "Test",
      "document": {
         "value": "00011111000100",
         "type": "CNPJ"
      }
   },
   "bank": {
      "ispb": "99999008"
   },
   "payment": {
      "baseValue": 766.67,
      "interestValue": 0,
      "penaltyValue": 0,
      "discountValue": 0,
      "totalValue": 766.67,
      "dueDate": "0001-01-01T00:00:00",
      "changeValue": 426.4,
      "withdrawalValue": 0
   },
   "location": {
      "city": "BRASILIA"
   },
   "additionalData": [
      {
         "name": "Delivery",
         "value": "Residential"
      }
   ],
   "changeAmountDetail": {
      "changeAmountType": "NOT_ALLOWED",
      "agentType": " STORE"
   },
   "qrCodePurpose": "CHANGE_AMOUNT"
}

Erros

Status code	Código	Descrição
400	INVALID_QRCODE_PAYLOAD_CONTENT_TO_DECODE	O payload do QR Code apresenta conteúdo inválido. Certifique-se de que o PSP do recebedor está gerando um payload de QR Code válido.
400	INVALID_USER_ID	Verifique se o cabeçalho `x-bkly-pix-user-id` apresenta um CPF ou CNPJ válido.
400	REQUEST_TIMEOUT	A transação excedeu o tempo limite.
404	ENTRY_NOT_FOUND	Informação não encontrada.

Pagamento do QR Code

Por meio de nossa API, é possível realizar pagamentos de QR Codes emitidos pelo Bankly ou por outras instituições.

Endpoint

Para o uso do endpoint de Pix cash-out para pagamento do QR Code, é obrigatório o preenchimento dos seguintes campos:

x-correlation-id: um GUID v4, gerado randomicamente. A cada requisição, deve-se gerar um novo GUID v4;
amount: informe o valor total a ser pago (valor da compra somado ao valor que se deseja obter em espécie);
changeAmount: valor do troco (quantia que se deseja obter em espécie);
sender:
- name: nome de quem envia o pagamento;
- documentNumber: número do documento (CPF/CNPJ) de quem envia o pagamento;
- account:
  - branch: número da agência pagadora;
  - number: número da conta pagadora;
  - type: tipo de conta.
endToEndId: identificador único gerado na decodificação do QR Code;
initializationType: informe "staticQrCode", para QR Code estático, e "dynamicQrCode", para QR Code dinâmico;
receiverReconciliationId: deve ser preenchido com o valor do conciliationId, quando esse campo retornar na leitura do QR Code.

Opcionalmente, informe a descrição do pagamento no campo description.

--location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/cash-out' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'api-version: 1.0' \ 
--header 'x-correlation-id: d4b8645c-7937-4b6c-9812-f7e7dc47d242' \ 
--header 'Authorization: Bearer' \ 
--data-raw
'{ 
    "amount": 187.55,   
    "changeAmount": 593.11,  
    "description": "change", 
    "sender":
    { 
        "name": "Peter Parker", 
        "documentNumber": "12345678900", 
        "account":
        { 
            "branch": "0001",
            "number": "123456", 
            "type": "CHECKING" 
    	 } 
   }, 
   "initializationType": "staticQrCode", 
   "endToEndId": "E1314008820220131132132515238664",
   "description": "change"  
}'

Retorno

Para obter o valor exato movimentado na transação de Pix Troco, deve-se somar os valores retornados nos campos amount e changeAmount.

{
   "amount": 187.55,
   "withdrawalAmount": 0,
   "changeAmount": 593.11,
   "description": "change",
   "sender": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "208167",
         "type": "PAYMENT"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamentos S.A"
      },
      "documentNumber": "12345678901",
      "name": "Peter Parker"
   },
   "recipient": {
      "documentType": "CNPJ",
      "account": {
         "branch": "0001",
         "number": "12345678",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "99999008"
      },
      "documentNumber": "11111111000191",
      "name": "Test"
   },
   "authenticationCode": "a020a18a-7133-4b49-a62d-e1daf38da54d"
}

Erros

Status code	Código	Descrição
400	---	Não é permitido incluir números ou caracteres especiais para o campo `City`.
400	---	O valor do `changeAmount` precisa ser o mesmo do informado pelo QR Code.
404	---	Formato de código postal inválido no Brasil. Considere não utilizar máscara para o CEP.

🚧
Importante
Para segurança dos usuários do Pix Saque e Pix Troco, o Bacen estipula como limite o valor de R$500,00 para as transações diurnas, e R$100,00 para transações noturnas (das 20h às 6h).

Etapas

Decodificação do QR Code

Endpoint

Retorno

Erros

Pagamento do QR Code

Endpoint

Retorno

Erros

🚧Importante

🚧
Importante