Ledger

Conceitos importantes sobre o módulo de Ledger.

Ativo

Um Ativo representa valores físicos ou digitais que podem ser transferidos entre pessoas ou empresas. Alguns exemplos:

  • Moedas fiduciárias (BRL, USD)

  • Moedas digitais (security tokens)

  • Pontos de um programa de fidelidade

  • Milhas

  • Títulos financeiros (ações, debêntures)

  • Commodities

  • Criptomoedas

Conta

Uma Conta possui saldos de um ou mais Ativos. Ela é representada por um identificador único, pode ter Contas filhas e pode, ou não, ter um par de Credenciais que garante todo o acesso via API.

Na maioria das aplicações, Contas costumam representar os usuários ou empresas clientes da aplicação.

Abaixo dois exemplos de scenarios possíveis no momento da criação das contas:

Cenario 1: Emissor e Contas Filhas

Exemplo de Conta Emissora com 3 clientes

Nesse cenario temos um emissor (instituição cliente da Swipe) que pode criar contas pros seus próprios clientes.

Cenario 2: Emissor, Intermediário e Contas Filhas

Exemplo de Conta Emissora com 2 Intermediários e 4 clientes finais

Nesse cenário temos um emissor (instituição cliente da Swipe) que pode criar contas de intermediários (PSPs, Gateways, Escrows, etc) e tanto o emissor quanto os intermediários podem criar contas filhas pros seus clientes.

Credenciais

A única forma de acessar programaticamente a nossa API é através de seu par de Credenciais. O par é composto de uma Chave de API (apiKey) e um Segredo (secret). Confira a seção de integração para detalhes técnicos

Suas Credenciais não devem ser compartilhadas ou expostas indevidamente! Qualquer um que tenha acesso à elas poderá realizar Ações em seu nome. A seção de Segurança recomenda boas práticas e dicas importantes.

Ação

Ações são a única maneira de modificar informações no Ledger. Existem quatro tipos de Ações:

  • Criar nova Conta

  • Destruir uma Conta

  • Emitir um Ativo

  • Transferir Ativos

Criar nova Conta filha

Cria uma nova Conta filha.

Destruir uma Conta

Remove uma Conta, inutilizando seu ID. Contas destruídas não podem ser recuperadas.

Emitir um Ativo

Cria um novo Ativo que automaticamente pode ser transferido entre todas suas Contas.

Transferir Ativos

Executa uma transferência de um Ativo entre duas de suas Contas. Se for transferido um Ativo que o destinatário ainda não possui, ele passará a suportá-lo automaticamente.

Lote de Ações

Todas as Ações são enviadas e processadas em lote, de modo que todas elas sejam processadas ao mesmo tempo. Assim, se alguma falhar por algum motivo, todas as outras também falharão.

O caso de uso mais utilizado é para split de pagamentos, em que é necessário que seja atômico para evitar problemas relacionados à inconsistência de saldos.

Um lote pode incluir mais de um tipo de Ação simultaneamente.

Fields

Algumas das entidades apresentadas possuem um campo chamado fields para armazenar informações no formato chave-valor. São elas:

  • Conta

  • Lote de Ações

  • Ativo

Dessa forma, é possível agregar informações relacionadas a Contas , como documentos ou dados pessoais; Transferências, como recibos ou identificadores externos; e Ativos, como tipo fiduciário ou ponto de milhagem.

Triggers

Pode ser utilizado para criar alguns fluxos automatizados. Um Trigger é composto de uma condition e um type, isto é, sempre que aquela condition ocorrer, execute este Trigger .

Atualmente, são suportados as seguintes conditions:

  • Ledger_Transfer : Uma Transferência foi realizada para sua Conta ou uma Conta filha.

E os seguintes types:

  • WebHook: Ser notificado em uma url.

É possível criar qualquer combinação de condition e type. Dessa forma, pode-se criar uma automatização para ser notificado de uma Transferência para sua Conta ou uma Conta filha.