> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delfinance.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizar beneficiário

> Atualize a forma de repasse, a conta ou o externalId de um beneficiário. A mudança vale para os repasses criados depois dela.

> [!WARNING]
>
> **Funcionalidade em beta.** Contrato em proposta, sujeito a mudanças. Veja o guia [Cadastro de beneficiários](https://docs.delfinance.com.br/guias/split-pagamentos/beneficiarios.md).

Atualiza um beneficiário ativo. Envie só os campos que quer mudar.

> [!NOTE]
>
> A mudança vale para os repasses criados **depois** dela. Os repasses já criados, inclusive os agendados, guardam os dados da conta que tinham no momento da criação.

## Headers

**x-delbank-api-key** `string` *required*

Sua API key.

**x-delfinance-account-id** `string` *required*

Número da conta de recebimento.

## Path params

**id** `string` *required*

Identificador do beneficiário (UUID).

## Body

Os campos são os mesmos de [Cadastrar beneficiário](https://docs.delfinance.com.br/api-reference/split-pagamentos/beneficiarios/cadastrar.md#body), todos opcionais. O `id` e a conta de recebimento dona do cadastro não podem ser alterados.

**externalId** `string`

Novo identificador do beneficiário no seu sistema.

**transferType** `string`

Nova forma de repasse. Ao mudar a forma de repasse, envie também o `account` com os campos obrigatórios da nova forma.

**account** `object`

Campos da conta a alterar. Depois da atualização, a conta precisa ter todos os campos obrigatórios do `transferType`, e as mesmas validações do cadastro são aplicadas.

## Response

Retorna o beneficiário atualizado, com a estrutura descrita em [Cadastrar beneficiário](https://docs.delfinance.com.br/api-reference/split-pagamentos/beneficiarios/cadastrar.md#response).

## Erros

| HTTP | Código | Quando acontece |
| - | - | - |
| `400` | `VALIDATION_ERROR` | O resultado não tem os campos obrigatórios do `transferType`, ou algum campo tem formato inválido |
| `404` | `SPLIT_BENEFICIARY_NOT_FOUND` | Não existe beneficiário com esse `id` na conta de recebimento |
| `409` | `SPLIT_BENEFICIARY_ALREADY_EXISTS` | O novo `externalId` já é usado por outro beneficiário ativo |
| `422` | `SPLIT_BENEFICIARY_INACTIVE` | O beneficiário está inativo |

```bash cURL theme={null}
curl --location --request PATCH 'https://apisandbox.delbank.com.br/baas/api/v1/split-payments/beneficiaries/6f1c2a9e-3b7d-4e8a-9c21-5d4f0e7b8a13' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
    "account": {
        "number": "654321",
        "branch": "0002"
    }
}'
```

```json 200 theme={null}
{
    "id": "6f1c2a9e-3b7d-4e8a-9c21-5d4f0e7b8a13",
    "bankAccountNumber": "10050",
    "externalId": "seller-4821",
    "transferType": {
        "name": "PIX_MANUAL",
        "description": "Pix Manual",
        "value": 2
    },
    "account": {
        "number": "654321",
        "branch": "0002",
        "type": "CURRENT",
        "participantIspb": "00000000",
        "pixKey": null,
        "holder": {
            "document": "12345678909",
            "name": "Maria Souza",
            "type": "NATURAL"
        }
    },
    "status": {
        "name": "ACTIVE",
        "description": "Ativo",
        "value": 0
    },
    "createdAt": "2026-11-03T14:00:00.000Z",
    "updatedAt": "2026-11-10T09:30:00.000Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.