> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/docs/current-account/retrieve-account-beneficiaries/main.md).

# Retrieve Account Beneficiaries

| Campo              | Valor                                                    |
| ------------------ | -------------------------------------------------------- |
| **Service Domain** | Current Account                                          |
| **BIAN Version**   | 14.0.0                                                   |
| **Operation**      | Retrieve Account Beneficiaries                           |
| **Method**         | GET                                                      |
| **API Name**       | Account Beneficiaries                                    |
| **Versão**         | v1.0.0                                                   |
| **Endpoint**       | `GET /v1/current-account/account-beneficiaries/retrieve` |
| **Autenticação**   | Bearer Token (OAuth2 / JWT)                              |

***

## 1. Descrição da Operação

Retorna os detalhes de uma conta corrente, incluindo identificação da conta, dados do beneficiário, estado, moeda e informação da agência bancária.

Esta API segue o modelo do Service Domain **Current Account** do **BIAN**, garantindo padronização e interoperabilidade entre sistemas bancários.

***

## 2. Cabeçalhos HTTP

| Header          | Tipo   | Obrigatório | Descrição                                                                          |
| --------------- | ------ | ----------- | ---------------------------------------------------------------------------------- |
| `Authorization` | string | Sim         | Bearer Token. Ex.: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| `Content-Type`  | string | Sim         | `application/json`                                                                 |
| `Accept`        | string | Sim         | `application/json`                                                                 |
| `x-request-id`  | string | Não         | Identificador único da requisição.                                                 |

A API utiliza autenticação baseada em Bearer Token (OAuth2 ou JWT).

***

## 3. Query Parameters

| Parâmetro                    | Tipo   | Obrigatório | Descrição        |
| ---------------------------- | ------ | ----------- | ---------------- |
| `AccountIdentificationType`  | string | Sim         | Tipo da conta.   |
| `AccountIdentificationValue` | string | Sim         | Número da conta. |

***

## 4. Payload de Resposta (Response — 200 OK)

```json
{
  "CurrentAccountNumber": {
    "AccountIdentificationType": "IBAN",
    "AccountIdentification": {
      "IdentifierValue": {
        "Value": "AO06004700001390887810191"
      }
    }
  },
  "CustomerReference": {
    "PartyReference": {
      "PartyName": {
        "Name": "NIRIA MARISA NEVES LOPES ORAMALU"
      }
    }
  },
  "AccountIdentification": {
    "IdentifierValue": {
      "Value": "1390887810001"
    },
    "AccountStatus": "ACTIVE",
    "AccountCurrency": {
      "CurrencyCode": "AKZ"
    }
  },
  "BankBranchLocationReference": {
    "BranchIdentification": {
      "IdentifierValue": {
        "Value": "519"
      }
    },
    "BranchAddress": {
      "AddressType": "PostalAddress",
      "LocationReference": {
        "LocationDescription": {
          "Text": "EDIFICIO GARDEN, TORRE B AV. HO, CHI MIN EMP. CDT GIKA 1, FLOOR 12"
        }
      }
    },
    "BranchName": {
      "Name": "BANCO KEVE, SA"
    },
    "InternalBankAccountReference": {
      "InternalBankAccountType": "BIC",
      "InternalBankAccountValue": {
        "Value": "BRDKAOLUXXX"
      }
    },
    "BranchCountryCode": {
      "CountryCode": "AO",
      "BranchCountry": {
        "Name": "Angola"
      }
    }
  }
}
```

### 4.1 Descrição dos Campos

| Campo                          | Tipo   | Obrigatório | Descrição                |
| ------------------------------ | ------ | ----------- | ------------------------ |
| `CurrentAccountNumber`         | object | Sim         | Identificação da conta.  |
| `AccountIdentificationType`    | string | Sim         | Tipo (IBAN, BBAN).       |
| `IdentifierValue.Value`        | string | Sim         | Número da conta.         |
| `CustomerReference`            | object | Sim         | Dados do cliente.        |
| `PartyName.Name`               | string | Sim         | Nome do cliente.         |
| `AccountIdentification`        | object | Sim         | Dados internos da conta. |
| `AccountStatus`                | string | Sim         | Estado da conta.         |
| `AccountCurrency.CurrencyCode` | string | Sim         | Moeda.                   |
| `BankBranchLocationReference`  | object | Sim         | Dados da agência.        |

### 4.2 Tabela de Objetos e Cardinalidade

| Objeto            | Campo                         | Tipo   | Cardinalidade | Descrição              |
| ----------------- | ----------------------------- | ------ | ------------- | ---------------------- |
| CurrentAccount    | `CurrentAccountNumber`        | Object | 1..1          | Identificação externa. |
| CurrentAccount    | `CustomerReference`           | Object | 1..1          | Cliente.               |
| CurrentAccount    | `AccountIdentification`       | Object | 1..1          | Conta interna.         |
| CurrentAccount    | `BankBranchLocationReference` | Object | 1..1          | Agência.               |
| CustomerReference | `PartyName`                   | Object | 1..1          | Nome.                  |
| Branch            | `BranchIdentification`        | Object | 1..1          | ID da agência.         |

***

## 5. Códigos HTTP de Resposta

| Código | Estado                | Descrição             |
| ------ | --------------------- | --------------------- |
| 200    | OK                    | Sucesso.              |
| 400    | Bad Request           | Pedido inválido.      |
| 401    | Unauthorized          | Não autorizado.       |
| 403    | Forbidden             | Proibido.             |
| 404    | Not Found             | Conta não encontrada. |
| 500    | Internal Server Error | Erro interno.         |

### 5.1 Erros específicos de GET

| Erro                 | Código | Descrição          |
| -------------------- | ------ | ------------------ |
| Conta não encontrada | 404    | ID inválido.       |
| IBAN inválido        | 400    | Formato incorreto. |
| Token inválido       | 401    | Não autorizado.    |

***

## 6. Envelope Padrão de Erro

**Pedido inválido**

```json
{
  "error": {
    "status": 400,
    "reason": "INVALID_VALUE",
    "message": "Invalid Srci-Client Id",
    "path": "GET /v1/current-account/533610002/retrieve",
    "errordetail": [
      {
        "code": "123332",
        "reason": "INVALID_VALUE",
        "message": "Invalid Srci-Client Id"
      }
    ]
  }
}
```

**Erro Interno**

```json
{
  "error": {
    "status": 500,
    "reason": "INVALID_STATE",
    "message": "Internal server error. Typically a server bug. The client should report this error to the Mastercard support team",
    "path": "GET /v1/current-account/533610002/retrieve"
  }
}
```

***

## 7. Regras de Negócio

* IBAN deve ser válido (estrutura internacional).
* Conta deve existir.
* Conta deve pertencer ao cliente.
* Conta não pode estar encerrada para operações.

***

## 8. Requisitos Não-Funcionais

* HTTPS obrigatório.
* Autenticação via Bearer Token.
* Logs de auditoria obrigatórios.
* Criptografia de dados sensíveis.


---

# 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://selenium-4.gitbook.io/nexus-docs/docs/current-account/retrieve-account-beneficiaries/main.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.