Autorização

Contexto e nome do evento

Nos eventos de autorização, o campo context sempre informará “Authorization”, 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 contexto de autorização, o entityId é o authorizationTransactionId (identificador único da transação).

Exemplos de eventos

{
  "entityId": "d4d61574-8c8a-4ed9-b797-b2a17f92e3ef",
  "companyKey": "COMPANY_KEY",
  "name": "TRANSACTION_WAS_PROCESSED",
  "timestamp": "2022-04-25T12:14:43.5839658Z",
  "correlationId": "f5303972-4559-4f37-ad98-7972b104f1dd",
  "metadata": null,
  "data": {
    "account": {
      "branch": "0001",
      "number": "123456",
      "bank": {
        "ispb": "13140088",
        "code": "332",
        "name": "Acesso Soluções De Pagamento S.A."
      },
      "type": null,
      "status": null,
      "pockets": null,
      "label": null,
      "balance": null
    },
    "amount": {
      "value": 9.96,
      "currency": "BRL"
    },
    "withoutFeeAmount": {
      "value": 9.96,
      "currency": "BRL"
    },
    "iofAmount": null,
    "markupAmount": null,
    "withdrawalFeeAmount": null,
    "fees": null,
    "deniedRules": [
      
    ],
    "status": "SUCCESS",
    "transactionTimeStamp": "2022-04-25T09:14:39",
    "channel": {
      "settlement": {
        "value": 2.12,
        "currency": "USD"
      },
      "localAmount": {
        "value": 9.96,
        "currency": "BRL"
      },
      "entryMode": {
        "code": "07",
        "description": "PAN auto-entry via contactless M/Chip",
        "cardPresent": true
      },
      "authorizationCode": "LBJ5F3",
      "transactionType": {
        "code": "00",
        "description": "Purchase"
      },
      "wallet": {
        "code": "0",
        "name": "Unknown"
      },
      "retrievalReferenceNumber": "429866500009",
      "merchant": {
        "mcc": "5912",
        "mcg": "Care",
        "city": "MANAUS",
        "stateOrCountryCode": "BRA",
        "state": "",
        "name": "MERCADO",
        "zipCode": "",
        "terminalId": "",
        "acquirerCode": ""
      },
      "numberOfInstallments": 1,
      "authorizationId": 56161250,
      "name": "CARD_NETWORK"
    },
    "authorizationTransactionId": "d4d61574-8c8a-4ed9-b797-b2a17f92e3ef",
    "card": {
      "proxy": "0000000000000000000",
      "alias": "Card Physic Pos",
      "function": "Pos",
      "type": "Physical"
    }
  },
  "context": "Authorization",
  "idempotencyKey": "f5303972-4559-4f37-ad98-7972b104f1dd"
}

{
  "entityId": "8c25e204-5c92-4cc2-8a9f-f7b4a2ea1a40",
  "companyKey": "COMPANY_KEY",
  "name": "TRANSACTION_WAS_REVERTED",
  "timestamp": "2022-04-25T12:07:57.1779332Z",
  "correlationId": "23247612-9b04-4dd0-8764-31ed27ab5e40",
  "metadata": null,
  "data": {
    "amount": {
      "value": 7.93,
      "currency": "BRL"
    },
    "withoutFeeAmount": {
      "value": 7.93,
      "currency": "BRL"
    },
    "iofAmount": null,
    "markupAmount": null,
    "withdrawalFeeAmount": null,
    "dollarExchangeRate": null,
    "reversalReason": "PosRequest",
    "channel": {
      "settlement": {
        "value": 1.69,
        "currency": "USD"
      },
      "localAmount": {
        "value": 7.93,
        "currency": "BRL"
      },
      "name": "CARD_NETWORK"
    },
    "authorizationTransactionId": "8c25e204-5c92-4cc2-8a9f-f7b4a2ea1a40",
    "card": {
      "proxy": "0000000000000000000",
      "alias": "Alias Name",
      "function": "Pre",
      "type": null
    }
  },
  "context": "Authorization",
  "idempotencyKey": "23247612-9b04-4dd0-8764-31ed27ab5e40"
}

