Transferência via Pix

As transações de pagamentos/transferências de valores via Pix, ou Pix cash-out, podem ocorrer das seguintes maneiras:

Manual;
Por chave PIX;
Por QR Code (estático ou dinâmico).

🚧
Importante
O Pix cash-out possui limite de valor definido durante a operação, de acordo com a necessidade do parceiro. Esse limite pode ser alterado a qualquer momento. Em caso de dúvidas, consulte o Farmer ou o Partner Lead.

📘
Nota
Em caso de pessoa física, não existe limite noturno para transações entre mesma titularidade.

Requisição

Requisição HTTP

 POST 'https://api-mtls.sandbox.bankly.com.br/pix/cash-out'

--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: {{GUID}}' \
--header 'Authorization: {{token}}  
--data-raw '{
    "amount": 23.00, 
    "description": "Description", 
    "initializationType": "Manual" ,  
    "sender": { 
        "documentNumber": "47742663023", 
        "name": "Nísia Floresta",
        "account": { 
            "branch": "0001", 
            "number": "15164"
        }, 
        "bank": { 
        }
    }, 
    "recipient": { 
        "documentNumber": "09992220074", 
        "name": "Maria Quitéria de Jesus" ,
        "account": { 
          "branch": "0001", 
          "number": "540108", 
          "type": "PAYMENT" 
        }, 
        "bank": { 
           "ispb": "13140088"
        }
    }
}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`pix.cashout.create`	Concede acesso para iniciar um pagamento via Pix.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`x-correlation-id`	Se desejar, informe um GUID v4, sendo um novo cada requisição.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

Tanto para operações manuais, quanto por chave pix ou por QR Code, deve-se enviar os seguintes campos comuns em formato JSON:

Nome	Tipo	Descrição
`sender`	`object`	Obrigatório. Objeto que contém os dados do pagador.
`sender.account`	`object`	Obrigatório. Objeto que contém informações sobre a conta do pagador.
`sender.account.branch`	`string`	Obrigatório. Número da agência.
`sender.account.number`	`string`	Obrigatório. Número da conta.
`sender.account.type`	`string`	Obrigatório. Tipo de conta, o qual pode ser "CHECKING" para conta corrente, "SALARY" para conta salário, "SAVINGS" para conta poupança e "PAYMENT" para conta de pagamento.
`sender.documentNumber`	`string`	Obrigatório. Número do documento do pagador.
`sender.name`	`string`	Obrigatório. Nome do pagador.
`amount`	`number`	Obrigatório. Valor a ser enviado.
`initializationType`	`string`	Obrigatório. Modo pelo qual se dará a transação: "key", no caso de chave de endereçamento Pix, "staticQrCode" ou "dynamicQrCode", no caso de QR Codes, e "manual".
`description`	`string`	Campo que pode ser utilizado pelo usuário para enviar mensagens ao destinatário da transferência com informações sobre a transação. O texto pode conter no máximo 140 caracteres e não aceita nenhum caractere especial (exceto hífen).

🚧
Importante
Para recuperar as informações da instituição financeira de destino (ISPB e code), basta consultar nosso serviço de listagem de participantes do Pix.

Veja a seguir as especificidades de cada modalidade de Pix cash-out.

Manual

Para realizar uma transferência via Pix manual, além dos campos comuns, envie os seguintes campos no body da requisição:

Nome	Tipo	Descrição	Especificação
`recipient`	`object`	Obrigatório. Objeto que contém os dados do recebedor do pagamento.	—
`recipient.account`	`object`	Obrigatório. Objeto que contém informações sobre a conta do recebedor.	—
`recipient.account.branch`	`string`	Obrigatório. Número da agência.	—
`recipient.account.number`	`string`	Obrigatório. Número da conta.	—
`recipient.account.type`	`string`	Obrigatório. Tipo de conta, o qual pode ser "CHECKING" para conta corrente, "SALARY" para conta salário, "SAVINGS" para conta poupança e "PAYMENT" para conta de pagamento.	—
`recipient.bank`	`object`	Obrigatório. Objeto com os dados do banco recebedor.	—
`recipient.bank.ispb`	`string`	Obrigatório. ISPB da instituição recebedora do pagamento	—
`recipient.documentNumber`	`string`	Obrigatório. Número do documento do recebedor.	—
`recipient.name`	`string`	Obrigatório. Nome do recebedor.	Este campo não aceita caracteres especiais ou com acentos, como por exemplo ã, é, ó, ç.

