Transações com cartões

Os eventos de transações com cartão disparam mensagens que comunicam ao destinatário informações sobre movimentações com o cartão.
Como esses eventos chegam ao recebedor via webhook, é preciso realizar previamente a sua configuração.

Contexto e nome do evento

Nos eventos de faturas de cartão, o campo context sempre informará “Invoice”, enquanto o campo name poderá variar de acordo com a transação, conforme a tabela a seguir:

EntityId

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.

No caso de transações com o cartão, o entityId representa o identificador único do item de fatura (statementItemId).

Exemplo de evento

{
  "name": "TRANSACTION_CREATED",
  "entityId": "12345",
  "idempotencyKey": "7581c878-5546-4eaa-8a93-340c1f3e820c",
  "companyKey": "COMPANY_KEY",
  "timestamp": "2022-04-25T11:39:27.7528839Z",
  "correlationId": "825b3f03-8376-4ooc-af2c-8dcc94e5e133",
  "version": 1,
  "metadata": {
    "Created": "2022-04-24T22:37:09Z"
  },
  "context": "Invoice",
  "data": {
    "statement": {
      "id": 56922,
      "dueDate": "2022-08-01T00:00:00"
    },
    "isCredit": false,
    "statementPost": true,
    "statementNumber": 3,
    "statementTotal": 3,
    "transactionDate": "2022-04-24T22:37:09Z",
    "transactionTypeId": 0,
    "transactionType": "INSTALLMENT_WITHOUT_INTEREST",
    "transactionDescription": "DROGARIA",
    "exchangeFee": {
      "value": 0.0,
      "currency": "BRL"
    },
    "amounts": [
      {
        "value": 67.95,
        "currency": "BRL",
        "amountType": "Billed"
      },
      {
        "value": 203.86,
        "currency": "BRL",
        "amountType": "Local"
      },
      {
        "value": 67.96,
        "currency": "BRL",
        "amountType": "Exchange"
      }
    ],
    "fees": [
      
    ],
    "transaction": {
      "card": {
        "proxy": "0000000000000000000",
        "lastFourDigits": "0000",
        "cardName": "vpos Teste",
        "cardType": "Virtual",
        "alias": "Card Virtual Pos"
      },
      "transactionAuthorizerId": "12345678",
      "auhtorizationCode": "LVSF1W",
      "nsu": "248882",
      "mcg": "Care",
      "merchant": "DROGARIA",
      "mcc": "5912",
      "entrymode": "810"
    },
    "documentNumber": {
      "value": "000000",
      "type": "CPF"
    }
  }
}

🚧

Importante

Para conhecer a estrutura básica dos eventos com os campos que chegarão à sua API, consulte nossa documentação específica de Eventos.

Objeto data no evento de transação com cartão

O objeto data traz detalhes específicos do contexto em que o evento ocorre. No caso de eventos de transações com cartão, esse objeto irá variar de acordo com o evento, conforme explicitado a seguir:

• statement: objeto que contém os dados da fatura:
  • id: identificador único da fatura;
  • dueDate: data de vencimento da fatura.
• isCredit: indica se é uma operação de crédito (TRUE) ou débito (FALSE);
• statementPost: define se é um item exibido na fatura, sendo TRUE para exibido e FALSE para oculto;
• statementNumber: número da parcela;
• statementTotal: número total de parcelas;
• transactionDate: data em que ocorreu a transação;
• transactionType: tipo da transação. Consulte os possíveis valores deste campo na tabela exibida no final desta página;
• transactionDescription: descritivo do item da fatura;
• exchangefee: objeto que contém a taxa de conversão utilizada em transações internacionais:
  • value: valor da taxa;
  • currency: código da moeda com base na ISO-4217.
• amounts: lista de objeto que contém informações sobre o total da transação:
  • value: valor do item da fatura;
  • currency: código da moeda com base na ISO-4217;
  • amountType: indicador do tipo do item de fatura, o qual pode ser: “Billet” (valor cobrado, em real, ao cliente), “Exchange” (valor em dólar da transação no caso da compra ser internacional) e “Local” (valor da moeda local).
• fees: objeto que contém as taxas aplicadas na transação:
  • feeType: tipo da taxa, o qual pode ser: “NotMapper” (não informado), “IOF” (Imposto de Operações Financeiras fixo da transação), “Markup” (taxa de conversão para proteção de mudanças de câmbio), “DailyIOF” (IOF diário em cima da fatura) e “Interest” (juros de transação cobrado pelo emissor).
  • value: valor da taxa.
• transaction: objeto que contém dados relacionados a uma transação (compra ou saque):
  • card: objeto que contém os dados do cartão utilizado na transação:
    • proxy: identificador do cartão;
    • lastFourDigits: quatro últimos dígitos do cartão;
    • cardName: nome gravado no cartão;
    • cardType: tipo do cartão, o qual pode ser: “Physical” ou “Virtual”;
    • alias: apelido definido pelo proprietário do cartão.
  • transactionAuthorizerId: identificador da transação gerado pela processadora;
  • authorizationCode: identificador da transação na rede de cartões;
  • nsu: número sequencial único que é gerado na venda;
  • mcc: código MCC da transação;
  • mcg: descrição do tipo mcc;
  • merchant: informações referentes ao estabelecimento que aceitou a transação. Seus dados são baseados na ISO 8583;
  • entrymode: código que identifica o tipo da transação.

📘

Nota

O objeto transaction pode ser nulo caso o item não represente uma transação.

• documentNumber: objeto que contém informações sobre o documento do titular do cartão:
  • value: número do documento;
  • type: tipo de documento do titular, que pode ser “CPF” ou “CNPJ”.

Tipos de transações