Skip to main content
Funcionalidade em beta. As rotas e os campos descritos aqui são uma proposta e podem mudar antes da versão final. Não use em produção sem alinhar com o time Delfinance.
O cadastro de beneficiários guarda, na sua conta de recebimento, os dados de cada beneficiário: a forma de repasse e a conta para onde vai a parte dele. Com o beneficiário cadastrado, a instrução de split do QR Code leva só o valor, o tipo e o beneficiaryId. Sem o cadastro, cada instrução precisa enviar o objeto beneficiary completo. Os dois formatos continuam aceitos. Veja Usar um beneficiário cadastrado.
Em um marketplace, cadastre cada vendedor quando ele entra na plataforma e guarde o id retornado junto com o cadastro dele. Use o externalId para gravar o id do vendedor no seu sistema e encontrá-lo depois.

​
Como funciona

  1. Você cadastra o beneficiário, com a forma de repasse (transferType) e os dados da conta (account).
  2. A Delfinance devolve o id do beneficiário, um UUID.
  3. Nas instruções de split do QR Code, você informa o beneficiaryId no lugar do transferType e do objeto beneficiary.
  4. Quando o Pix é pago, a Delfinance busca o beneficiário e cria o repasse com os dados da conta daquele momento.
Cada beneficiário pertence à conta de recebimento que o cadastrou. Uma conta não vê nem usa os beneficiários de outra.

​
Cadastrar um beneficiário

O corpo tem a forma de repasse na raiz e os dados da conta em account, no mesmo formato do beneficiary da instrução de split.
Para uma conta Delfinance, basta o número da conta.
Veja todos os campos e as regras de validação em Cadastrar beneficiário.

​
Usar o beneficiário numa cobrança

Na instrução de split do QR Code, troque o transferType e o beneficiary pelo beneficiaryId:
O beneficiaryId não é verificado na criação do QR Code, só no pagamento. Se o beneficiário não existir, for de outra conta ou estiver inativo, o repasse é criado em ERROR, nenhuma transferência é feita e o valor fica na conta de recebimento. Veja Usar um beneficiário cadastrado.

​
Atualizar e inativar

  • Atualizar: use Atualizar beneficiário para mudar a forma de repasse, os dados da conta ou o externalId. A mudança vale para os repasses criados depois dela. Os repasses já criados guardam os dados da conta que tinham no momento da criação.
  • Inativar: use Inativar beneficiário. O beneficiário não é apagado e continua aparecendo nas consultas, mas os novos pagamentos que o referenciarem geram repasses em ERROR.

​
Acompanhar os repasses de um beneficiário

Cada repasse criado a partir de um beneficiário cadastrado traz o beneficiaryId. Para ver todos os repasses de um beneficiário, inclusive os criados antes de uma mudança na conta dele, filtre Listar repasses por beneficiaryId.
Nas rotas do split padrão da conta, o caminho /configurations/{splitPaymentId}/beneficiaries se refere às instruções do split padrão, e não a este cadastro. O split padrão ainda não aceita beneficiaryId.

​
Referência da API

Cadastrar beneficiário

POST /split-payments/beneficiaries

Listar beneficiários

GET /split-payments/beneficiaries

Consultar beneficiário

GET /split-payments/beneficiaries/{id}

Atualizar beneficiário

PATCH /split-payments/beneficiaries/{id}

Inativar beneficiário

DELETE /split-payments/beneficiaries/{id}