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.

Etapas

Endpoint

Embora as modalidades de Pix cash-out sejam diferentes, elas possuem campos comuns de preenchimento obrigatório na requisição:

x-correlation-id: informe um GUID v4, gerado randomicamente. A cada requisição, deve-se gerar um novo GUID v4;
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;
sender: dados de quem enviará o pagamento;
- account:
  - branch: informe o número da agência;
  - number: número da conta;
  - type: informe o tipo de conta. "CHECKING" para conta-corrente, "SALARY" para conta-salário, "SAVINGS" para conta-poupança e "PAYMENT" para conta de pagamento;
- documentNumber: número do documento (CPF/CNPJ) do proprietário da conta;
- name: nome do proprietário da conta;
amount: informe o valor a ser enviado;
initializationType: informe o modo pelo qual se dará a transação: "key", no caso de chave de endereçamento, "staticQrCode" ou "dynamicQrCode", no caso de QR Codes, e "manual".

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

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

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

Manual

O Pix cash-out manual exige que o cliente final (que realizará o pagamento) informe a agência e a conta do recebedor antes de realizar a transação.

Para consumo do endpoint de Pix cash-out na modalidade manual, preencha todos os campos obrigatórios comuns e informe:

recipient: dados de quem receberá o pagamento;
- account:
  - branch: informe o número da agência do recebedor;
  - number: número da conta;
  - type: informe o tipo de conta. "CHECKING" para conta-corrente, "SALARY" para conta-salário, "SAVINGS" para conta-poupança e "PAYMENT" para conta de pagamento;
- bank:
  - ispb: informe o ISPB da instituição recebedora do pagamento;
- documentNumber: documento (CPF/CNPJ) do proprietário da conta recebedora;
- name: nome do proprietário da conta;
inicializationType: deve ser preenchido com a palavra "Manual".

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

Por chave PIX

Os pagamentos ou transferências via chave podem ser feitos para todos os tipos de chaves Pix (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 uma hora.

Para consumo deste endpoint para cash-out por chave Pix, além de preencher todos os campos obrigatórios comuns, é preciso informar:

initializationType: preencha este campo com a palavra "Key";
endToEndId: informe o valor de endToEndId retornado na consulta de chave.

Opcionalmente, informe o campo addressKey com a chave de endereçamento Pix do recebedor.

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 consumo deste endpoint para cash-out por QR Code, além de preencher todos os campos obrigatórios comuns, informe:

initializationType: preencha este campo com a palavra "staticQrCode" ou "dynamicQrCode".
endToEndId: informe o valor de endToEndId retornado na decodificação do QR Code.
conciliationId: 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.

A seguir, exemplos de requisição para cash-out manual, via chave Pix e via QR Code.

--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": "12345678902", 
        "name": "Peter Parker",
        "account": { 
            "branch": "0001", 
            "number": "111470", 
        }, 
        "bank": { 
        }
    }, 
    "recipient": { 
        "documentNumber": "12345678900", 
        "name": "Carol Denvers" ,
        "account": { 
          "branch": "0001", 
          "number": "111929", 
          "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": "1234", 
        }, 
        "bank": { 
        }, 
        "documentNumber": "12345678902", 
        "name": "Peter Parker" 
    }, 
    "amount": 1, 
    "description": "payment", 
    "initializationType": "StaticQrCode", 
    "endToEndId": "E1314008820210628213443832702790" 
}'

Retorno

O sucesso retornará o status code 202.

O retorno de todos os tipos de requisição trará o campo authenticationCode. Seu valor é utilizado para verificar os status da transação no endpoint de consulta de status.

A seguir, exemplos de retorno de cash-out manual, via chave Pix e via QR Code.