📘
Nota
No tipo manual, não é necessário informar o endToEndId.

Por chave Pix

Os pagamentos ou transferências via chave Pix podem ser feitos para todos os tipos de chaves (CPF, CNPJ, telefone, e-mail e chave aleatória - EVP).

Antes de realizar uma transação cash-out por chave Pix, o parceiro deve fazer a consulta da chave junto ao DICT para verificar a sua validade.

Recordamos que o retorno da consulta de chaves trará o endToEndId, que será utilizado no momento da transação de cash-out. Esse identificador deve ser usado no período máximo de 15 minutos.

Para realizar uma transferência por chave Pix, além dos campos comuns, envie os seguintes campos no body da requisição:

Nome	Tipo	Descrição
`endToEndId`	`string`	Obrigatório. Valor de `endToEndId` retornado na consulta de chave.

Por QR Code (estático e dinâmico)

Para realizar uma transação cash-out por QR Code estático ou dinâmico, é preciso recuperar o endToEndId retornado na decodificação do QR Code.

Para realizar uma transferência/pagamento por QR Code, além dos campos comuns, envie os seguintes campos no body da requisição:

Nome	Tipo	Descrição
`endToEndId`	`string`	Obrigatório. Valor de `endToEndId` retornado na decodificação do QR Code.
`conciliationId`	`string`	Obrigatório. Campo de preenchimento obrigatório no caso de pagamento de QR Codes dinâmicos. Nele, deve ser informado o valor do `conciliationId` retornado na leitura do QR Code.
`changeAmount`	`string`	Campo obrigatório em caso de Pix Troco. Informe o valor do troco (quantia que se deseja obter em espécie).

--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: {{correlationId}}' \
--header 'x-bkly-pix-user-id: {{clientDocument}}'\
--header 'Authorization: {{token}}' \  
--data-raw '{
    "amount": 23.00, 
    "description": "Description", 
    "initializationType": "Manual" ,  
    "sender": { 
        "documentNumber": "47742663023", 
        "name": "Nísia Floresta",
        "account": { 
            "branch": "0001", 
            "number": "15164"
        }, 
        "bank": { 
        }
    }, 
    "recipient": { 
        "documentNumber": "09992220074", 
        "name": "Maria Quitéria de Jesus" ,
        "account": { 
          "branch": "0001", 
          "number": "540108", 
          "type": "PAYMENT" 
        }, 
        "bank": { 
           "ispb": "13140088"
        }
    }
}'

--location --request POST 'https://api.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: {{correlationId}}' \ 
--header 'x-bkly-pix-user-id: {{clientDocument}}'\
--header 'Authorization: {{token}}' \ 
--data-raw '{ 
    "sender": { 
        "account": { 
            "branch": "0001", 
            "number": "111929", 
            "type": "PAYMENT" 
        }, 
        "bank": { 
        }, 
        "documentNumber": "12345678902", 
        "name": "Peter Parker" 
        }, 
    "amount": 1, 
    "description": "Pix cashout via Key", 
    "initializationType": "Key", 
    "endToEndId": "E1314008820211019140822078594881" 
    }'

--location --request POST 'https://api.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: {{correlationId}}' \ 
--header 'x-bkly-pix-user-id: {{clientDocument}}'\
--header 'Authorization: {{token}}' \
--data-raw '{ 
    "sender": { 
        "account": { 
            "branch": "0001", 
            "number": "15164", 
        }, 
        "bank": { 
        }, 
        "documentNumber": "47742663023", 
        "name": "Nísia Floresta", 
    }, 
    "amount": 1, 
    "description": "payment", 
    "initializationType": "StaticQrCode", 
    "endToEndId": "E1314008820210628213443832702790" 
}'

