Pix-Out

Ao receber pagamentos das cobranças, pode surgir a necessidade de transferir esses recursos para uma conta externa fora da plataforma. Para essa finalidade, a aplicação oferece um endpoint que permite realizar uma transação conhecida como Pix-out, que consiste em transferir fundos para uma chave Pix fora do ambiente da BIT Capital.

É importante observar que esse procedimento não é obrigatório, uma vez que cada cliente da plataforma possui, por padrão, uma conta bancária para recebimento de recursos custodiada pelo Banco Parati.

Usado para:

Transferir os saldos da conta interna de recebimentos para qualquer outra conta externa por meio de uma chave Pix.

Como fazer uma transferência Pix-Out

ENDPOINT: https://kaizen.bt-staging.app/pix-service/wallets/{{walletKZ}}/withdraw

Esse endpoint utiliza o método POST.

Endpoint:

https://kaizen.bt-{{env}}.app/pix-service/wallets/{{wallet}}/withdraw

curl --location 'https://kaizen.bt-staging.app/pix-service/wallets/ddfbfcd1-d094-4136-a908-ee489e694c6e/withdraw' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
	"key": "0d8298ed-c87d-45ec-b121-7239173aabef",  
	"amount": "1.5", 
	"description": "PIX-OUT de 1.5 para uma CHAVE PIX",
	"priority": "normal"
}'

curl --location 'https: //kaizen.bt-staging.app/pix-service/wallets/ddfbfcd1-d094-4136-a908-ee489e694c6e/withdraw' \
--header 'x-idempotence-key: IKb0ecc236-a4c3-4e7c-abe8-bd7a39749723' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "amount": "0.87",
    "description": "PIX-OUT de 0.87 para uma conta ISPB SANDBOX BACEN",
    "bank": {
        "bank": "99999004",
        "agency": "8008",
        "account": "295761",
        "taxId": "40422863807",
        "name": "Cliente Externo ISPB BACEN SANDBOX"
    }

}'

Modelo de requisição:

Header da requisição:

O uso dos Headers abaixo são opcionais durante a execução do Pix OUT. No entanto, caso não seja fornecido, serão automaticamente gerados dois campos: "idempotenceKey" e "endtoendId" nos seguintes formatos:

parâmetro do header	Obrigatoriedade	descrição	Formato	Exemplo
x-idempotence-key	Opcional	Chave de idempotencia da transação para garantir unicidade	UUIDv4	ff3a31d3-e578-40a0-a795-c5f95b1ae5d9
x-endtoend-Id	Opcional	E2E recebido na consulta dos dados da chave	String com 32 caracteres conforme padrão BACEN	E03311443202309061908c3oXxJfa7Zn

Formatos e exemplos dos parâmetros

x-endtoend-Id
- deve ser uma sequencia de 32 caracteres sendo:
  - deve iniciar com a letra "E" maiúscula
  - deve conter o IPSB do emissor, 8 caracteres
  - deve conter o ano da emissão, 4 caracteres
  - deve conter o mes da emissão, 2 caracteres
  - deve conter o dia da emissão, 2 caracteres
  - deve conter a hora e minuto da emissão no horário UTC0, 4 caracteres
  - deve conter uma sequencia de 11 caracteres(a-z, A-Z 0-9)
  - Exemplo de endtoendId: E03311443202309061908c3oXxJfa7Zn

👍
Dica de utilização:
É uma boa prática utilizar o E2E gerado na transação de consulta de chaves, que em geral é realizada antes do PIX OUT, para a requisição, com isso, além de já ter um E2E no padrão necessário, é possível reduzir o consumo de fichas (rate limit Bacen) no processo.
Saiba mais em: Sistema de baldes e fichas Bacen

Body de requisição:

{
	"key": "9875e6b1-89fb-4ebb-8fd5-364ffee2af55",
	"amount": "0.01",
	"description": "PIX-OUT withdraw para uma wallet externa",
	"priority": "high"
}

{
	"amount": "22.22",
	"description": "PIX-OUT de 22.22 para uma conta ISPB SANDBOX BACEN",
	"bank": {
		"bank": "99999004",
		"agency": "8008",
		"account": "295761",
		"taxId": "40422863807",
		"name": "Cliente Externo ISPB BACEN SANDBOX"
	}
}

Body de resposta:

