# Transferências PIX

## Ciclo de Vida

### Fluxo Padrão

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/pix/transfers
    B-->>P: 201 Created (status: PENDING)
    Note over B: Valida chave PIX e cria a transação
    P->>B: POST /v1/pix/transfers/{id}/approve
    B-->>P: 200 OK (status: PROCESSING)
    Note over B: Processamento assíncrono
    B-->>P: Webhook cash_out.update (SUCCESS)
```

### Fluxo com Falha na Aprovação

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/pix/transfers
    B-->>P: 201 Created (status: PENDING)
    P->>B: POST /v1/pix/transfers/{id}/approve
    B-->>P: 200 OK (status: PROCESSING)
    Note over B: Processamento assíncrono
    B-->>P: Webhook cash_out.update (FAILED)
```

### Fluxo com Falha na Criação

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/pix/transfers
    B-->>P: 201 Created (status: FAILED)
    Note over B: Falha ao criar transação pix
```

### Status

| Status       | Descrição                                  |
| ------------ | ------------------------------------------ |
| `PENDING`    | Transferência criada, aguardando aprovação |
| `PROCESSING` | Transferência aprovada, em processamento   |
| `SUCCESS`    | Transferência concluída com sucesso        |
| `FAILED`     | Transferência falhou                       |
| `RETURNED`   | Transferência estornada                    |

***

## POST /v1/pix/transfers

Cria uma nova transferência PIX. A transferência é criada com status `PENDING` e precisa ser aprovada via `POST /v1/pix/transfers/{id}/approve` para iniciar o processamento assíncrono.

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v1/pix/transfers' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "pixKey": "12345678900",
    "pixKeyType": "CPF",
    "amount": 100.00,
    "description": "Pagamento de serviço",
    "idempotencyKey": "unique-key-123"
  }'
```

### Campos — Request

| Campo            | Tipo       | Obrigatório | Validação                                                               |
| ---------------- | ---------- | ----------- | ----------------------------------------------------------------------- |
| `accountId`      | UUID       | Sim         | UUID v4 da conta bancária                                               |
| `pixKey`         | String     | Sim         | Chave PIX do destinatário. Validada conforme o tipo (ver tabela abaixo) |
| `pixKeyType`     | String     | Sim         | Enum: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                            |
| `amount`         | BigDecimal | Sim         | Valor em reais. Mínimo: `0.01`. Ex: `100.00`                            |
| `description`    | String     | Não         | Descrição da transferência                                              |
| `idempotencyKey` | String     | Sim         | Chave única para deduplicação. Não pode estar vazio                     |

### Tipos de Chave PIX