{
   "amount": 1,
   "description": "DESCRIÇÃO",
   "sender": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "187470",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamento S.A."
      },
      "documentNumber": "12345678902",
      "name": "Peter Parker"
   },
   "recipient": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "186929",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções De Pagamento S.A."
      },
      "documentNumber": "12345678900",
      "name": "Carol Denvers"
   },
   "authenticationCode": "fc6470ac-6d1b-4c84-8c61-00de2b8888d4"
}

{
   "amount": 1,
   "description": "DESCRIÇÃO",
   "sender": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "187470",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamento S.A."
      },
      "documentNumber": "12345678902",
      "name": "Peter Parker"
   },
   "recipient": {
      "documentType": "CPF",
      "account": {
         "branch": "0551",
         "number": "1085867",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "00000000",
         "compe": "001",
         "name": "Banco Do Brasil S.A."
      },
      "documentNumber": "12345678900",
      "name": "Carol Denvers"
   },
   "authenticationCode": "dd648881-f837-46ca-a9ee-79cb7e5c7ef3"
}

{
   "amount": 1,
   "description": "DESCRIÇÃO",
   "sender": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "187470",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções de Pagamento S.A."
      },
      "documentNumber": "12345678902",
      "name": "Peter Parker"
   },
   "recipient": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "219568",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções De Pagamento S.A."
      },
      "documentNumber": "12345678900",
      "name": "Carol Denvers"
   },
   "authenticationCode": "65411a0d-06af-4c4d-b61e-e0f0cb91c9ff"
}

📘
Nota
O campo name retornará o nome do documento de cadastro, e não o nome social.

Erros

Status code	Código	Descrição
400	SENDER_ACCOUNT_STATUS_NOT_ALLOW_CASH_OUT	O status da conta pagadora não permite o cash-out.
400	RECIPIENT_ACCOUNT_STATUS_NOT_ALLOW_CASH_IN	O status da conta recebedora não permite cash-in.
400	INVALID_RECIPIENT_ACCOUNT	A conta do pagador e do recebedor não podem ser a mesma.
400	SENDER_ACCOUNT_NOT_FOUND	Conta do pagador não encontrada para a realização da transferência.
400	RECIPIENT_ACCOUNT_NOT_FOUND	Conta do recebedor não encontrada para transferência interna.
400	CASHOUT_LIMIT_NOT_ENOUGH	A transação excede o limite de valor da transferência.
400	TIMEOUT	A requisição excedeu o tempo máximo para completar essa transação.
400	INVALID_BANK_BRANCH	Agência bancária inválida.
400	INVALID_BANK_ACCOUNT	Conta bancária inválida.
400	RECIPIENT_ACCOUNT_DOES_NOT_MATCH_THE_DOCUMENT	O documento informado não pertence à conta do recebedor.
400	SENDER_ACCOUNT_DOES_NOT_MATCH_THE_DOCUMENT	O documento informado não pertence à conta do pagador.
400	INSUFFICIENT_BALANCE	O cliente não possui saldo suficiente para a transação.
400	TRANSFER_WAS_REPROVED	A transferência não foi aprovada.
400	TRANSFER_AMOUNT_NOT_RESERVED	Erro ao reservar dinheiro para transferência.
400	TRANSFER_ORDER_NOT_PROCESSED	A transferência não foi processada.
400	INTERNAL_TRANSFER_NOT_COMPLETED	A transferência interna de Pix não foi completada.
404	ACCOUNT_NOT_FOUND	Conta não encontrada.
400	SCHEDULE_NOT_ALLOWED	Agendamento não permitido.
400	INVALID_END_TO_END_ID	`endToEndId` inválido.

Transferência via Pix

🚧
Importante

Etapas

Endpoint

🚧
Importante

Manual

📘
Nota

Por chave PIX

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

Retorno

📘
Nota

Erros

🚧Importante

Etapas

Endpoint

🚧Importante

Manual

📘Nota

Por chave PIX

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

Retorno

📘Nota

Erros

🚧
Importante

🚧
Importante

📘
Nota

📘
Nota