Conceitos

Nesta página iremos dar mais detalhes sobre os principais conceitos da API (account, transaction, etc.).

Account

Estrutura básica de uma account:

{
  "id": "integer",
  "name": "string",
  "email": "string",
  "mobile_number": "string",
  "date_of_birth": "string",
  "document": "string",
  "document_type": "string",
  "created_at": "string",
  "updated_at": "string"
}

Por padrão, toda account é criada R$0,00 de limite de movimentação mensal e diária. Para editar esse limite devem ser usadas as rotas de limite disponível em nossa documentação. Sendo possível configurar os limites de movimentação para cada usuário, por operação e intervalo de tempo (chegando na granularidade da hora).

Atualmente damos suporte para contas PF e PJ, essa distinção é feita pelo document_type, podendo ser cpf ou cnpj.

Os campos name, email e document são obrigatórios, sendo os dois últimos únicos por conta.

Transaction

Estrutura básica de uma transaction:

{
  "id": "integer",
  "account_id": "integer",
  "wallet_slug": "string",
  "value": "integer",
  "side": "string",
  "status": "string",
  "category": "string",
  "created_at": "string",
  "updated_at": "string",
  "payment_method": "string",
  "description": "string",
  "operation_id": "string",
  "custom_id": "string",
  "uuid": "string",
  "metadata": {
    ...
  }
}

O value é medido em centavos de real, por exemplo: o valor 300 equivale a R$3,00.

O campo side indica se a transaction é de cash-in ou cash-out, podendo assumir os valores credit (cash-in) ou debit (cash-out).

O campo status indica a situação da transação, podendo ser:

• approved (operação aprovada)
• pending (operação aguardando definição)
• denied (operação negada).

O campo payment_method indica o método de pagamento utilizado para realizar a transação. Os valores possíveis são:

• CONTA: valor saiu ou entrou de uma conta da aplicação
• BOLETO: valor entrou na conta por um boleto
• PREPAID_CARD: valor saiu ou entrou por um cartão pré-pago
• CREDIT_CARD: valor foi pago utilizando um cartão de crédito
• TED: valor foi pago ou recebido via TED
• PIX: valor foi pago ou recebido via Pix

O campo category indica o tipo de transaction que foi feita, cada categoria está atrelada a um ou mais possíveis métodos de pagamento. São elas:

• BILL_PAYMENT: um pagamento de contas (método: CONTA)
• RECEIVAL: um recebimento de fora da aplicação (método: TED ou PIX)
• EXTERNAL_TRANSFER: uma transferência externa (método: TED ou PIX)
• SENDBACK: uma devolução Pix iniciada pelo usuário (método: PIX)
• FEE: uma taxa devido a uma transaction (por exemplo a taxa de uma TED) (método: CONTA)
• INTERNAL_TRANSFER: uma transferência interna entre contas da sua aplicação (método: CONTA)
• RECHARGE: uma recarga na conta via Boleto (método: BOLETO)
• WALLET_TRANSFER: uma transferência entre duas wallets de uma account (método: CONTA)
• EXTERNAL_PURCHASE: uma compra realizada externa a aplicação (tipicamente uma compra com cartão pré-pago) (método: PREPAID_CARD)
• EXTERNAL_PURCHASE_CANCEL: um cancelamento de uma EXTERNAL_PURCHASE (quando a compra no cartão é cancelada antes de ser liquidada) (método: PREPAID_CARD)
• EXTERNAL_CHARGEBACK: um recebimento de estorno/devolução que foi emitido externo a aplicação (quando uma compra de cartão é estornada ou um pix devolvido) (método: PREPAID_CARD ou PIX)\

O campo metadata representa algumas informações que são sensíveis ao tipo da transação, nele são disponibilizadas informações adicionais como as indicadas abaixo:

• RECHARGE (BOLETO):
  JSON

  {
    "fee": "integer",
    "writable_line": "string",
    "barcode_number": "string",
    "due_date": "string"
  }

   
• BILL_PAYMENT:
  JSON

  {
    "fine_value": "integer",
    "interest_value": "integer",
    "discount_value": "integer",
    "original_value": "integer",
    "due_date": "string",
    "schedule_to": "string",
    "writable_line": "string",
    "bill_type": "string"
  }

   
• RECEIVAL (PIX):
  JSON

  {
    "bank_code": "string",
    "agency_number": "string",
    "number": "string",
    "charge_id": "integer",
    "holder": {
      "name": "string",
      "document_type": "string",
      "document": "string"
    },
    "bank_ispb": "string",
    "pix_key": "string",
    "end_to_end_id": "string",
    "identification": "string"
  }

   
• EXTERNAL_TRANSFER (PIX):
  JSON

  {
    "bank_code": "string",
    "agency_number": "string",
    "number": "string",
    "holder": {
      "name": "string",
      "document_type": "string",
      "document": "string"
    },
    "bank_ispb": "string",
    "pix_key": "string",
    "initiation_method": "string",
    "end_to_end_id": "string",
    "identification": "string"
  }

   
• SENDBACK (PIX):
  JSON

  {
    "end_to_end_id": "string",
    "original_transaction_id": "integer"
  }

   
• EXTERNAL_CHARGEBACK (PIX):
  JSON

  {
    "original_transaction_id": "integer"
  }

   
• EXTERNAL_TRANSFER (TED):
  JSON

  {
    "bank_code": "string",
    "agency_number": "string",
    "number": "string",
    "holder": {
      "name": "string",
      "document_type": "string",
      "document": "string"
    }
  }

   
• INTERNAL_TRANSFER:
  JSON

  {
    "credit": {
      "account_id": "string",
      "account_name": "string",
      "wallet_slug": "string"
    },
    "debit": {
      "account_id": "string",
      "account_name": "string",
      "wallet_slug": "string"
    }
  }

   
• EXTERNAL_PURCHASE (PREPAID_CARD):
  JSON

  {
    "prepaid_card_id": "integer",
    "establishment": {
      "name": "string",
      "mcc": "string",
      "city": "string"
    }
  }

   
• EXTERNAL_PURCHASE_CANCEL (PREPAID_CARD):
  JSON

  {
    "prepaid_card_id": "integer",
    "original_transaction_id": "integer"
  }

   
• EXTERNAL_CHARGEBACK (PREPAID_CARD):
  JSON

  {
    "prepaid_card_id": "integer",
    "original_transaction_id": "integer"
  }