curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/split-payments/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
"externalId": "seller-4821",
"transferType": "PIX_MANUAL",
"account": {
"number": "123456",
"branch": "0001",
"type": "CURRENT",
"participantIspb": "00000000",
"holder": {
"document": "12345678909",
"name": "Maria Souza",
"type": "NATURAL"
}
}
}'
{
"id": "6f1c2a9e-3b7d-4e8a-9c21-5d4f0e7b8a13",
"bankAccountNumber": "10050",
"externalId": "seller-4821",
"transferType": {
"name": "PIX_MANUAL",
"description": "Pix Manual",
"value": 2
},
"account": {
"number": "123456",
"branch": "0001",
"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": null
}
{
"code": "SPLIT_BENEFICIARY_ALREADY_EXISTS",
"message": "Já existe um beneficiário ativo com o externalId seller-4821."
}
Beneficiários
Cadastrar beneficiário
Cadastre um beneficiário na conta de recebimento para usar o id dele nas instruções de split.
POST
/
baas
/
api
/
v1
/
split-payments
/
beneficiaries
curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/split-payments/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
"externalId": "seller-4821",
"transferType": "PIX_MANUAL",
"account": {
"number": "123456",
"branch": "0001",
"type": "CURRENT",
"participantIspb": "00000000",
"holder": {
"document": "12345678909",
"name": "Maria Souza",
"type": "NATURAL"
}
}
}'
{
"id": "6f1c2a9e-3b7d-4e8a-9c21-5d4f0e7b8a13",
"bankAccountNumber": "10050",
"externalId": "seller-4821",
"transferType": {
"name": "PIX_MANUAL",
"description": "Pix Manual",
"value": 2
},
"account": {
"number": "123456",
"branch": "0001",
"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": null
}
{
"code": "SPLIT_BENEFICIARY_ALREADY_EXISTS",
"message": "Já existe um beneficiário ativo com o externalId seller-4821."
}
Funcionalidade em beta. Contrato em proposta, sujeito a mudanças. Veja o guia Cadastro de beneficiários.
id retornado como beneficiaryId nas instruções de split do QR Code.
Headers
string
required
Sua API key.
string
required
Número da conta de recebimento, dona do cadastro.
Body
string
Identificador do beneficiário no seu sistema, por exemplo, o id do vendedor na sua plataforma. Até 100 caracteres. Não pode se repetir entre os beneficiários ativos da mesma conta de recebimento.
string
required
Forma de repasse:
INTERNAL (conta Delfinance), PIX_MANUAL (conta em qualquer instituição, por dados bancários) ou PIX_KEY (conta em qualquer instituição, por chave Pix).object
required
Conta do beneficiário. Os campos obrigatórios dependem do
transferType:INTERNAL: sónumber.PIX_MANUAL:number,branch,type,participantIspbeholder.PIX_KEY:pixKeyeholder.
Show account
Show account
string
Número da conta do beneficiário. Obrigatório para
INTERNAL e PIX_MANUAL. Com INTERNAL, a conta precisa existir na Delfinance.string
Agência da conta. Obrigatório para
PIX_MANUAL.string
Tipo da conta:
PAYMENT, CURRENT ou SAVING. Obrigatório para PIX_MANUAL.string
ISPB da instituição da conta (8 caracteres). Obrigatório para
PIX_MANUAL.string
Chave Pix do beneficiário: CPF, CNPJ, e-mail, telefone (
+55...) ou chave aleatória. Obrigatório para PIX_KEY. Só o formato é validado no cadastro. Se a chave for um CPF ou CNPJ, ela precisa ser igual a account.holder.document.Response
Retorna201 Created com o beneficiário cadastrado.
string
Identificador do beneficiário (UUID). Use como
beneficiaryId nas instruções de split.string
Conta de recebimento dona do cadastro.
string
Identificador do beneficiário no seu sistema, quando informado.
object
Forma de repasse, como enum (
name, description e value). name: INTERNAL, PIX_MANUAL ou PIX_KEY. Veja Formato dos enums.object
Conta do beneficiário, com os campos enviados no cadastro (
number, branch, type, participantIspb, pixKey e holder). Os campos que não se aplicam ao transferType vêm null.object
Situação do cadastro, como enum.
name: ACTIVE ou INACTIVE.string
Data e hora do cadastro, em ISO 8601.
string
Data e hora da última atualização, em ISO 8601.
Erros
| HTTP | Código | Quando acontece |
|---|---|---|
400 | VALIDATION_ERROR | Campo obrigatório ausente para o transferType, formato inválido de documento, ISPB ou chave Pix, ou chave CPF/CNPJ diferente de account.holder.document |
409 | SPLIT_BENEFICIARY_ALREADY_EXISTS | Já existe um beneficiário ativo com o mesmo externalId na conta de recebimento |
422 | ACCOUNT_NOT_FOUND | Com INTERNAL, a conta informada não existe na Delfinance |
curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/split-payments/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: {{apiKey}}' \
--header 'x-delfinance-account-id: {{accountId}}' \
--data '{
"externalId": "seller-4821",
"transferType": "PIX_MANUAL",
"account": {
"number": "123456",
"branch": "0001",
"type": "CURRENT",
"participantIspb": "00000000",
"holder": {
"document": "12345678909",
"name": "Maria Souza",
"type": "NATURAL"
}
}
}'
{
"id": "6f1c2a9e-3b7d-4e8a-9c21-5d4f0e7b8a13",
"bankAccountNumber": "10050",
"externalId": "seller-4821",
"transferType": {
"name": "PIX_MANUAL",
"description": "Pix Manual",
"value": 2
},
"account": {
"number": "123456",
"branch": "0001",
"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": null
}
{
"code": "SPLIT_BENEFICIARY_ALREADY_EXISTS",
"message": "Já existe um beneficiário ativo com o externalId seller-4821."
}