{
      "id": "2f668485-a5f7-4133-b406-630d1f7c4b2f",
      "createdAt": "2023-08-17T19:52:12.271Z",
      "type": "withdrawal",
      "additionalData": {
        "clientWalletId": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
        "key": "66008158920",
        "description": "PIX-OUT de 1.43 para uma CHAVE EXTERNA",
        "priority": "high",
        "authorizerId": "55a1032f-f642-4165-ab65-ae6c15413584"
      
    },
      "amount": "1.43",
      "clientExternalId": "KAIcde91d1623934aafa615fdc43d0d49c7",
      "wallet": {
        "id": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
        "createdAt": "2022-09-20T14:24:29.109Z",
        "updatedAt": null,
        "deletedAt": null,
        "client": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
        "clientId": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
        "accountId": "92bc81ae-f7bf-4437-ad58-9dd61b1ff4c4",
        "additionalData": {},
        "status": "ready",
        "ispb": "03311443",
        "bankBranch": "0001",
        "bankNumber": "10000052202",
        "isPixoleto": false,
        "notificationUrl": "https://webhook-site-staging.bitcapital.teleport.sh/8918b4b9-572f-4820-a955-254dd615c62c"
      
    },
      "externalTransactionId": "2f668485-a5f7-4133-b406-630d1f7c4b2f",
      "endToEndId": "E03311443202308171952JleTTbobNzB",
      "idempotenceKey": "905d2c62de675e430f95342ebd504299b4",
      "source": {
        "account": {
          "bankBranch": "0001",
          "bankNumber": "10000052202",
          "ispb": "03311443"
        
        }
      
    },
      "states": [
        {
          "id": "aaa89ccb-57a6-481a-b359-f145f9d9d4e0",
          "createdAt": "2023-08-17T19:52:14.143Z",
          "additionalData": {},
          "status": "pending"
        
        },
        {
          "id": "74710e12-2e15-4cf1-9795-1be7eb5503a0",
          "createdAt": "2023-08-17T19:52:12.320Z",
          "additionalData": {},
          "status": "approved"
        
        }
      
    ],
      "updatedAt": "2023-08-17T19:52:12.315Z",
      "status": "pending"
}

{
    "id": "8acf0a6c-46cc-4fc8-957f-d24e32f10e71",
    "createdAt": "2023-08-30T13:16:48.289Z",
    "type": "withdrawal",
    "additionalData": {
        "clientWalletId": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
        "description": "PIX-OUT de 1.25 para uma conta ISPB SANDBOX BACEN",
        "bank": {
            "bank": "99999004",
            "agency": "8008",
            "account": "295761",
            "taxId": "40422863807",
            "name": "Cliente Externo ISPB BACEN SANDBOX"
        },
        "authorizerId": "af06ab9e-c73b-4169-a79b-9bff71e546d6"
    },
    "amount": "1.25",
    "clientExternalId": "KAI06a1a7337d80414984845ae0f7fe8a5e",
    "wallet": {
        "id": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
        "createdAt": "2022-09-20T14:24:29.109Z",
        "updatedAt": "2023-08-23T19:56:41.544Z",
        "deletedAt": null,
        "client": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
        "clientId": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
        "accountId": "92bc81ae-f7bf-4437-ad58-9dd61b1ff4c4",
        "additionalData": {
            "requiredCustomerName": true
        },
        "status": "ready",
        "ispb": "03311443",
        "bankBranch": "0001",
        "bankNumber": "10000052202",
        "isPixoleto": false,
        "notificationUrl": "https://webhook-site-staging.bitcapital.teleport.sh/630f709b-cabb-40df-a9da-ee7bdf95bb0a"
    },
    "externalTransactionId": "8acf0a6c-46cc-4fc8-957f-d24e32f10e71",
    "endToEndId": "E033114432023083013166EZXw0MycT8",
    "idempotenceKey": "IK980c721e351d42f290408f8157713e9f",
    "source": {
        "account": {
            "bankBranch": "0001",
            "bankNumber": "10000052202",
            "ispb": "03311443"
        }
    },
    "states": [
        {
            "id": "5faf9234-e10b-419a-9adf-bc00e11937ce",
            "createdAt": "2023-08-30T13:16:49.583Z",
            "additionalData": {},
            "status": "pending"
        },
        {
            "id": "5a7f529c-138e-4478-a21b-609a447c2657",
            "createdAt": "2023-08-30T13:16:48.323Z",
            "additionalData": {},
            "status": "approved"
        }
    ],
    "updatedAt": "2023-08-30T13:16:48.320Z",
    "status": "pending"
}

