Transferência via Pix

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

• 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 através do nosso Service Desk.

📘

Nota

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

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

• Realizar a consulta das informações vinculadas à chave Pix, por meio do endpoint Consulta de chaves para transferência (em caso de transferência via chave Pix);
• Obter o endToEndId e o conciliationId no endpoint de Decodificação de QR Code (em caso de transferência por QR Code estático ou dinâmico).

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/pix/transfer

--request POST 'https://sandbox.hiperbanco.com.br/pix/transfer' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--header 'Idempotency-Key: d9a2305a-7b93-4a43-b0c3-a494480c8c36' \
--data-raw '{
    "sender": {
        "account": {
            "type": "CHECKING",
            "branch": "0001",
            "number": "1101958127"
        },
        "documentNumber": "35698525475",
        "name": "Edson Batista"
    },
    "amount": 0.10,
    "initializationType": "Key",
    "endToEndId": "E1314008820211019140822078594881",
    "pixKey": "35698525475",
		"description": "Pix cashout via Key",
    "paymentDate": ""
}'

Cabeçalhos (Headers)

📘

Nota

Informe um UUID novo a 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:

⚠️

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.

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).

👍

Dica

Recordamos que, 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:

Manual

📘

Nota

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

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

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

{
    "sender": {
        "account": {
            "type": "CHECKING",
            "branch": "0001",
            "number": "111015164"
        },
        "documentNumber": "47742663023",
        "name": "Nísia Floresta"
    },
    "amount": 0.10,
    "description": "Pagar Pix por Chave Pix",
    "initializationType": "Key",
    "endToEndId": "E1314008820210628213443832702790",
    "pixKey": "86046117747170",
    "paymentDate": ""
}

{
    "sender": {
        "account": {
            "type": "CHECKING",
            "branch": "0001",
            "number": "111015164"
        },
        "documentNumber": "47742663023",
        "name": "Nísia Floresta"
    },
    "amount": 1,
    "description": "Transfêrencia Pix QrCode Estático",
    "initializationType": "StaticQrCode",
    "endToEndId": "E1314008820210628213443832702790",
    "pixKey": "86046117747170",
    "conciliationId": "FiCapc7D0Ul7KHDOnZp8HGaCS",
    "paymentDate": ""
}

{
    "sender": {
        "account": {
            "type": "CHECKING",
            "branch": "0001",
            "number": "111015164"
        },
        "documentNumber": "47742663023",
        "name": "Nísia Floresta"
    },
    "amount": 1,
    "description": "Transfêrencia Pix QrCode Estático",
    "initializationType": "DynamicQrCode",
    "endToEndId": "E1314008820210628213443832702790",
    "pixKey": "86046117747170",
    "receiverReconciliationId": "Jk6GDZxqDD0HizWOfIYxGosIn9",
    "paymentDate": ""
}

{
    "amount": 3.36,
    "transactionNotes": "Pix Manual",
    "initializationType": "Manual",
    "sender": {
        "documentNumber": "73379344915",
        "name": "Nísia Floresta",
        "account": {
            "type": "CHECKING",
            "branch": "0001",
            "number": "1104714229"
        }
    },
    "recipient": {
        "documentNumber": "52145638795",
        "name": "Alberto Gilberto",
        "account": {
            "branch": "0001",
            "number": "1101263307",
            "type": "CHECKING"
        },
        "bank": {
            "ispb": "13140088"
        }
    },
    "paymentDate": ""
}

Resposta (Response)

O status code 202 indicará sucesso na transação.

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:

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints 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:

📘

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. Nesse cenário, o parceiro receberá dois eventos: PIX_CASHOUT_WAS_CANCELED e PIX_CASHOUT_WAS_UNDONE.