Associar Conta Destino

Associar conta destino

Para associar uma conta destino externa, utilizada para envio dos valores de repasse no momento de Funds Out, utilize a rota abaixo.
A rota deve ser utilizada tanto para cadastro quanto para alteração de conta destino externa.

POST /v1/marketplaces/{marketplace_id}/profiles/{profile_id}/external-bank-account

{
  "bank_code": "260",
  "agency_number": "0001",
  "account_number": "123456-7",
  "account_type": "CHECKING"
}

Resposta 204 No Content (sem corpo).

Caso a associação seja feita com sucesso, será retornado o webhook profile.external_account_validation_succeeded

{
  "type": "profile.external_account_validation_succeeded,
  "resource": "event",
  "payload": {
    "object": {
      "onboarding_id": "onboarding-1",
      "profile_id": "85b00690-...",
      "status": "EXTERNAL_ACCOUNT_VALIDATION_FAILED",
      "bank_code": "341",
      "agency_number": "3000",
      "account_number": "600000"
    }
  }
}

⚠️ Erros comuns na associação de conta destino

Erro	Causa	Correção
`404`	`PROFILE_NOT_FOUND`	Profile não encontrado
`422`	`INVALID_STATE`	Operação não permitida no estado atual do Profile

Importante | Validação de Titularidade
Após cadastro da conta destino externa, fazemos um Pix de R$0,01 para validar a titularidade dessa conta. A titularidade deve ser a mesma do Profile cadastrado, caso não seja, esse cadastro será negado.
Essa validação ocorre tanto no Credenciamento (caso os dados de conta destino externa sejam enviados) quanto no endpoint acima de Associação de Conta Destino.

O retorno da validação de titularidade acima será informada para o Marketplace através do webhook profile.external_account_validation_failed:

{
  "type": "profile.external_account_validation_failed",
  "resource": "event",
  "payload": {
    "object": {
      "onboarding_id": "onboarding-1",
      "profile_id": "85b00690-...",
      "status": "EXTERNAL_ACCOUNT_VALIDATION_FAILED",
      "bank_code": "341",
      "agency_number": "3000",
      "account_number": "600000",
      "retry": true,
      "decision_reasons": [
        { "reason": "...", "detail": "..." }
      ]
    }
  }
}

Para mais informações sobre Webhook, consulte o Catálogo de Webhooks.