{
    "status": 403,
    "message": "The order was rejected by the bank side (for reasons concerning content)",
    "stackId": "c9987482-21c8-4cb9-878c-013b105d2bfe",
    "stack": false
}

{
	"status": 400,
	"message": "Insufficient Balance",
	"details": {},
	"stackId": "014c73a4-51f2-412a-b2a6-cdfc865809a9",
	"stack": false
}

{
    "status": 400,
    "message": "Key not found",
    "details": {},
    "stackId": "261016a9-b8f7-47cf-a4e5-6a9faf2b2ca4",
    "stack": false
}

Descrição dos campos:

Campo	Tipo	Descrição
key	string	Chave de destino que será enviado o pix-out
amount	string(00.00)	- string com casa decimal separada por ponto - valor do pix-out
description	string(72)	- descrição do pix-out
priority	emum(high \| normal)	- default : high
idempotenceKey	string(uuid)	- idempotenceKey da transação de pix-out
E2E	string()	- ID único da transação de PIX
status	ENUM(awaiting_approval, approved, pending, denied, feiled, success)	- status atual da transação (veja descrição abaixo)

❗️
Fluxo de aprovação de PIX OUT
Para retiradas de valores temos o subfluxo de aprovação, que vai validar se aquele PIX OUT deve ou não passar por uma análise. O fator principal para essa análise é o limite configurado na wallet do Cliente, ou seja, todo PIX OUT que for acima desse valor, passará pelo fluxo de aprovação, antes de ser executado.

Status da transação de Pix OUT

status	descrição	evolui para
awaiting_approval	- aguardando aprovação do serviço de alçadas (status inicial) - somente para trasnações acima do limite configurado	approved \| denied
approved	- aprovado pelo serviço de alçadas (status inicial)	pending
pending	- aguardando confirmação (Bacen) da execução da transação (status intermediário)	success \| failed
failed	- foi aprovado pelo serviço de alçadas, e houve erro ao liquidar (status final)	status final
success	- foi aprovado pelo serviço de alçadas, e houve sucesso ao liquidar (status final)	status final

📘
Status de PIX OUT (Transação)
Como a transação de PIX OUT possui o subfluxo de aprovação, os status desse fluxo também são replicados ao Cliente, na ordem cronológica abaixo, que deve ser acompanhada através do campo "createdAt":

awaiting approval - aguardando aprovação do serviço de alçadas (status inicial)

Apenas para transações acima do limite configurado.

approved - aprovado pelo serviço de alçadas (status inicial)

pending - aguardando confirmação (Bacen) da execução da transação (status intermediário)

denied - recusado pelo serviço de alçadas (status final)

failed - foi aprovado (serviço de alçadas) e houve erro ao liquidar (status final)

success - foi aprovado (serviço de alçadas) e houve sucesso na liquidação (status final)

❗️
Importante:
O campo "idempotenceKey" também é retornado no header de resposta e no postback transacional.

📘
Informação:
O campo "idempotenceKey" tem a função de rastrear uma transação e seus status, não permitir que essa transação seja executada duas vezes, ou que exista uma outra transação com a mesma idempotencia.
Essa chave pode ser um ID interno (Cliente) e deve seguir o seguinte padrão:

UUID;

E caso não seja informada será gerado pela aplicação.

Pix-Out

Usado para:

Como fazer uma transferência Pix-Out

Endpoint:

Modelo de requisição:

Header da requisição:

Formatos e exemplos dos parâmetros

👍
Dica de utilização:

Body de requisição:

Body de resposta:

Descrição dos campos:

❗️
Fluxo de aprovação de PIX OUT

Status da transação de Pix OUT

📘
Status de PIX OUT (Transação)

❗️
Importante:

📘
Informação:

Usado para:

Como fazer uma transferência Pix-Out

Endpoint:

Modelo de requisição:

Header da requisição:

Formatos e exemplos dos parâmetros

👍Dica de utilização:

Body de requisição:

Body de resposta:

Descrição dos campos:

❗️Fluxo de aprovação de PIX OUT

Status da transação de Pix OUT

📘Status de PIX OUT (Transação)

❗️Importante:

📘Informação:

👍
Dica de utilização:

❗️
Fluxo de aprovação de PIX OUT

📘
Status de PIX OUT (Transação)

❗️
Importante:

📘
Informação: