Transferências PIX

Ciclo de Vida

Fluxo Padrão

Fluxo com Falha na Aprovação

Fluxo com Falha na Criação

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:

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: [e-mail])
PHONE	Telefone do destinatário	+55 + DDD + número (ex: [phone])
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:

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

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:

{
  "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):

{
  "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):

{
  "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:

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:

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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