Abertura de conta

beta

Este endpoint possibilita que parceiro solicite a criação de uma conta de pagamentos ou conta corrente.

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/customers/{{documentNumber}}/accounts

--location --request POST 'https://api-mtls.sandbox.bankly.com.br/customers/{{documentNumber}}/accounts' \
--header 'api-version: 1' \
--header 'Authorization: Bearer {{Token}}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key : {{uuid v4}}' \
--header 'x-bkly-license: 24ac71da-4309-4348-9cc0-a0c88f867993' \
--data-raw '{
	"programId": "2e8ce49c-4c56-4ef3-9ed4-3272b0c675e2",
	"branch": "2020"
}'

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

Cabeçalhos (Headers)

Nome	Descrição	Especificação
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.	—
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.	—
`Idempotency-Key`	Chave de idempotência cuja finalidade é garantir que uma operação seja executada uma única vez. Importante: o tempo para a expiração do `Idempotency-Key` é de 6 minutos.	Formato UUID v4. Informe um UUID novo a cada requisição
`x-bkly-license`	Obrigatório. Id da licença bancária vinculada ao produto.	—

🚧
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:

Nome	Tipo	Descrição	Especificação
`documentNumber`	`path`	Obrigatório. Número do documento CPF do cliente.	Informe somente números.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`accountType`	`string`	Tipo de conta. Obsoleto.
`programId`	`string`	Obrigatório. Identificador do programa de contas que determina o tipo de conta a ser aberto. Para obtê-lo, entre em contato com a equipe Bankly.
`branch`	`string`	Agência válida associada ao programa de contas. Caso esse valor não seja informado, será considerado o primeiro valor do programa de contas.

{
	"programId": "2e8ce49c-4c56-4ef3-9ed4-3272b0c675e2",
	"branch": "2020"
}

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:

Nome	Tipo	Descrição
`balance`	`object`	Objeto que contém os dados do saldo da conta.
`balance.inProcess`	`object`	Objeto que contém informações sobre saldo em processamento.
`balance.inProcess.amount`	`number`	Valor do saldo em processamento.
`balance.inProcess.currency`	`string`	Sigla da moeda do saldo, de acordo com a ISO 4217. Exemplos: “BRL”.
`balance.available`	`object`	Objeto que contém informações sobre saldo disponível na conta.
`balance.available.amount`	`number`	Valor do saldo disponível.
`balance.available.currency`	`string`	Sigla da moeda do saldo, de acordo com a ISO 4217. Exemplos: “BRL”.
`balance.blocked`	`object`	Objeto que contém informações sobre saldo bloqueado na conta.
`balance.blocked.amount`	`number`	Valor do saldo bloqueado.
`balance.blocked.currency`	`string`	Sigla da moeda do saldo, de acordo com a ISO 4217. Exemplos: “BRL”.
`status`	`string`	Situação da conta, que pode ser active ou closed.
`branch`	`string`	Agência associada à conta consultada.
`number`	`string`	Número da conta consultada.
`type`	`string`	Tipo de conta, que pode ser checking (corrente) ou payment (pagamento).
`bank`	`object`	Objeto que contém os dados bancários da conta.
`bank.ispb`	`string`	ISPB do banco.
`bank.code`	`string`	Código do banco.
`bank.name`	`string`	Nome do banco.
`programId`	`string`	Identificador do programa de contas que determina o tipo de conta.

{
    "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",
    "type": "Checking",
    "bank": {
        "ispb": "01858774",
        "code": "413",
        "name": "BCO BV S.A."
    },
    "programId": "d83c37b2-fb71-477c-b689-8ec95ab810c8"
}

Erros

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

Status code	Código	Mensagem	Descrição
422	HOLDER_ALREADY_HAVE_A_ACCOUNT	It's not possible to create more than one account per holder.	Não é possível criar mais de uma conta por documento.
422	ACCOUNT_HOLDER_NOT_EXISTS	Account 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.
422	PROGRAM_ID_NOT_ACTIVE	Program ID not active.	O `programId` não está ativo.
422	PRODUCT_NOT_ELEGIBLE_FOR_HOLDER_ACCOUNT	Product not eligible for holder account.	O `programId` não está associado a ao titular dessa conta.
422	PRODUCT_NOT_ELIGIBLE_FOR_COMPANY_ACCOUNT_PROGRAM	Product not eligible for company account program.	O `programId` não está disponível para essa `companyKey`.
422	BRANCH_NOT_LINKED_TO_PROGRAM	Branch 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 evento	Descrição
`ACCOUNT_WAS_CREATED`	A conta foi criada.
`ACCOUNT_WAS_CLOSED`	A conta foi encerrada tecnicamente.
`ACCOUNT_WAS_LEGALLY_CLOSED`	A conta foi encerrada legalmente. Neste caso, o Banco central foi informado do encerramento.