{
  "entityId": "a1349dde-817a-4913-91d0-84fa2d787755",
  "companyKey": "COMPANY_KEY",
  "name": "TRANSACTION_WAS_EXPIRED",
  "timestamp": "2022-04-25T12:00:02.2180183Z",
  "correlationId": "9b76feea-98a0-4001-b2bf-ab83ae57adce",
  "metadata": null,
  "data": {
    "authorizationTransactionId": "a1349dde-817a-4913-91d0-84fa2d787755",
    "card": {
      "proxy": "0000000000000000000",
      "alias": "0921",
      "function": "Pre",
      "type": null
    }
  },
  "context": "Authorization",
  "idempotencyKey": "9b76feea-98a0-4001-b2bf-ab83ae57adce"
}

🚧

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 nos eventos de autorização

O objeto data traz detalhes específicos do evento transmitido. No caso de eventos de autorização, esse objeto poderá conter os seguintes campos:

• account: os dados da conta do pagador;
  • label: nome dado à conta no momento de sua configuração;
  • branch: número da agência;
  • bank: objeto contendo o ISPB, o código e o nome do banco a qual a conta pertence;
  • number: número da conta;
• amount: objeto contendo o valor total da transação e a moeda utilizada;
• withoutFeeAmount: objeto contendo o valor da transação sem taxas e a moeda utilizada;
• iofAmount: valor calculado do IOF da transação;
• markupAmount: valor calculado do markup da transação;
• withdrawalFeeAmount: valor da tarifa de saque (somente para transações de saque);
• fees: taxas aplicadas na transação;
  • markup: o percentual do markup;
  • iof: o percentual do IOF;
  • dollarExchangeRate: objeto contendo a cotação atual do dólar e a moeda em que ele é cotado;
• deniedRules: lista dos motivos pelos quais a transação foi negada. Confira a lista completa na sessão, Denied rules, logo abaixo;
• status: status da transação, o qual pode ser: “SUCCESS” ou “DENIED”;
• transactionTimeStamp: a data e a hora em que ocorreu a transação;
• channel: canal por onde passam as informações recebidas da rede de cartões;
  • numberOfInstallments: quantidade de parcelas da transação;
  • transactionType: tipo da transação de acordo com a ISO 8583;
    • code: código da transação, o qual pode ser: “00”, “01”, ou “20”;
    • description: descrição do código, a qual pode ser “purchase” para “00”, “withdraw” para “01” ou “voucher” para “20”;
  • settlement: objeto contendo o valor da transação sem taxas e a moeda utilizada;
  • localAmount: objeto contendo o valor da transação sem taxas e a moeda do local da transação.
  • entryMode:
    • code: o código do modo de entrada de acordo com a ISO 8583;
    • description: a descrição do modo de entrada;
    • cardPresent: define se este modo de entrada está presente no cartão;
  • authorizationCode: um identificador da transação da rede do cartão;
  • wallet: objeto contendo o código e a descrição da carteira. Veja alguns exemplos na tabela ao final da página;
  • retrievalReferenceNumber: um identificador de transação da rede do cartão;
  • merchant: informações referentes ao estabelecimento/comerciante que aceitou a transação. Seus campos são baseados na ISO 8583:
    • mcc: o código mcc da transação;
    • mcg: a descrição do tipo do mcc;
    • city: a cidade do merchant para identificar parte de sua localização;
    • stateOrCountryCode: o código do estado ou do país do merchant para identificar parte da sua localização;
    • state: estado do merchant para identificar parte de sua localização;
    • name: nome do merchant;
    • zipCode: CEP do merchant;
    • terminalId: id do terminal do merchant;
    • acquirerCode: código do credenciador;
  • authorizationId: identificador da autorização da processadora;
  • name: nome do canal que iniciou a transação no banco. No contexto do autorizador, o canal será sempre “CARD_NETWORK”;
• authorizationTransactionId: o identificador da transação gerado pela plataforma de autorização do Bankly;
• dollarExchangeRate: a cotação atual do dólar, em reais;
• card:
  • proxy: código identificador do cartão;
  • alias: apelido definido pelo proprietário do cartão;
  • function: função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”;
  • type: tipo do cartão, o qual pode ser: “Physical” ou “Virtual”;
• reversalReason: motivo da reversão da transação. Exemplo: “SystemFault”, “PosRequest”, “DebitReversal”;
• clearingDate: data de confirmação processada pela plataforma de autorização do Bankly.

Exemplos de conteúdo do campo wallet

📘

Nota

No contexto de autorização (Authorization), os subcampos type, status, pockets, balance e label do campo Account geralmente são enviados como null.

Denied rules

O evento de autorização TRANSACTION_WAS_PROCESSED traz o campo deniedRules, que pode conter os seguintes motivos de negação:

Bankly

Core bancário

Processadora