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 (Request)

Requisição HTTP

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

--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 deverá conter informações sobre a conta pocket criada.
`data.user`	`objetc`	Obrigatório. Objeto que deverá conter informações sobre o usuário da conta pocket.
`data.user.name`	`string`	Obrigatório. Nome do usuário.
`data.user.document`	`object`	Obrigatório. Objeto que deverá conter informações sobre o 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. Código da moeda com base na 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), “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`	Código da moeda corrente da pocket.
`data.type`	`string`	Tipo da conta com o código 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 “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 informações sobre o usuário da conta pocket.
`data.user.name`	`string`	Nome do usuário.
`data.user.document`	`object`	Objeto que contém informações sobre o 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 informações sobre a 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 informações sobre o banco ao qual a conta pertence.
`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 informações sobre o 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, que pode ser “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.

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 (Request)

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 (Request)

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