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:

Nome do evento (name)	Descrição
TRANSACTION_WAS_PROCESSED	A transação foi processada. Ela pode ter sido aprovada ou não.
TRANSACTION_WAS_REVERTED	A transação foi revertida parcial ou totalmente.
TRANSACTION_WAS_EXPIRED	O tempo de reserva de saldo da transação expirou e a transação foi revertida. Esse fluxo ocorre em transações pré-pagas.

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`

Código	Descrição
101	MasterpassByMastercard
103	ApplePay
216	GooglePay
217	SamsungPay
327	MerchantTokenizationProgram
0	Unknown
00	Unknown

📘
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

Motivo	Descrição
NOT_ALLOWED_ADVICE_FOR_DENIED_TRANSACTION_HOLD	A reversão por falha sistêmica não foi permitida porque a autorização foi negada.
OPERATION_NOT_IMPLEMENTED	A interpretação da requisição recebida não resultou em nenhuma operação válida (autorização, advice ou reversão).
DUPLICATED_TRANSACTION	Transação duplicada.
TRANSACTION_NOT_EXISTS	Transação não existe.
BLOCKED_BY_CARD_INTEGRATION	Erro de comunicação interna com o serviço de cartão.
NOT_ALLOWED_WITHDRAWAL	Não é permitido saque.
NOT_ALLOWED_PURCHASE_INTERNATIONAL	Não é permitida compra internacional.
NOT_ALLOWED_PURCHASE_ONLINE	Não é permitida compra online.
NOT_ALLOWED_PURCHASE_PHYSICAL	Não é permitida compra física.
NOT_ALLOWED_PRE_AUTHORIZATION	Não é permitida pré-autorização.
NOT_ALLOWED_MORE_THAN_ONE_INSTALLMENT	Não é permitido parcelamento.
CONSTITUTION_NOT_FOUND	Erro interno na consulta de configurações do cartão.
NOT_ALLOWED_CONTACTLESS	Não é permitido contactless.
NOT_ALLOWED_MCC	MCC não permitido.
NOT_ALLOWED_CARD_NOT_VALID	Cartão não ativo.
NOT_ALLOWED_CARD_LOCKED	Cartão bloqueado.
NOT_ALLOWED_CARD_CANCELED	Cartão cancelado.
NOT_ALLOWED_CARD_IS_BUILDING	Cartão ainda em processo de impressão.
NOT_ALLOWED_REVERSAL_AMOUNT_GREATER_THAN_ORIGINAL_AMOUNT	Reversão não permitida, pois o valor é maior que o original.
NOT_ALLOWED_REVERSAL_FOR_ALREADY_PROCESSED_TRANSACTION_IN_SECOND_INSTANCE	Não é permitida a reversão para a transação já conciliada.
NOT_ALLOWED_PARTIAL_WITHDRAWAL_REVERSAL	Não é permitida a reversão de saque parcial.
BLOCKED_BY_CORE_BANK_VALIDATION	Falha na integração com core bancário.
BLOCKED_BY_LIMIT_VALIDATION	Bloqueado por validação de limite de quantidade de transações ou montante por CPF por ciclo (transacional, diário ou mensal).
BLOCKED_BY_RISK_ANALYSIS	Bloqueado para análise de risco (enviado em transações pré-pagas).
BLOCKED_BY_RISK_ANALYSIS_AND_LIMIT_VALIDATION	Bloqueado por análise de risco e validação de limite.
INVALID_OPERATION	A compra foi passada em uma operação (débito ou crédito) não permitida.
NOT_ALLOWED_CARD_WITH_STATUS_CREATED	Cartão com status de Criação.
NOT_ALLOWED_CARD_WITH_STATUS_BLOCKED	Cartão com status Bloqueado.
NOT_ALLOWED_CARD_WITH_STATUS_WARNING	Cartão com status de Atenção.
NOT_ALLOWED_CARD_WITH_STATUS_CANCELLED_OR_CLIENTORDER	Cartão com status Cancelado.
NOT_ALLOWED_CARD_WITH_STATUS_FRAUD	Cartão com status de Fraude.
NOT_ALLOWED_CARD_WITH_STATUS_LOST	Cartão com status Perdido.
NOT_ALLOWED_CARD_WITH_STATUS_ROBBED_OR_THEFT	Cartão com status Roubado.
NOT_ALLOWED_CARD_WITH_STATUS_DELETED	Cartão com status Excluído.
NOT_ALLOWED_CARD_WITH_STATUS_UNRECEIVED	Cartão com status Não Recebido.
NOT_ALLOWED_CARD_WITH_STATUS_INOPERATIVE	Cartão com status Inoperante.
NOT_ALLOWED_PURCHASE_WITH_CURRENCY_UNMATCH_COUNTRY	A compra foi realizada em BRL, mas o estabelecimento é internacional.
NOT_ALLOWED_CARD_WITH_STATUS_OTHER	Cartão com status Outros.
TRANSACTION_IS_NOT_ON_HOLD	Transação já revertida.
NOT_ALLOWED_REVERSAL_CURRENCY_UNMATCH_ORIGINAL_CURRENCY	Moeda de reversão diferente da utilizada na autorização.

Core bancário

Motivo	Descrição
INSUFFICIENT_BALANCE	Saldo insuficiente.
AUTHORIZATION_HOLD_NOT_FOUND	Erro ao tentar reverter uma autorização não efetuada.
WITHDRAWAL_LIMIT_EXCEEDED	O limite de retirada de dinheiro no core bancário foi excedido.
CORE_BANK_INTEGRATION_ERROR	Erro ao integrar com o core bancário.

Processadora

Motivo	Descrição
INVALID_PASSWORD	A senha informada na compra/saque não é válida.
PAN_NOT_FOUND_IN_PCI_DATABASE	Cartão não encontrado pela processadora.
INVALID_EXPIRATION_DATE	Data de expiração inválida.
NOT_ALOWED_PURCHASE_WITH_STRIPE_CARD	Não é permitido passar a compra com a tarja do cartão.
INVALID_ENTRY_MODE	Não é permitido passar a compra com a tarja do cartão, pois a máquina só aceita chip.
CVV_VALIDATION_WITH_SAFETY_AUTHENTICATION_MODE_VALIDATION	CVV inválido.
UNSAFETY_TRANSACTION_WITHOUT_VALIDATION_METHOD	Não foi informado nenhum dado de segurança, no momento da transação.
CVV_VALIDATION_WITH_EXPIRATION_DATE_VALIDATION	Cartão temporário utilizado após o término do seu prazo de vida.
ANTI_FRAUD_VALIDATION	Transação pós-paga negada no antifraude do Bankly.
CANCEL_REQUEST_UNMATCH_ORIGINAL_TRANSACTION	Transação original não encontrada na processadora.
LIMIT_EXCEEDED	Limite da processadora excedido.
TIMEOUT	Tempo de comunicação expirado.
COMUNICATION_FAIL	Comunicação indisponível.
CRIPTOGRAM_VALIDATION_HSM	Falha na validação de segurança do criptograma.
OBSOLET_CARDHOLDER_VALIDATION	Método de validação do usuário é obsoleto.
INVALID_OPERATION_FOR_THE_PROGRAM_OR_ACCOUNT	Não é permitido o parcelamento de compra com cartão de débito ou crédito pré.
NOT_ALOWED_TRANSACTION_DATE_BIGGER_THAN_CARD_EXPIRATION_DATE	Cartão expirado.
RETRY_QUANTITY_EXCEEDED	Número de tentativas de senha foi excedido.
ATC	Discrepância entre o ATC (Application Transaction Counter) do chip e do autorizador.
NOT_ALLOWED_PURCHASE_FOR_BLOCKED_ACCOUNT	Conta bloqueada.
CRIPTOGRAM_VALIDATION_PER_ENTRY_MODE	Criptograma não enviado para o entry mode escolhido.

Contexto e nome do evento

EntityId

Exemplos de eventos

Importante

Objeto data nos eventos de autorização

Exemplos de conteúdo do campo wallet

Nota

Denied rules

Bankly

Core bancário

Processadora

Exemplos de conteúdo do campo `wallet`