> For the complete documentation index, see [llms.txt](https://docs.bullcredtech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bullcredtech.com/api-reference/apis-en/proposal-flow/post-proposals-banking-data.md).

# 6. Bank details

**POST** `/proposals/{proposalId}/banking-data`

Informs proposal disbursement data. The endpoint accepts traditional bank account, `use_pix_cpf: true` or an explicit Pix key validated in DICT before proceeding with the flow.

## URL Parameters

| Parameter    | Type          | Description |
| ------------ | ------------- | ----------- |
| `proposalId` | string (UUID) | Proposal ID |

## Request Body

There are three ways to provide disbursement data:

* traditional bank account
* Pix CPF of the holder with `use_pix_cpf: true`
* explicit Pix key with `pix_key` + `pix_key_type`

{% hint style="warning" %}
Do not mix traditional bank account with `pix_key` in the same request. When `pix_key` is provided, the API prioritizes the Pix flow and clears the traditional banking fields saved on the proposal.
{% endhint %}

### Option 1: Traditional Banking Data

| Field                | Type    |    Required   | Description                    | Example                                                             |
| -------------------- | ------- | :-----------: | ------------------------------ | ------------------------------------------------------------------- |
| `bank_code`          | string  | Conditional\* | COMPE bank code (3 digits)     | `"001"`                                                             |
| `bank_branch`        | string  | Conditional\* | Branch number                  | `"1234"`                                                            |
| `bank_branch_digit`  | string  |       No      | Branch check digit             | `"5"`                                                               |
| `bank_account`       | string  | Conditional\* | Account number (without digit) | `"123456789"`                                                       |
| `bank_account_digit` | string  | Conditional\* | Account check digit            | `"4"`                                                               |
| `account_type`       | string  | Conditional\* | Account type                   | `"checking"`, `"savings"`, `"checking"`, `"savings"` or `"payment"` |
| `use_pix_cpf`        | boolean |       No      | Use CPF PIX key                | `false`                                                             |

\*Required when `use_pix_cpf` is `false` or not provided.

{% hint style="info" %}
The `bank_code` needs to be in the list of banks authorized by Bull. The API normalizes codes with leading zero before validation.
{% endhint %}

### Option 2: CPF PIX Key

| Field         | Type    | Required | Description   |
| ------------- | ------- | :------: | ------------- |
| `use_pix_cpf` | boolean |    Yes   | Fixed: `true` |

When `use_pix_cpf = true`, traditional bank data is not needed. The disbursement will be configured for the proposal holder's CPF Pix key.

### Option 3: Standalone PIX Key

| Field          | Type   | Required | Description  | Example                                  |
| -------------- | ------ | :------: | ------------ | ---------------------------------------- |
| `pix_key`      | string |    Yes   | The PIX key  | `"123e4567-e89b-12d3-a456-426614174000"` |
| `pix_key_type` | string |    Yes   | PIX key type | `"EVP"`, `"EMAIL"`, `"PHONE"` or `"CPF"` |

| Type    | Format                          | Example                                  |
| ------- | ------------------------------- | ---------------------------------------- |
| `EVP`   | Random UUID (random key)        | `"123e4567-e89b-12d3-a456-426614174000"` |
| `EMAIL` | Email address                   | `"cliente@example.com"`                  |
| `PHONE` | Phone number with country code  | `"+5511999998888"`                       |
| `CPF`   | CPF (11 digits, no punctuation) | `"12345678901"`                          |

{% hint style="info" %}
`CNPJ` is not accepted in this flow.
{% endhint %}

{% hint style="info" %}
When `pix_key_type` for `PHONE`, the accepted format is international, such as `+5511999998888`.
{% endhint %}

## Validation Rules

* For traditional bank account, all required account fields must be sent.
* For `pix_key`, the field `pix_key_type` is required.
* The Pix key must belong to the same CPF as the proposal.
* The API queries DICT and validates whether the key is eligible to receive payments.
* The bank returned by DICT also needs to be on Bull's whitelist.
* `pix_key_type: "CNPJ"` returns an error, even if sent in the enum.
* The endpoint only accepts updates in stages before contracting and disbursement.

### Statuses that block this endpoint

If the proposal is in one of the statuses below, the API returns an error and does not update the data:

* `CREDIT_ANALYSIS_IN_PROGRESS`
* `CONTRACT_GENERATION_IN_PROGRESS`
* `CONTRACT_GENERATED`
* `AWAITING_SIGNATURE`
* `SIGNED`
* `DISBURSEMENT_FAILED`
* `DISBURSED`
* `PENDING_ANALYSIS`
* `ANALYSIS_APPROVED`
* `ANALYSIS_REPROVED`
* `SIGNATURE_FAILED`

## Request Examples

### Traditional Banking Data

```json
{
  "bank_code": "001",
  "bank_branch": "1234",
  "bank_branch_digit": "5",
  "bank_account": "123456789",
  "bank_account_digit": "4",
  "account_type": "checking",
  "use_pix_cpf": false
}
```

### CPF PIX Key

```json
{
  "use_pix_cpf": true
}
```

### Random PIX Key (EVP)

```json
{
  "pix_key": "123e4567-e89b-12d3-a456-426614174000",
  "pix_key_type": "EVP"
}
```

### Email PIX Key

```json
{
  "pix_key": "cliente@example.com",
  "pix_key_type": "EMAIL"
}
```

### Phone PIX Key

```json
{
  "pix_key": "+5511999998888",
  "pix_key_type": "PHONE"
}
```

### CPF PIX Key (via `pix_key`)

```json
{
  "pix_key": "12345678901",
  "pix_key_type": "CPF"
}
```

## Success Response (200 OK)

### Traditional bank account or Pix CPF

```json
{
  "message": "Banking data stored successfully",
  "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75",
  "status": "BANK_DATA_SUBMITTED",
  "ok": true
}
```

### Pix key validated successfully

```json
{
  "message": "PIX key confirmed and saved successfully",
  "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75",
  "status": "BANK_DATA_SUBMITTED",
  "ok": true
}
```

### Pix key not confirmed

When the Pix key cannot be confirmed, the API responds with `200 OK`, but with `ok: false`:

```json
{
  "message": "PIX key does not belong to the provided CPF",
  "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75",
  "status": "PIX_KEY_CPF_MISMATCH",
  "ok": false
}
```

## Account Types

| Value                          | Description      |
| ------------------------------ | ---------------- |
| `checking` or `checking`       | Checking Account |
| `savings` or `savings_account` | Savings Account  |
| `payment`                      | Payment Account  |

## Possible Errors

| Code | Message                                                                                   |
| ---- | ----------------------------------------------------------------------------------------- |
| 400  | Invalid banking data                                                                      |
| 400  | `PIX key type is required when pix_key is provided`                                       |
| 400  | `CNPJ-type PIX key is not supported in this flow. The holder must be the proposal's CPF.` |
| 400  | `PIX key was not validated`                                                               |
| 400  | `Bank not allowed. Select a bank from the authorized list.`                               |
| 400  | `Bank not accepted for PIX key`                                                           |
| 400  | `Cannot update banking data for a proposal with status {STATUS}`                          |
| 404  | Proposal not found                                                                        |

## Pix Validation Failure Returns

In addition to HTTP errors, the flow with `pix_key` can return `200 OK` with `ok: false` in these scenarios:

| `status`                | Meaning                                                   |
| ----------------------- | --------------------------------------------------------- |
| `PIX_KEY_CPF_MISMATCH`  | The key exists, but does not belong to the proposal's CPF |
| `PIX_KEY_NOT_CONFIRMED` | The key was not confirmed in the validation process       |

## Notes

* The data must be in the proposal holder's name (same CPF)
* Third-party accounts and third-party Pix keys are not accepted
* `use_pix_cpf: true` is the simplest path when the holder already has an active CPF Pix key
* `pix_key_type: "CPF"` with `pix_key` works as an alternative to `use_pix_cpf`, but goes through explicit key validation
* If the proposal is already in `DISBURSEMENT_FAILED`, this endpoint does not allow resending banking data
* In Pix integrations, treat `ok: false` as a business failure and request new data from the customer before proceeding

{% hint style="success" %}
**Next Step**

Generate the digital contract: [POST /proposals/{id}/contract](/api-reference/apis-en/proposal-flow/post-proposals-contract.md)
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bullcredtech.com/api-reference/apis-en/proposal-flow/post-proposals-banking-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.