Pix transfer v3

Case initiationType="MANUAL"

customerId: string;  
externalId: string;//uuid  
initiationType: "MANUAL"  
transfer: {  
  branch: Joi.string().trim().required(),  
  accountNumber: string;  
  taxId: string;  
  accountType: "CACC" | "SLRY" | "SVGS" | "TRAN"  
  ispb: string;  
  name: string;  
  value: number;  
  description?: string; //optional
}

Case initiationType ="DICT"

customerId: string;
externalId: string; //uuid
initiationType: "DICT"
transfer: {
  key: string;
  keyType: 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'EVP'
  taxId: string;
  value: number;
  description?: string; //optional
}

🚧
Important
Due accounts must be registered in Bacen for payments in hml/dev, we only accept the following isbp and account type.
transfer{ isbp: 99999004' accountType = "TRAN"}
In addition, the branch and account number must be linked to a valid CPF/CNPJ.

Error Handling

If an error occurs in the request, one of the following error codes related in the error table will be returned: 400; 401; 403; 404; 405; 408; 409; 500; 502;

Validations asynchronous

In this v3 version of the cash-out flow, we have made some validations asynchronous. As a result, there will be changes in the way errors are returned: validations that previously blocked the request with an immediate error will now be handled asynchronously.

In these cases, we will send webhooks when a validation fails. The webhook used will be the existing pix_transaction_failed, and the reason for the rejection will be included in the errorCode and errorMessage fields.

{
  "callbackId": "01999bc7-cef4-73db-b06d-8d656dab429b",
  "callbackStatus": "created",
  "externalId": "0e48d66b-39a5-4ce5-9519-9178937e6741",
  "eventType": "pix_transaction_failed",
  "customerId": "01937341-93ab-7005-9497-f210dc1b57b8",
  "pixTransaction": {
    "pixTransactionId": "01999bc7-cef4-73db-b06d-8d656dab429b",
    "pixTransactionAmount": 0.01,
    "pixTransactionStatus": "fail",
    "pixTransactionType": "debit",
    "customerId": "01937341-93ab-7005-9497-f210dc1b57b8",
    "pixTransactionCreatedAt": "2025-09-30T17:59:47.188Z",
    "pixTransactionUpdatedAt": "2025-09-30T17:59:47.188Z",
    "pixTransactionEndToEndId": "E30980539202509301459d2ae340a168",
    "pixTransactionExternalId": "0e48d66b-39a5-4ce5-9519-9178937e6741",
    "pixAccountInfos": {
      "id": "d1d5a562-7d2a-4a7a-b48e-cccb20857e6e",
      "ispb": "30980539",
      "branch": "0001",
      "account": "2808550350",
      "accountType": "TRAN",
      "taxId": "78475413005",
      "personType": "CPF",
      "name": "Gabi teste"
    },
    "errorCode": "PIX-001",
    "errorMessage": "Account mismatch validation failed",
  }
}