| Tipo    | Descrição                | Formato esperado                                  |
| ------- | ------------------------ | ------------------------------------------------- |
| `CPF`   | CPF do destinatário      | 11 dígitos numéricos (ex: `12345678900`)          |
| `CNPJ`  | CNPJ do destinatário     | 14 dígitos numéricos (ex: `12345678000190`)       |
| `EMAIL` | Email do destinatário    | Formato de email válido (ex: `user@example.com`)  |
| `PHONE` | Telefone do destinatário | `+55` + DDD + número (ex: `+5511999998888`)       |
| `EVP`   | Chave aleatória          | UUID (ex: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`) |

Se o formato da chave não corresponder ao tipo informado, a API retorna **400 Bad Request** com o erro `BNK-0501`.

### Idempotência

O campo `idempotencyKey` garante a deduplicação de requisições. Se uma requisição com a mesma chave já existir, a API retorna **409 Conflict** com o erro `BNK-0316`.

**Response — 201 Created:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PENDING",
  "amount": 100.00,
  "pixKey": "12345678900",
  "pixKeyType": "CPF",
  "recipientName": "João da Silva",
  "recipientDocument": "12345678900",
  "endToEndId": null,
  "description": "Pagamento de serviço",
  "idempotencyKey": "unique-key-123"
}
```

### Campos — Response

| Campo               | Tipo       | Descrição                                                                         |
| ------------------- | ---------- | --------------------------------------------------------------------------------- |
| `id`                | String     | Identificador único da transferência (UUID)                                       |
| `status`            | String     | Status da transferência: `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`, `RETURNED` |
| `amount`            | BigDecimal | Valor em reais. Ex: `100.00`                                                      |
| `pixKey`            | String     | Chave PIX utilizada                                                               |
| `pixKeyType`        | String     | Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                         |
| `recipientName`     | String     | Nome do destinatário                                                              |
| `recipientDocument` | String     | Documento do destinatário (CPF/CNPJ)                                              |
| `endToEndId`        | String     | Identificador end-to-end do PIX (pode ser `null` durante processamento)           |
| `description`       | String     | Descrição da transferência (pode ser `null`)                                      |
| `idempotencyKey`    | String     | Chave de idempotência                                                             |

**Response — 400 Bad Request (campo obrigatório ausente):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request amount - Amount must be greater than 0"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (JSON inválido):**

```json
{
  "errors": [
    {
      "code": "BAR-0501",
      "title": "INVALID_REQUEST_PARAM",
      "description": "JSON parse error: ..."
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 403 Forbidden (sem acesso a conta):**

```json
{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found (conta não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account with id f47ac10b-58cc-4372-a567-0e02b2c3d479 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (formato de chave PIX inválido):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Error in request",
      "description": "Invalid PIX key format for type CPF: abc123"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 409 Conflict (idempotency key duplicada):**

```json
{
  "errors": [
    {
      "code": "BNK-0316",
      "title": "Payment flow error",
      "description": "Payment already exists for idempotency key: unique-key-123"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                               |
| ------------------ | ------------------------------------------------------- |
| `201 Created`      | Transferência criada, aguardando aprovação              |
| `400 Bad Request`  | Dados inválidos ou campos obrigatórios ausentes         |
| `401 Unauthorized` | Token inválido ou expirado                              |
| `403 Forbidden`    | Sem acesso a conta                                      |
| `404 Not Found`    | Conta bancária não encontrada                           |
| `409 Conflict`     | Já existe uma transferência com a mesma idempotency key |

***

## GET /v1/pix/transfers/{id}

Consulta os detalhes de uma transferência PIX.

**Path Parameters:**

| Parâmetro | Tipo   | Descrição                             |
| --------- | ------ | ------------------------------------- |
| `id`      | String | Identificador da transferência (UUID) |

**Request:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v1/pix/transfers/a1b2c3d4-5678-90ab-cdef-1234567890ab' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "amount": 100.00,
  "pixKey": "12345678900",
  "pixKeyType": "CPF",
  "description": "Pagamento de serviço",
  "status": "SUCCESS",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "recipient": {
    "name": "João da Silva",
    "document": "12345678900",
    "ispb": "31680151"
  },
  "failReason": null,
  "createdAt": "2026-01-30T15:30:00",
  "completedAt": "2026-01-30T15:30:05"
}
```

### Campos — Response

| Campo                | Tipo       | Descrição                                                                         |
| -------------------- | ---------- | --------------------------------------------------------------------------------- |
| `id`                 | String     | Identificador único da transferência (UUID)                                       |
| `accountId`          | String     | UUID da conta bancária                                                            |
| `amount`             | BigDecimal | Valor em reais. Ex: `100.00`                                                      |
| `pixKey`             | String     | Chave PIX utilizada                                                               |
| `pixKeyType`         | String     | Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                         |
| `description`        | String     | Descrição da transferência (pode ser `null`)                                      |
| `status`             | String     | Status da transferência: `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`, `RETURNED` |
| `endToEndId`         | String     | Identificador end-to-end do PIX (pode ser `null`)                                 |
| `recipient`          | Object     | Dados do destinatário                                                             |
| `recipient.name`     | String     | Nome do destinatário                                                              |
| `recipient.document` | String     | Documento do destinatário (CPF/CNPJ)                                              |
| `recipient.ispb`     | String     | Código ISPB do banco do destinatário (pode ser `null`)                            |
| `failReason`         | String     | Motivo da falha (pode ser `null`)                                                 |
| `createdAt`          | String     | Data/hora de criação (ISO 8601)                                                   |
| `completedAt`        | String     | Data/hora de conclusão (pode ser `null`)                                          |

**Response — 403 Forbidden (sem acesso a conta):**

```json
{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found (transferência não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0301",
      "title": "Payment flow error",
      "description": "Payment not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                    |
| ------------------ | ---------------------------- |
| `200 OK`           | Detalhes da transferência    |
| `401 Unauthorized` | Token inválido ou expirado   |
| `403 Forbidden`    | Sem acesso a conta           |
| `404 Not Found`    | Transferência não encontrada |

***

## POST /v1/pix/transfers/{id}/approve

Aprova uma transferência PIX previamente criada.

**Path Parameters:**

| Parâmetro | Tipo   | Descrição                             |
| --------- | ------ | ------------------------------------- |
| `id`      | String | Identificador da transferência (UUID) |

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v1/pix/transfers/a1b2c3d4-5678-90ab-cdef-1234567890ab/approve' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PROCESSING",
  "amount": 100.00,
  "pixKey": "12345678900",
  "pixKeyType": "CPF",
  "recipientName": "João da Silva",
  "recipientDocument": "12345678900",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "description": "Pagamento de serviço",
  "idempotencyKey": "unique-key-123"
}
```

**Response — 404 Not Found (transferência não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0301",
      "title": "Payment flow error",
      "description": "Payment not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (transferência já aprovada ou não está em CREATED):**

```json
{
  "errors": [
    {
      "code": "BNK-0302",
      "title": "Payment flow error",
      "description": "Payment already submitted"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (erro no provider):**

```json
{
  "errors": [
    {
      "code": "BNK-0313",
      "title": "Transfer domain flow error",
      "description": "Seller payment failed"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 403 Forbidden (sem acesso a conta):**

```json
{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                                      |
| ------------------ | -------------------------------------------------------------- |
| `200 OK`           | Transferência aprovada e em processamento                      |
| `400 Bad Request`  | Transferência não está em status `CREATED` ou erro no provider |
| `401 Unauthorized` | Token inválido ou expirado                                     |
| `403 Forbidden`    | Sem acesso a conta                                             |
| `404 Not Found`    | Transferência não encontrada                                   |


---

# Agent Instructions: 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:

```
GET https://docs.barte.com/banking/api/pix-transfers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.