Contas (Account)

stable

Os eventos relacionados a contas disparam mensagens que comunicam ao destinatário a abertura, o encerramento, o bloqueio e o desbloqueio de uma conta e sobre o processo de bloqueio/desbloqueio judicial de valores.

Para mais informações sobre quando essas mensagens são disparadas e sobre o seu conteúdo, consulte as páginas:

  • Visão Geral (Gestão de conta);
  • Abertura de conta. Para mais informações, acesse a seção Gestão de conta na aba v1 deste manual;
  • Encerramento de conta. Para mais informações, acesse a seção Gestão de conta na aba v1 deste manual.

🚧

Importante

Recordamos que esta documentação apenas descreve os eventos na versão 2.0. Para saber os detalhes dos demais eventos do contexto "Account", acesse a documentação da versão 1.0.

Pré-requisitos

Para receber esses eventos, o parceiro deverá:

  • Configurar previamente o recebedor de eventos do webhook. Para mais informações, acesse a seção Webhooks na aba v1 deste manual.
  • Conhecer a estrutura básica dos eventos que acompanha o objeto data.

Informações sobre os eventos

Contexto e nome do evento

Os campos context e name poderão variar de acordo com a tabela a seguir:

contextnameDescrição
AccountPAYMENT_ACCOUNT_WAS_LOCKEDA conta foi bloqueada.
AccountPAYMENT_ACCOUNT_WAS_UNLOCKEDA conta foi desbloqueada.

Fluxo dos eventos

O fluxograma a seguir descreve a sequência em que os eventos ocorrem. Clique na imagem para ampliá-la:

Identificador (entityId)

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão, conforme a tabela a seguir:

EventoIdentificador (entityId )Descrição
PAYMENT_ACCOUNT_WAS_LOCKEDaccount.numberNúmero da conta do cliente.
PAYMENT_ACCOUNT_WAS_UNLOCKEDaccount.numberNúmero da conta do cliente.

Dados dos eventos

PAYMENT_ACCOUNT_WAS_LOCKED

Este evento sinaliza que a conta foi bloqueada para transações do tipo cash-out, emissão de boletos e consulta de chaves Pix.

Descrição do objeto data do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

NomeTipoDescrição
statusstringSituação da conta, que nesse caso será "LOCKED".
reasonstringMotivo do bloqueio da conta .
branchstringNúmero da agência bancária.
numberstringNúmero da conta.
bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
bank.codestringCódigo do banco.
bank.namestringNome do banco.
holderobjectObjeto que contém informações sobre o titular da conta.
holder.documentobjectObjeto que contém os dados do documento do titular da conta.
holder.document.valuestringNúmero do documento do titular da conta.
holder.document.typestringTipo do documento, o qual pode ser "CPF" ou "CNPJ".
holder.namestringNome do cliente titular da conta.
holder.statusstringSituação do cliente titular da conta, o qual pode ser PENDING_APPROVAL, APPROVED, IN_ANALYSIS, REPROVED e BLOCKLISTED.
holder.typestringTipo de titular, o qual pode ser "Customer" ou "Business".

Motivos de bloqueio da conta

MotivoDescrição
TRANSACTION_CONTESTATIONBloqueio por política interna de risco relacionado ao transacional.
SUSPICIOUS_BEHAVIORBloqueio por política interna de risco relacionado a comportamento de risco.

👍

Dica

O campo reason indica a causa do bloqueio e serve como guia para o orientar o cliente sobre o que fazer para desbloquear a conta (quando for o caso).

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

Exemplo de payload
{
    "entityId": "12345678",
    "idempotencyKey": "3b90efcf-78ab-4809-8308-6f0fbff65afd",
    "companyKey": "ACESSO",
    "context": "Account",
    "name": "PAYMENT_ACCOUNT_WAS_LOCKED",
    "timestamp": "2023-05-05 15:10:15.278000+00:00",
    "correlationId": "285af944-9383-4bde-81dd-3089a6cb89b0",
    "version": "2",
    "data": {
      "status": "LOCKED",
      "reason": "TRANSACTION_CONTESTATION",
      "branch": "0001",
      "number": "15164",
      "bank": {
        "ispb": "13140088",
        "code": "332",
        "name": "Acesso Soluções Pagamentos S.A"
      },
      "holder": {
        "document": {
          "value": "47742663023",
          "type": "CPF"
        },
        "name": "Nísia Floresta",
        "status": "APPROVED",
        "type": "CUSTOMER"
      }
    }
  }

PAYMENT_ACCOUNT_WAS_UNLOCKED

Este evento sinaliza que a conta foi desbloqueada e pode voltar a realizar transações do tipo cash-out, emissão de boletos e consulta de chaves Pix.

🚧

Importante

O desbloqueio é realizado por meio de análise de prevenção à fraude. A análise pode ser solicitada via Service Desk.

Descrição do objeto data do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

NomeTipoDescrição
statusstringSituação da conta, que pode ser: "Active", "Closed" ou "Locked".
branchstringNúmero da agência bancária.
numberstringNúmero da conta.
bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
bank.codestringCódigo do banco.
bank.namestringNome do banco.
holderobjectObjeto que contém informações sobre o titular da conta.
holder.documentobjectObjeto que contém os dados do documento do titular da conta.
holder.document.valuestringNúmero do documento do titular da conta.
holder.document.typestringTipo do documento, o qual pode ser "CPF" ou "CNPJ".
holder.namestringNome do cliente titular da conta.
holder.statusstringSituação do cliente titular da conta, o qual pode ser PENDING_APPROVAL, APPROVED, IN_ANALYSIS, REPROVED e BLOCKLISTED.
holder.typestringTipo de titular, o qual pode ser "Customer" ou "Business".

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

Exemplo de payload
{
    "entityId": "12345678",
    "idempotencyKey": "3927e0f0-d29e-43a6-8f46-6cad99862a82",
    "companyKey": "ACESSO",
    "context": "Account",
    "name": "PAYMENT_ACCOUNT_WAS_UNLOCKED",
    "timestamp": "2023-05-16 11:36:59.801000+00:00",
    "correlationId": "271af454-fddc-4c2a-a7b4-a62bd98de42f",
    "version": "2",
    "data": {
      "status": "APPROVED",
      "branch": "0001",
      "number": "15164",
      "bank": {
        "ispb": "13140088",
        "code": "332",
        "name": "Acesso Soluções Pagamentos S.A"
      },
      "holder": {
        "document": {
          "value": "47742663023",
          "type": "CPF"
        },
        "name": "Nísia Floresta",
        "status": "APPROVED",
        "type": "CUSTOMER"
      }
    }
  }