Manual do Dev
InstitucionalBlogService DeskStatus Page

Transferência via Pix

stable scopes: pix.cashout.create

Suggest Edits

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 codeCódigoDescrição
400SENDER_ACCOUNT_STATUS_NOT_ALLOW_CASH_OUTO status da conta pagadora não permite o cash-out.
400RECIPIENT_ACCOUNT_STATUS_NOT_ALLOW_CASH_INO status da conta recebedora não permite cash-in.
400INVALID_RECIPIENT_ACCOUNTA conta do pagador e do recebedor não podem ser a mesma.
400SENDER_ACCOUNT_NOT_FOUNDConta do pagador não encontrada para a realização da transferência.
400RECIPIENT_ACCOUNT_NOT_FOUNDConta do recebedor não encontrada para transferência interna.
400CASHOUT_LIMIT_NOT_ENOUGHA transação excede o limite de valor da transferência.
400TIMEOUTA requisição excedeu o tempo máximo para completar essa transação.
400INVALID_BANK_BRANCHAgência bancária inválida.
400INVALID_BANK_ACCOUNTConta bancária inválida.
400RECIPIENT_ACCOUNT_DOES_NOT_MATCH_THE_DOCUMENTO documento informado não pertence à conta do recebedor.
400SENDER_ACCOUNT_DOES_NOT_MATCH_THE_DOCUMENTO documento informado não pertence à conta do pagador.
400INSUFFICIENT_BALANCEO cliente não possui saldo suficiente para a transação.
400TRANSFER_WAS_REPROVEDA transferência não foi aprovada.
400TRANSFER_AMOUNT_NOT_RESERVEDErro ao reservar dinheiro para transferência.
400TRANSFER_ORDER_NOT_PROCESSEDA transferência não foi processada.
400INTERNAL_TRANSFER_NOT_COMPLETEDA transferência interna de Pix não foi completada.
404ACCOUNT_NOT_FOUNDConta não encontrada.
400SCHEDULE_NOT_ALLOWEDAgendamento não permitido.
400INVALID_END_TO_END_IDendToEndId inválido.

Updated 11 months ago