--location --request POST 'https://api.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: {{correlationId}}' \ 
--header 'x-bkly-pix-user-id: {{clientDocument}}'\
--header 'Authorization: {{token}}' \ 
--data-raw'{ 
    "amount": 187.55,   
    "changeAmount": 593.11,  
    "description": "change", 
    "sender":{ 
        "name": "Nísia Floresta", 
        "documentNumber": "47742663023", 
        "account":{ 
            "branch": "0001",
            "number": "15164", 
            "type": "CHECKING" 
    	  } 
   }, 
   "initializationType": "staticQrCode", 
   "endToEndId": "E131400882022131132132515238664"
}'

Resposta (Response)

O status code 202 indicará sucesso na transação.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`amount`	`number`	Valor enviado.
`withdrawalAmount`	`number`	Valor do saque. Campo retornado apenas em caso pagamento por QR Code para Pix Saque.
`changeAmount`	`number`	Valor do troco. Campo retornado apenas em caso pagamento por QR Code para Pix Troco.
`description`	`string`	Campo que pode ser utilizado pelo usuário para enviar mensagens ao destinatário da transferência com informações sobre a transação. O texto pode conter no máximo 140 caracteres e não aceita nenhum caractere especial (exceto hífen).
`sender`	`object`	Objeto que contém os dados do pagador.
`sender.documentType`	`string`	Tipo de documento do pagador (CPF ou CNPJ).
`sender.documentNumber`	`string`	Número do documento do recebedor.
`senderName`	`string`	Nome do recebedor. Esse campo retornará o nome do documento de cadastro, e não o nome social.
`sender.account`	`object`	Objeto que contém informações sobre a conta do pagador.
`sender.account.branch`	`string`	Número da agência.
`sender.account.number`	`string`	Número da conta.
`sender.account.type`	`string`	Tipo de conta, o qual pode ser `CHECKING` para conta corrente, `SALARY` para conta salário, `SAVINGS` para conta poupança e `PAYMENT` para conta de pagamento.
`sender.bank`	`object`	Objeto com os dados do banco do pagador.
`sender.bank.ispb`	`string`	ISPB do banco.
`sender.bank.compe`	`string`	Código do banco.
`sender.bank.name`	`string`	Nome do banco.
`recipient`	`object`	Objeto que contém os dados do recebedor.
`recipient.documentType`	`string`	Tipo de documento do recebedor (CPF ou CNPJ).
`recipient.documentNumber`	`string`	Número do documento do recebedor.
`recipient.name`	`string`	Nome do recebedor. Esse campo retornará o nome do documento de cadastro, e não o nome social.
`recipient.account`	`object`	Objeto que contém informações sobre a conta do recebedor.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.type`	`string`	Tipo de conta, o qual pode ser `CHECKING` para conta corrente, `SALARY` para conta salário, `SAVINGS` para conta poupança e `PAYMENT` para conta de pagamento.
`recipient.bank`	`object`	Objeto com os dados do banco recebedor.
`recipient.bank.ispb`	`string`	ISPB da instituição recebedora do pagamento
`recipient.bank.compe`	`string`	Código do banco.
`recipient.bank.name`	`string`	Nome do banco.
`authenticationCode`	`string`	Código de autenticação da transação. O valor desse campo é utilizado para verificar os status da transação no endpoint de consulta de status.

📘
Nota
Para obter o valor exato movimentado em transações de Pix Troco, deve-se somar os valores retornados nos campos amount e changeAmount.

{
    "amount": 1,
    "description": "DESCRIÇÃO",
    "sender": {
       "documentType": "CPF",
       "documentNumber": "47742663023",
       "name": "Nísia Floresta",
       "account": {
          "branch": "0001",
          "number": "15164",
          "type": "CHECKING"
       },
       "bank": {
          "ispb": "13140088",
          "compe": "332",
          "name": "Acesso Soluções de Pagamento S.A."
       },
    },
    "recipient": {
       "documentType": "CPF",
       "documentNumber": "09992220074",
       "name": "Maria Quitéria de Jesus",
       "account": {
          "branch": "0001",
          "number": "540108",
          "type": "CHECKING"
       },
       "bank": {
          "ispb": "13140088",
          "compe": "332",
          "name": "Acesso Soluções De Pagamento S.A."
       },
    },
    "authenticationCode": "fc6470ac-6d1b-4c84-8c61-00de2b8888d4"
 }

{
   "amount": 1,
   "description": "DESCRIÇÃO",
   "sender": {
      "documentType": "CPF",
      "documentNumber": "47742663023",
      "name": "Nísia Floresta",
      "account": {
         "branch": "0001",
         "number": "187470",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamento S.A."
      },
   },
   "recipient": {
      "documentType": "CPF",
      "documentNumber": "09992220074",
      "name": "Maria Quitéria de Jesus",
      "account": {
         "branch": "0551",
         "number": "1085867",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "00000000",
         "compe": "001",
         "name": "Banco Do Brasil S.A."
      },
   },
   "authenticationCode": "dd648881-f837-46ca-a9ee-79cb7e5c7ef3"
}

{
   "amount": 1,
   "description": "DESCRIÇÃO",
   "sender": {
      "documentType": "CPF",
      "documentNumber": "47742663023",
      "name": "Nísia Floresta",
      "account": {
         "branch": "0001",
         "number": "187470",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamento S.A."
      },
   },
   "recipient": {
      "documentType": "CNPJ",
      "documentNumber": "34183937000161",
      "name": "Editora Nísia Floresta",
      "account": {
         "branch": "0001",
         "number": "219568",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções De Pagamento S.A."
      },
   },
   "authenticationCode": "65411a0d-06af-4c4d-b61e-e0f0cb91c9ff"
}

{
   "amount": 187.55,
   "withdrawalAmount": 0,
   "changeAmount": 593.11,
   "description": "change",
   "sender": {
      "documentType": "CPF",
      "documentNumber": "47742663023",
      "name": "Nísia Floresta",
      "account": {
         "branch": "0001",
         "number": "15164",
         "type": "PAYMENT"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamentos S.A"
      },
   },
   "recipient": {
      "documentType": "CNPJ",
      "documentNumber": "34183937000161",
      "name": "Editora Nísia Floresta",
      "account": {
         "branch": "0001",
         "number": "422316",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088"
      },
   },
   "authenticationCode": "a020a1a-7133-4b49-a62d-e1daf38da54d"
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Reprovação no processo de transferência

Embora haja sucesso na requisição, é possível que o processo de transferência via Pix não seja completado.

Nesses casos, o valor retornará para a conta pagadora e o parceiro receberá o evento PIX_CASHOUT_WAS_CANCELED e/ou o evento PIX_CASHOUT_WAS_UNDONE, que indicarão no campo refusalReason a razão pela qual a transferência não pôde ocorrer.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Descrição
400	—	—	O valor do `changeAmount` precisa ser o mesmo do informado pelo QR Code.
400	SENDER_ACCOUNT_STATUS_NOT_ALLOW_CASH_OUT	Sender account status does not allow cash out.	O status da conta pagadora não permite o cash-out.
400	RECIPIENT_ACCOUNT_STATUS_NOT_ALLOW_CASH_IN	Recipient account status does not allow cash in.	O status da conta recebedora não permite cash-in.
400	INVALID_RECIPIENT_ACCOUNT	Sender and recipient account must not be the same.	A conta do pagador e do recebedor não podem ser a mesma.
400	SENDER_ACCOUNT_NOT_FOUND	Sender account not found for fund transfer.	Conta do pagador não encontrada para a realização da transferência.
400	RECIPIENT_ACCOUNT_NOT_FOUND	Recipient account not found for internal transfer.	Conta do recebedor não encontrada para transferência interna.
400	CASHOUT_LIMIT_NOT_ENOUGH	Sender does not have sufficient cash out limit.	A transação excede o limite de valor da transferência.
400	TIMEOUT	Transaction exceeded request limit timeout.	A requisição excedeu o tempo máximo para completar essa transação.
400	INVALID_BANK_BRANCH	Invalid bank branch.	Agência bancária inválida.
400	INVALID_BANK_ACCOUNT	Invalid bank account.	Conta bancária inválida.
400	RECIPIENT_ACCOUNT_DOES_NOT_MATCH_THE_DOCUMENT	Recipient account does not match with the document informed.	O documento informado não pertence à conta do recebedor.
400	SENDER_ACCOUNT_DOES_NOT_MATCH_THE_DOCUMENT	Sender account does not match with the document informed.	O documento informado não pertence à conta do pagador.
400	INSUFFICIENT_BALANCE	Customer does not have sufficient balance.	O cliente não possui saldo suficiente para a transação.
400	TRANSFER_WAS_REPROVED	Pix transfer was reproved.	A transferência não foi aprovada.
400	TRANSFER_AMOUNT_NOT_RESERVED	Pix transfer amount not reserved.	Erro ao reservar dinheiro para transferência.
400	TRANSFER_ORDER_NOT_PROCESSED	Pix transfer order not processed.	A transferência não foi processada.
400	INTERNAL_TRANSFER_NOT_COMPLETED	Pix transfer order not processed	A transferência interna de Pix não foi completada.
400	SCHEDULE_NOT_ALLOWED	—	Agendamento não permitido.
400	INVALID_END_TO_END_ID	—	`endToEndId` inválido.
400	END_2_END_ID_ALREADY_USED	The EndToEnd informed already been used by another transaction.	O `endToEndId` informado já está sendo utilizado em outra transação.
400	INVALID_PARAMETERS	The QR Code is expired. Payment after its expiration date is not allowed.	Não é permitido realizar pagamentos após a expiração do QR Code.
404	ACCOUNT_NOT_FOUND	Account not found for fund transfer.	Conta não encontrada.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Evento	Descrição
`PIX_CASHOUT_WAS_COMPLETED`	Pagamento via Pix finalizado.
`PIX_CASHOUT_WAS_CANCELED`	A reserva de valor para a transação (hold) não foi concluída com sucesso, resultando no cancelamento da transação.
`PIX_CASHOUT_WAS_UNDONE`	Embora a reserva de valor para a transação (hold) tenha sido realizada com sucesso (o status do saldo foi modificado de 'available' para 'in-process'), a etapa de verificação antifraude resultou em reprovação, levando à reversão do status do saldo de 'in_process' para 'available' novamente.

📘
Nota
Se a reserva de valor para a transação (hold) for realizada com sucesso (o saldo foi atualizado para o status in-process), e a etapa de verificação antifraude for aprovada, mas ocorrer uma falha durante o processo, a transação será cancelada e o saldo retornará ao status "available" novamente. Neste cenário, o parceiro receberá dois eventos: PIX_CASHOUT_WAS_CANCELED e PIX_CASHOUT_WAS_UNDONE.

Transferência via Pix

🚧
Importante

📘
Nota

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧
Importante

Manual

📘
Nota

Por chave Pix

Por QR Code (estático e dinâmico)

Resposta (Response)

📘
Nota

👍
Dica

Reprovação no processo de transferência

Erros

Eventos

📘
Nota

🚧Importante

📘Nota

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧Importante

Manual

📘Nota

Por chave Pix

Por QR Code (estático e dinâmico)

Resposta (Response)

📘Nota

👍Dica

Reprovação no processo de transferência

Erros

Eventos

📘Nota

🚧
Importante

📘
Nota

🚧
Importante

📘
Nota

📘
Nota

👍
Dica

📘
Nota