Criação de conta pocket

Com uma conta de pagamento ativa no Bankly, nossos parceiros já poderão criar contas pockets e disponibilizá-las a seus clientes.

O número da conta pocket será composto pelo número da conta de pagamento + número aleatório de até 13 dígitos + código referente à moeda.

Exemplo: se o número da conta de pagamento for 123456, então, o número da pocket poderá ser 123456 + 82 + BRL, resultando em: 12345682BRL.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que o parceiro:

Possua uma conta de pagamento ativa no Bankly;
Defina a quantidade de contas pockets que serão necessárias a seu negócio.

🚧
Importante
Recordamos que a quantidade de pockets a serem criadas é especificada pelo parceiro junto ao time Bankly. Entre em contato com o responsável pela sua conta para realizar o ajuste.

Requisição

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/accounts/{accountNumber}/pockets

curl --request POST \
     --url 'https://api-mtls.sandbox.bankly.com.br/accounts/15164/pockets' \
     --header 'accept: application/json' \
     --header 'api-version: 2' \
     --header 'authorization: Bearer' \
     --header 'content-type: application/json' \
     --header 'idempotency-key: f5ff2ba3-76c0-4aa0-8015-a93b62a6c100' \
     --data ' {
    "data": {
         "user": {
              "document": {
                   "value": "47742663023",
                   "type": "CPF"
              },
              "name": "Nísia Floresta",
              "birthDate": "1810-10-12"
         },
         "currency": "BRL",
         "label": "Viagem",
         "useCase": "CORPORATE_EXPENSES"
    },
   "metadata": {}
}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`pocket.create`	Concede acesso para a criação de contas pockets.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. A versão desta API é a 2.0.
`authorization`	Obrigatório. Token de autorização do tipo Bearer.
`idempotency-key`	Obrigatório. Informe um GUID v4, sendo um novo a cada requisição. Importante: O tempo para a expiração do `Idempotency-Key` é de 6 minutos.

Parâmetros da rota (Path)

No path desta requisição, envie o seguinte campo:

Nome	Tipo	Descrição
`accountNumber`	`path`	Obrigatório. Número da conta com o dígito, a partir da qual a pocket será criada.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`data`	`object`	Obrigatório. Objeto que contém os dados da conta pocket criada.
`data.user`	`objetc`	Obrigatório. Objeto que contém os dados do usuário da conta pocket.
`data.user.name`	`string`	Obrigatório. Nome do usuário.
`data.user.document`	`object`	Obrigatório. Objeto que contém os dados do documento do usuário.
`data.user.document.value`	`string`	Obrigatório. Número do documento.
`data.user.document.type`	`string`	Obrigatório. Tipo do documento (CPF ou CNPJ).
`data.user.birthDate`	`string`	Obrigatório. Data de nascimento do usuário, no formato ISO 8601 - UTC.
`data.currency`	`string`	Obrigatório. Sigla da moeda utilizada, de acordo com a ISO 4217.
`data.label`	`string`	Obrigatório. Campo destinado ao nome da conta pocket criada.
`data.useCase`	`enum`	Obrigatório. Especificação da finalidade da pocket. As possibilidades de preenchimento são: “CORPORATE_EXPENSES” (despesas corporativas), “ACCOUNT_FOR_UNDER_AGE” (conta para menor de idade), “FLEXIBLE_BENEFITS” (benefícios diversos) e “BALANCE_SEGREGATION” (saldo reservado).


{
    "data": {
         "user": {
              "document": {
                   "value": "47742663023",
                   "type": "CPF"
              },
              "name": "Nísia Floresta",
              "birthDate": "1810-10-12"
         },
         "currency": "BRL",
         "label": "Viagem",
         "useCase": "CORPORATE_EXPENSES"
    },
   "metadata": {}

}

📘
Nota
O objeto metadata é um dicionário de metadados que possibilita o envio de dados adicionais na requisição. O uso desse campo é opcional.

Resposta (Response)

O status code 201 indicará que a pocket foi criada com sucesso.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`data`	`object`	Objeto que contém informações sobre a conta pocket criada.
`data.number`	`string`	Número da conta pocket.
`data.label`	`string`	Nome descritivo da conta pocket.
`data.suffix`	`string`	Sufixo atribuído ao número da pocket. Exemplo: BRL.
`data.currency`	`string`	Sigla da moeda corrente da pocket.
`data.type`	`string`	Tipo da conta com a sigla da moeda. Exemplo: POCKET_BRL.
`data.status`	`string`	Situação da conta pocket.
`data.reason`	`string`	Motivo da situação da conta pocket. Nesse caso, sempre será HOLDER_REQUEST.
`data.category`	`string`	Categoria da conta.
`data.useCase`	`string`	Motivo de uso da conta pocket, que pode ser: “ACCOUNT_FOR_UNDER_AGE” (Conta para menor de idade), “CORPORATE_EXPENSES” (Despesas corporativas), “FLEXIBLE_BENEFITS” (Benefícios flexíveis) e “BALANCE_SEGREGATION” (Segregação de saldo).
`data.createdAt`	`string`	Data de criação da conta pocket, no formato ISO 8601 - UTC.
`data.user`	`object`	Objeto que contém os dados do usuário da conta pocket.
`data.user.name`	`string`	Nome do usuário.
`data.user.document`	`object`	Objeto que contém os dados do documento do usuário da conta pocket.
`data.user.document.value`	`string`	Número do documento.
`data.user.document.type`	`string`	Tipo de documento (CPF ou CNPJ).
`data.user.birthDate`	`string`	Data de nascimento do usuário.
`data.account`	`object`	Objeto que contém os dados da conta de pagamento à qual a pocket está atrelada.
`data.account.branch`	`string`	Número da agência da conta de pagamento à qual a conta pocket está atrelada.
`data.account.number`	`string`	Número da conta de pagamento.
`data.account.status`	`string`	Situação da conta de pagamento que, nesse caso, será “ACTIVE”.
`data.account.reason`	`string`	Motivo da situação da conta de pagamento.
`data.account.createdAt`	`string`	Data de criação da conta de pagamento, no formato ISO 8601 - UTC.
`data.account.bank`	`object`	Objeto que contém os dados do banco da conta de pagamento.
`data.account.bank.ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.account.bank.code`	`string`	Código do banco.
`data.account.bank.name`	`string`	Nome do banco.
`data.account.holder`	`object`	Objeto que contém informações sobre o titular da conta de pagamento.
`data.account.holder.document`	`object`	Objeto que contém dados do documento do titular da conta de pagamento.
`data.account.holder.document.value`	`string`	Número do documento.
`data.account.holder.document.type`	`string`	Tipo de documento (CPF ou CNPJ).
`data.account.holder.type`	`string`	Tipo do cadastro do titular da conta de pagamento (“CUSTOMER” ou “BUSINESS”).
`data.account.holder.name`	`string`	Nome do titular da conta de pagamento.
`data.account.holder.status`	`string`	Situação do cadastro do titular.
`data.account.holder.createdAt`	`string`	Data de criação do cadastro do titular no formato ISO 8601 - UTC.
`links[]`	`array of objects`	Links de próximos estados válidos da entidade/recurso.
`links[].url`	`string`	URLs que podem ser utilizadas em um próximo estado da entidade.
`links[].rel`	`string`	Descrição de como a URL se relaciona com o recurso atual.
`links[].method`	`string`	Tipo de verbo que deve ser utilizado para acessar a URL.
`metadata`	`dictionary<string, object>`	Metadados da requisição.

{
    "data": {
        "number": "1516482BRL",
        "label": "BRL",
        "suffix": "BRL",
        "currency": "BRL",
        "type": "POCKET_BRL",
        "status": "ACTIVE",
        "reason": "HOLDER_REQUEST",
        "category": "POCKET",
        "useCase": "CORPORATE_EXPENSES",
        "createdAt": "2022-11-16T20:07:45.6277967Z",
        "user": {
            "name": "Nísia Floresta",
            "document": {
                "value": "47742663023",
                "type": "CPF"
            },
            "birthDate": "1810-10-12T00:00:00Z"
        },
        "account": {
            "branch": "15164",
            "number": "0001",
            "status": "ACTIVE",
            "reason": "HOLDER_REQUEST",
            "createdAt": "2022-10-07T02:08:41.0307Z",
            "bank": {
                "ispb": "13140088",
                "code": "332",
                "name": "Acesso Soluções De Pagamento S.A."
            },
            "holder": {
                "document": {
                    "value":"47742663023",
                    "type": "CPF"
                },
                "type": "CUSTOMER",
                "name": "Nísia Floresta",
                "status": "ACTIVE",
                "createdAt": "2022-10-07T01:59:10.2588Z"
            }
        }
    },
    "links": [
        {
            "url": "/pockets/319597131BRL",
            "rel": "get_pocket",
            "method": "GET"
        },
        {
            "url": "/pockets/319597131BRL/balances",
            "rel": "get_pocket_balances",
            "method": "GET"
        },
        {
            "url": "/pockets/319597131BRL/transactions/savings",
            "rel": "create_pocket_transaction_savings",
            "method": "POST"
        },
        {
            "url": "/pockets/319597131BRL/closure",
            "rel": "close_pocket",
            "method": "PATCH"
        }
    ],
    "metadata": {}
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
422	MAXIMUM_POCKETS_COUNT_REGISTERED_FOR_ACCOUNT	Account has reached the maximum pocket counts.	A quantidade limite de pockets foi excedida para essa conta.
422	PRODUCT_NOT_ELIGIBLE_FOR_THIS_COMPANY_ACCOUNT_PROGRAM	Product not eligible for company accounts program under this company key {companyKey}. Request the product setting to you account manager.	Configuração não encontrada no programa de contas definido pela equipe Bankly.
422	INVALID_USER_BIRTHDATE_FOR_USE_CASE	The birthdate of the user {birthdate} is invalid to use case {useCase}.	A data de nascimento do usuário é inválida para o caso de uso.
422	INVALID_USER_BIRTHDATE_FOR_ACCOUNT_FOR_UNDER_AGE_USE_CASE	The use case ACCOUNT_FOR_UNDER_AGE is only for user between 16 and 18 years old.	O caso de uso "ACCOUNT_FOR_UNDER_AGE_USE_CASE" só é permitido para usuário entre 16 e 18 anos.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Nesse caso, o evento é:

Nome do evento	Descrição
`POCKET_ACCOUNT_WAS_CREATED`	Comunica a criação da conta pocket.

Criação de conta pocket

Pré-requisitos

🚧
Importante

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

📘
Nota

Resposta (Response)

👍
Dica

Erros

Eventos

Pré-requisitos

🚧Importante

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

📘Nota

Resposta (Response)

👍Dica

Erros

Eventos

🚧
Importante

📘
Nota

👍
Dica