InstitucionalBlogService DeskStatus Page

Abertura de conta

stable

Suggest Edits

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

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 registro aprovado.

🚧

Importante

A conclusão do registro é confirmada por meio do evento ACCOUNT_HOLDER_WAS_CREATED.

Requisição

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/customers/{{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 CPF do cliente. 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ódigoMensagemDescrição
422HOLDER_ALREADY_HAVE_A_ACCOUNTIt's not possible to create more than one account per holder.Não é possível criar mais de uma conta por documento.
422ACCOUNT_HOLDER_NOT_EXISTSAccount holder does not exist or does not have an approved registration yet.Conta não existente ou o registro do cliente ainda não foi aprovado.
422PROGRAM_ID_NOT_ACTIVEProgram ID not active.O programId não está ativo.
422PRODUCT_NOT_ELEGIBLE_FOR_HOLDER_ACCOUNTProduct not eligible for holder account.O programId não está associado a ao titular dessa conta.
422PRODUCT_NOT_ELIGIBLE_FOR_COMPANY_ACCOUNT_PROGRAMProduct not eligible for company account program.O programId não está disponível para essa companyKey.
422BRANCH_NOT_LINKED_TO_PROGRAMBranch not linked to program.Agência não associada ao programa de contas.

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. Os eventos são:

Nome do eventoDescrição
ACCOUNT_WAS_CREATEDA conta foi criada.

Updated about 1 month ago