Abertura de conta

stable

Este endpoint possibilita que parceiro solicite a criação de uma conta de pagamentos ou conta corrente para um cliente pessoa jurídica.

Depois que a conta é criada, o cliente passa a ser reconhecido no sistema financeiro como um titular de uma conta (de pagamentos ou corrente) e poderá realizar operações, como transações via Pix, TED, emissão de boletos, depósitos via boletos, pagamento de contas (boletos e convênios), dentre outras operações financeiras.

Adicionalmente o cliente poderá ter um cartão de crédito pré-pago vinculado à sua conta.

Pré-requisito

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

  • O cliente tenha tido seu cadastro aprovado.

Requisição

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/business/{{documentNumber}}/accounts
--location --request POST 'https://api-mtls.sandbox.bankly.com.br/customers/{{documentNumber}}/accounts' \
--header 'api-version: 1.0' \
--header 'Authorization: Bearer {{Token}}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key : {{uuid v4}}' \
--data-raw '{
	"accountType": "PAYMENT_ACCOUNT 
}'

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
account.createConcede acesso para criar uma conta de pagamento.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
Idempotency-KeyInforme um UUID, sendo um novo a cada requisição. Importante: O tempo para a expiração do Idempotency-Key é de 6 minutos.

🚧

Importante

Caso o cliente possua multicontas ativas, o parceiro deverá utilizar o cabeçalho Idempotency-Key nas requisições, a fim de evitar a criação de contas duplicadas.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

NomeTipoDescrição
documentNumberpathObrigatório. Número do documento CNPJ da empresa. Informe somente os números.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

NomeTipoDescrição
accountTypestringTipo de conta, neste caso "PAYMENT_ACCOUNT".
{
	"accountType": "PAYMENT_ACCOUNT"
}

Resposta (Response)

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

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

NomeTipoDescrição
balanceobjectObjeto que contém os dados do saldo da conta.
balance.inProcessobjectObjeto que contém informações sobre saldo em processamento.
balance.inProcess.amountnumberValor do saldo em processamento.
balance.inProcess.currencystringSigla da moeda do saldo, de acordo com a ISO 4217. Exemplos: “BRL”.
balance.availableobjectObjeto que contém informações sobre saldo disponível na conta.
balance.available.amountnumberValor do saldo disponível.
balance.available.currencystringSigla da moeda do saldo, de acordo com a ISO 4217. Exemplos: “BRL”.
balance.blockedobjectObjeto que contém informações sobre saldo bloqueado na conta.
balance.blocked.amountnumberValor do saldo bloqueado.
balance.blocked.currencystringSigla da moeda do saldo, de acordo com a ISO 4217. Exemplos: “BRL”.
statusstringSituação da conta, que pode ser active ou closed.
branchstringAgência associada à conta consultada.
numberstringNúmero da conta consultada.
{
    "balance": {
        "inProcess": {
            "amount": 0.0,
            "currency": "BRL"
        },
        "available": {
            "amount": 0.0,
            "currency": "BRL"
        },
        "blocked": {
            "amount": 0.0,
            "currency": "BRL"
        }
    },
    "status": "ACTIVE",
    "branch": "2020",
    "number": "502000027888"
}

Erros

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

Status codeCódigoDescrição
422HOLDER_ALREADY_HAVE_A_ACCOUNTNão é possível criar mais de uma conta por documento.
422ACCOUNT_HOLDER_NOT_EXISTSConta não existente ou o registro do cliente ainda não foi aprovado.
422PROGRAM_ID_NOT_ACTIVEO programId não está ativo.
422PRODUCT_NOT_ELEGIBLE_FOR_HOLDER_ACCOUNTO programId não está associado a ao titular dessa conta.
422PRODUCT_NOT_ELIGIBLE_FOR_COMPANY_ACCOUNT_PROGRAMO programId não está disponível para essa companyKey.
422BRANCH_NOT_LINKED_TO_PROGRAMAgência não associada ao programa de contas.

Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do eventoDescrição
ACCOUNT_WAS_CREATEDA conta foi criada.