Criação de conta pocket

stable

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:

ScopeDescrição
pocket.createConcede acesso para a criação de contas pockets.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. A versão desta API é a 2.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
idempotency-keyObrigató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:

NomeTipoDescrição
accountNumberpathObrigató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:

NomeTipoDescrição
dataobjectObrigatório. Objeto que deverá conter informações sobre a conta pocket criada.
data.userobjetcObrigatório. Objeto que deverá conter informações sobre o usuário da conta pocket.
data.user.namestringObrigatório. Nome do usuário.
data.user.documentobjectObrigatório. Objeto que deverá conter informações sobre o documento do usuário.
data.user.document.valuestringObrigatório. Número do documento.
data.user.document.typestringObrigatório. Tipo do documento (CPF ou CNPJ).
data.user.birthDatestringObrigatório. Data de nascimento do usuário, no formato ISO 8601 - UTC.
data.currencystringObrigatório. Código da moeda com base na ISO-4217.
data.labelstringObrigatório. Campo destinado ao nome da conta pocket criada.
data.useCaseenumObrigató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:

NomeTipoDescrição
dataobjectObjeto que contém informações sobre a conta pocket criada.
data.numberstringNúmero da conta pocket.
data.labelstringNome descritivo da conta pocket.
data.suffixstringSufixo atribuído ao número da pocket. Exemplo: BRL.
data.currencystringCódigo da moeda corrente da pocket.
data.typestringTipo da conta com o código da moeda. Exemplo: POCKET_BRL.
data.statusstringSituação da conta pocket.
data.reasonstringMotivo da situação da conta pocket. Nesse caso, sempre será HOLDER_REQUEST.
data.categorystringCategoria da conta.
data.useCasestringMotivo 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.createdAtstringData de criação da conta pocket, no formato ISO 8601 - UTC.
data.userobjectObjeto que contém informações sobre o usuário da conta pocket.
data.user.namestringNome do usuário.
data.user.documentobjectObjeto que contém informações sobre o documento do usuário da conta pocket.
data.user.document.valuestringNúmero do documento.
data.user.document.typestringTipo de documento (CPF ou CNPJ).
data.user.birthDatestringData de nascimento do usuário.
data.accountobjectObjeto que contém informações sobre a conta de pagamento à qual a pocket está atrelada.
data.account.branchstringNúmero da agência da conta de pagamento à qual a conta pocket está atrelada.
data.account.numberstringNúmero da conta de pagamento.
data.account.statusstringSituação da conta de pagamento que, nesse caso, será “ACTIVE”.
data.account.reasonstringMotivo da situação da conta de pagamento.
data.account.createdAtstringData de criação da conta de pagamento, no formato ISO 8601 - UTC.
data.account.bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
data.account.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.account.bank.codestringCódigo do banco.
data.account.bank.namestringNome do banco.
data.account.holderobjectObjeto que contém informações sobre o titular da conta de pagamento.
data.account.holder.documentobjectObjeto que contém informações sobre o documento do titular da conta de pagamento.
data.account.holder.document.valuestringNúmero do documento.
data.account.holder.document.typestringTipo de documento (CPF ou CNPJ).
data.account.holder.typestringTipo do cadastro do titular da conta de pagamento, que pode ser “CUSTOMER” ou “BUSINESS”.
data.account.holder.namestringNome do titular da conta de pagamento.
data.account.holder.statusstringSituação do cadastro do titular.
data.account.holder.createdAtstringData de criação do cadastro do titular, no formato ISO 8601 - UTC.
links[]array of objectsLinks de próximos estados válidos da entidade/recurso.
links[].urlstringURLs que podem ser utilizadas em um próximo estado da entidade.
links[].relstringDescrição de como a URL se relaciona com o recurso atual.
links[].methodstringTipo de verbo que deve ser utilizado para acessar a URL.
metadatadictionary<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 CodeCódigoMensagemDescrição
422MAXIMUM_POCKETS_COUNT_REGISTERED_FOR_ACCOUNTAccount has reached the maximum pocket counts.A quantidade limite de pockets foi excedida para essa conta.
422PRODUCT_NOT_ELIGIBLE_FOR_THIS_COMPANY_ACCOUNT_PROGRAMProduct 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 eventoDescrição
POCKET_ACCOUNT_WAS_CREATEDComunica a criação da conta pocket.