Autorização e confirmação (Authorization)
stable
O processo de autorização consiste numa série de análises internas realizadas pelo Bankly para autorizar o processamento de uma transação com um cartão.
Após a autorização, ocorre o processo de confirmação, no qual o valor é de fato liquidado e o dinheiro é depositado na conta do recebedor.
Todos os eventos relacionados à autorização e à confirmação de transações com o cartão serão comunicados ao destinatário através de mensagens.
Pré-requisitos
Para receber esses eventos, o parceiro deverá:
- Configurar previamente o recebedor de eventos do webhook.
- Conhecer a estrutura básica dos eventos que acompanha o objeto
data
.
Informações sobre os eventos
Contexto e nome do evento
Os campos context
e name
poderão variar de acordo com a tabela a seguir:
context | name | Descrição |
---|---|---|
Authorization | TRANSACTION_WAS_PROCESSED | A transação foi processada. Ela pode ter sido aprovada ou não. |
Authorization | TRANSACTION_WAS_REVERTED | A transação foi revertida parcial ou totalmente. |
Authorization | 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. |
Authorization | CONFIRMATION_WAS_PROCESSED | A transação foi confirmada parcial ou totalmente. |
Authorization | CANCELATION_WAS_PROCESSED | A transação foi cancelada. |
Authorization | VOUCHER_WAS_PROCESSED | O voucher (crédito) foi lançado na conta do cliente. |
Fluxo dos eventos
O fluxograma a seguir descreve a sequência em que os eventos ocorrem. Clique na imagem para ampliá-la:

Nota
É possível que o evento VOUCHER_WAS_PROCESSED seja disparado isoladamente. Ou seja, ele poderá ser disparado mesmo sem conexão com o evento TRANSACTION_WAS_PROCESSED.
Identificador (entityId
)
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 identificador único da transação (authorizationTransactionId
).
Dados dos eventos
TRANSACTION_WAS_PROCESSED
Este evento sinaliza que a transação foi processada. Ela pode ter sido aprovada ou não.
Descrição do objeto data
do evento
data
do eventoO objeto data
traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
Nome | Tipo | Descrição |
---|---|---|
account | object | Objeto que contém informações sobre a conta bancária. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta. |
account.bank | object | Objeto que contém informações sobre o banco ao qual a conta pertence. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
amount | object | Objeto que contém informações sobre o valor da transação. |
amount.value | number | Valor da transação. |
amount.currency | string | Código da moeda com base na ISO-4217. |
withoutFeeAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
withoutFeeAmount.value | number | Valor da transação sem taxas. |
withoutFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
iofAmount | object | Objeto que contém informações sobre o valor calculado do IOF da transação. |
iofAmount.value | number | Valor calculado do IOF da transação. |
iofAmount.currency | string | Código da moeda com base na ISO-4217. |
markupAmount | object | Objeto que contém informações sobre o valor calculado do markup da transação. |
markupAmount.value | number | Valor calculado do markup. |
markupAmount.currency | string | Código da moeda com base na ISO-4217. |
withdrawalFeeAmount | object | Objeto que contém informações sobre o valor da tarifa de saque (somente para transações de saque). |
withdrawalFeeAmount.value | number | Valor da tarifa de saque. |
withdrawalFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
fees | object | Objeto que contém informações sobre as taxas aplicadas na transação. |
fees.markup | number | Percentual do markup. |
fees.iof | number | Percentual do IOF. |
fees.dollarExchangeRate | object | Objeto que contém informações sobre a cotação atual do dólar, em reais. |
fees.dollarExchangeRate.value | number | Cotação atual do dólar, em reais. |
fees.dollarExchangeRate.currency | string | Código da moeda local com base na ISO-4217. |
deniedRules | array of strings | Motivos pelos quais a transação foi negada. Confira a lista dos possíveis motivos de negação no final da página. |
status | string | Situação da transação, a qual pode ser “SUCCESS” ou “DENIED”. |
transactionTimeStamp | string | Data e a hora em que ocorreu a transação, no formato YYYY-MM-DDTHH:mm:SS. |
channel | object | Objeto que contém informações sobre o canal por onde passam os dados recebidos da rede de cartões. |
channel.settlement | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.settlement.value | number | Valor da transação sem taxas. |
channel.settlement.currency | string | Código da moeda com base na ISO-4217. |
channel.localAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.localAmount.value | number | Valor da transação sem taxas. |
channel.localAmount.currency | string | Código da moeda local com base na ISO-4217. |
channel.entryMode | object | Objeto que contém informações sobre o modo de entrada do cartão. |
channel.entryMode.code | string | Código do modo de entrada de acordo com a ISO-8583. |
channel.entryMode.description | string | Descrição do modo de entrada. |
channel.entryMode.cardPresent | boolean | Indica se este modo de entrada está presente no cartão. |
channel.authorizationCode | string | Identificador da transação da rede do cartão. |
channel.transactionType | object | Objeto que contém informações sobre o tipo da transação de acordo com a ISO-8583. |
channel.transactionType.code | string | Código da transação, o qual pode ser: “00”, “01”, ou “20”. |
channel.transactionType.description | string | Descrição do código, a qual pode ser “purchase” para “00”, “withdraw” para “01” ou “voucher” para “20”. |
channel.wallet | object | Objeto que contém informações sobre a carteira utilizada na transação. Confira a lista com as possíveis carteiras na tabela ao final da página. |
channel.wallet.code | string | Código da carteira. |
channel.wallet.name | string | Nome da carteira. |
channel.retrievalReferenceNumber | string | Identificador de transação da rede do cartão. |
channel.merchant | object | Objeto que contém informações referentes ao estabelecimento/comerciante que aceitou a transação. Seus campos são baseados na ISO-8583. |
channel.merchant.mcc | string | Código mcc da transação. |
channel.merchant.mcg | string | Descrição do tipo do mcc. |
channel.merchant.city | string | Cidade do merchant para identificar parte de sua localização. |
channel.merchant.stateOrCountryCode | string | Código do estado ou do país do merchant para identificar parte da sua localização. |
channel.merchant.state | string | Estado do merchant para identificar parte de sua localização |
channel.merchant.name | string | Nome do merchant. |
channel.merchant.zipCode | string | Código postal do merchant. |
channel.merchant.terminalId | string | Identificador do terminal do merchant. |
channel.merchant.acquirerCode | string | Código do credenciador. |
channel.numberOfInstallments | number | Quantidade de parcelas da transação. |
authorizationId | number | Identificador da autorização da processadora. |
channel.name | string | Nome do canal que iniciou a transação no banco. No contexto do autorizador, o canal será sempre “CARD_NETWORK”. |
authorizationTransactionId | string | Identificador da transação gerado pela plataforma de autorização do Bankly. |
card | object | Objeto que contém informações sobre o cartão utilizado na transação. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
card.function | string | Função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”. |
card.type | string | Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"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": "15164",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
},
"amount": {
"value": 9.96,
"currency": "BRL"
},
"withoutFeeAmount": {
"value": 9.96,
"currency": "BRL"
},
"iofAmount": {
"value": 0,
"currency": "BRL"
},
"markupAmount": {
"value": 0,
"currency": "BRL"
},
"withdrawalFeeAmount": {
"value": 0,
"currency": "BRL"
},
"fees": {
"markup": 0,
"iof": 0,
"dollarExchangeRate": {
"value": 0,
"currency": "BRL"
}
},
"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"
}
]
TRANSACTION_WAS_REVERTED
Este evento sinaliza que a transação foi revertida parcial ou totalmente.
Descrição do objeto data
do evento
data
do eventoO objeto data
traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
Nome | Tipo | Descrição |
---|---|---|
account | object | Objeto que contém informações sobre a conta bancária. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta. |
account.bank | object | Objeto que contém informações sobre o banco ao qual a conta pertence. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
amount | object | Objeto que contém informações sobre o valor da transação. |
amount.value | number | Valor da transação. |
amount.currency | string | Código da moeda com base na ISO-4217. |
withoutFeeAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
withoutFeeAmount.value | number | Valor da transação sem taxas. |
withoutFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
iofAmount | object | Objeto que contém informações sobre o valor calculado do IOF da transação. |
iofAmount.value | number | Valor calculado do IOF da transação. |
iofAmount.currency | string | Código da moeda com base na ISO-4217. |
markupAmount | object | Objeto que contém informações sobre o valor calculado do markup da transação. |
markupAmount.value | number | Valor calculado do markup. |
markupAmount.currency | string | Código da moeda com base na ISO-4217. |
withdrawalFeeAmount | object | Objeto que contém informações sobre o valor da tarifa de saque (somente para transações de saque). |
withdrawalFeeAmount.value | number | Valor da tarifa de saque. |
withdrawalFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
dollarExchangeRate | object | Objeto que contém informações sobre a cotação atual do dólar, em reais. |
dollarExchangeRate.value | number | Cotação atual do dólar, em reais. |
dollarExchangeRate.currency | string | Código da moeda local com base na ISO-4217. |
reversalReason | number | Motivo da reversão da transação. Exemplo: “SystemFault”, “PosRequest”, “DebitReversal”. |
channel | object | Objeto que contém informações sobre o canal por onde passam os dados recebidos da rede de cartões. |
channel.settlement | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.settlement.value | number | Valor da transação sem taxas. |
channel.settlement.currency | string | Código da moeda com base na ISO-4217. |
channel.localAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.localAmount.value | number | Valor da transação sem taxas. |
channel.localAmount.currency | string | Código da moeda local com base na ISO-4217. |
channel.name | string | Nome do canal que iniciou a transação no banco. No contexto do autorizador, o canal será sempre “CARD_NETWORK”. |
authorizationTransactionId | string | Identificador da transação gerado pela plataforma de autorização do Bankly. |
card | object | Objeto que contém informações sobre o cartão utilizado na transação. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
card.function | string | Função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”. |
card.type | string | Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"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",
"context": "Authorization",
"idempotencyKey": "23247612-9b04-4dd0-8764-31ed27ab5e40",
"metadata": null,
"data": {
"account": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
},
"amount": {
"value": 7.93,
"currency": "BRL"
},
"withoutFeeAmount": {
"value": 7.93,
"currency": "BRL"
},
"iofAmount": {
"value": 0,
"currency": "BRL"
},
"markupAmount": {
"value": 0,
"currency": "BRL"
},
"withdrawalFeeAmount": {
"value": 0,
"currency": "BRL"
},
"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
}
}
}
]
TRANSACTION_WAS_EXPIRED
Este evento sinaliza que o tempo de reserva de saldo da transação expirou e a transação foi revertida. Esse fluxo ocorre em transações pré-pagas.
Descrição do objeto data
do evento
data
do eventoO objeto data
traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
Nome | Tipo | Descrição |
---|---|---|
authorizationTransactionId | string | Identificador da transação gerado pela plataforma de autorização do Bankly. |
card | object | Objeto que contém informações sobre o cartão utilizado na transação. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
card.function | string | Função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”. |
card.type | string | Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”. |
account | object | Objeto que contém os dados da conta e da licença bancária. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta. |
account.bank | object | Objeto que contém os dados bancários. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"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",
"context": "Authorization",
"idempotencyKey": "9b76feea-98a0-4001-b2bf-ab83ae57adce",
"metadata": null,
"data": {
"authorizationTransactionId": "a1349dde-817a-4913-91d0-84fa2d787755",
"card": {
"proxy": "0000000000000000000",
"alias": "0921",
"function": "Pre",
"type": null
},
"account": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
},
}
}
]
CONFIRMATION_WAS_PROCESSED
Este evento sinaliza que a transação foi confirmada parcial ou totalmente.
Descrição do objeto data
do evento
data
do eventoO objeto data
traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
Nome | Tipo | Descrição |
---|---|---|
account | object | Objeto que contém os dados da conta e da licença bancária. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta. |
account.bank | object | Objeto que contém os dados bancários. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
amount | object | Objeto que contém informações sobre o valor da transação. |
amount.value | number | Valor da transação. |
amount.currency | string | Código da moeda com base na ISO-4217. |
withoutFeeAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
withoutFeeAmount.value | number | Valor da transação sem taxas. |
withoutFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
iofAmount | object | Objeto que contém informações sobre o valor calculado do IOF da transação. |
iofAmount.value | number | Valor calculado do IOF da transação. |
iofAmount.currency | string | Código da moeda com base na ISO-4217. |
markupAmount | object | Objeto que contém informações sobre o valor calculado do markup da transação. |
markupAmount.value | number | Valor calculado do markup. |
markupAmount.currency | string | Código da moeda com base na ISO-4217. |
withdrawalFeeAmount | object | Objeto que contém informações sobre o valor da tarifa de saque (somente para transações de saque). |
withdrawalFeeAmount.value | number | Valor da tarifa de saque. |
withdrawalFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
channel | object | Objeto que contém informações sobre o canal por onde passam os dados recebidos da rede de cartões. |
channel.numberOfInstallments | number | Quantidade de parcelas da transação. |
channel.settlement | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.settlement.value | number | Valor da transação sem taxas. |
channel.settlement.currency | string | Código da moeda com base na ISO-4217. |
channel.localAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.localAmount.value | number | Valor da transação sem taxas. |
channel.localAmount.currency | string | Código da moeda local com base na ISO-4217. |
channel.name | string | Nome do canal que iniciou a transação no banco. No contexto do autorizador, o canal será sempre “CARD_NETWORK”. |
fees | object | Objeto que contém informações sobre as taxas aplicadas na transação. |
fees.markup | number | Percentual do markup. |
fees.iof | number | Percentual do IOF. |
fees.dollarExchangeRate | object | Objeto que contém informações sobre a cotação atual do dólar, em reais. |
fees.dollarExchangeRate.value | number | Cotação atual do dólar, em reais. |
fees.dollarExchangeRate.currency | string | Código da moeda local com base na ISO-4217. |
authorizationTransactionId | string | Identificador da transação gerado pela plataforma de autorização do Bankly. |
card | object | Objeto que contém informações sobre o cartão utilizado na transação. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
card.function | string | Função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”. |
card.type | string | Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”. |
clearingDate | string | Data de confirmação processada pela plataforma de autorização do Bankly, no formato YYYY-MM-DDTHH:mm:SS. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"entityId": "215a51e6-9934-423a-8f15-321f6301bc34",
"companyKey": "COMPANY_KEY",
"name": "CONFIRMATION_WAS_PROCESSED",
"timestamp": "2022-04-25T09:18:02.0901117Z",
"correlationId": "215a51e6-9934-423a-8f15-321f6301bc34",
"idempotencyKey": "215a51e6-9934-423a-8f15-321f6301bc34",
"context": "Authorization",
"metadata": null,
"data": {
"account": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
},
"amount": {
"value": 52.9,
"currency": "BRL"
},
"withoutFeeAmount": {
"value": 52.9,
"currency": "BRL"
},
"iofAmount": {
"value": 0,
"currency": "BRL"
},
"markupAmount": {
"value": 0,
"currency": "BRL"
},
"withdrawalFeeAmount": {
"value": 0,
"currency": "BRL"
},
"channel": {
"numberOfInstallments": 1,
"settlement": {
"value": 52.9,
"currency": "USD"
},
"localAmount": {
"value": 52.9,
"currency": "BRL"
},
"name": "CARD_NETWORK"
},
"fees": {
"markup": 0,
"iof": 0,
"dollarExchangeRate": {
"value": 0,
"currency": "BRL"
}
},
"authorizationTransactionId": "215a51e6-9934-423a-8f15-321f6301bc34",
"card": {
"proxy": "0000000000000000000",
"alias": "Card Physic Pos",
"function": "Pos",
"type": null
},
"clearingDate": "2022-04-25T09:18:02.0900356Z"
}
}
]
CANCELATION_WAS_PROCESSED
Este evento sinaliza que a transação foi cancelada.
Descrição do objeto data
do evento
data
do eventoO objeto data
traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
Nome | Tipo | Descrição |
---|---|---|
channel | object | Objeto que contém informações sobre o canal por onde passam os dados recebidos da rede de cartões. |
channel.transactionType | object | Objeto que contém informações sobre o tipo da transação de acordo com a ISO-8583. |
channel.transactionType.code | string | Código da transação, o qual pode ser: “00”, “01”, ou “20”. |
channel.transactionType.description | string | Descrição do código, a qual pode ser “purchase” para “00”, “withdraw” para “01” ou “voucher” para “20”. |
channel.name | string | Nome do canal que iniciou a transação no banco. No contexto do autorizador, o canal será sempre “CARD_NETWORK”. |
authorizationTransactionId | string | Identificador da transação gerado pela plataforma de autorização do Bankly. |
card | object | Objeto que contém informações sobre o cartão utilizado na transação. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
card.function | string | Função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”. |
card.type | string | Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”. |
account | object | Objeto que contém os dados da conta e da licença bancária. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta. |
account.bank | object | Objeto que contém os dados bancários. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
clearingDate | string | Data de confirmação processada pela plataforma de autorização do Bankly, no formato YYYY-MM-DDTHH:mm:SS. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"entityId": "2ed8a63c-e3e3-4093-8094-9ce0635b2404",
"companyKey": "COMPANY_KEY",
"name": "CANCELATION_WAS_PROCESSED",
"timestamp": "2022-04-25T09:10:36.9474645Z",
"correlationId": "2ed8a63c-e3e3-4093-8094-9ce0635b2404",
"idempotencyKey": "2ed8a63c-e3e3-4093-8094-9ce0635b2404",
"context": "Authorization",
"metadata": null,
"data": {
"channel": {
"transactionType": {
"code": "00",
"description": "Purchase"
},
"name": "CARD_NETWORK"
},
"authorizationTransactionId": "2ed8a63c-e3e3-4093-8094-9ce0635b2404",
"card": {
"proxy": "0000000000000000000",
"alias": "Card Physic Pos",
"function": "Pos",
"type": null
},
"account": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
},
"clearingDate": "2022-04-25T09:10:36.9474585Z"
}
}
]
VOUCHER_WAS_PROCESSED
Este evento sinaliza que o voucher (crédito) foi lançado na conta do cliente.
Descrição do objeto data
do evento
data
do eventoO objeto data
traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
Nome | Tipo | Descrição |
---|---|---|
amount | object | Objeto que contém informações sobre o valor da transação. |
amount.value | number | Valor da transação. |
amount.currency | string | Código da moeda com base na ISO-4217. |
withoutFeeAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
withoutFeeAmount.value | number | Valor da transação sem taxas. |
withoutFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
iofAmount | object | Objeto que contém informações sobre o valor calculado do IOF da transação. |
iofAmount.value | number | Valor calculado do IOF da transação. |
iofAmount.currency | string | Código da moeda com base na ISO-4217. |
markupAmount | object | Objeto que contém informações sobre o valor calculado do markup da transação. |
markupAmount.value | number | Valor calculado do markup. |
markupAmount.currency | string | Código da moeda com base na ISO-4217. |
withdrawalFeeAmount | object | Objeto que contém informações sobre o valor da tarifa de saque (somente para transações de saque). |
withdrawalFeeAmount.value | number | Valor da tarifa de saque. |
withdrawalFeeAmount.currency | string | Código da moeda com base na ISO-4217. |
account | object | Objeto que contém informações sobre a conta bancária. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta. |
account.bank | object | Objeto que contém informações sobre o banco ao qual a conta pertence. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
channel | object | Objeto que contém informações sobre o canal por onde passam os dados recebidos da rede de cartões. |
channel.authorizationCode | string | Identificador da transação da rede do cartão. |
channel.entryMode | object | Objeto que contém informações sobre o modo de entrada do cartão. |
channel.entryMode.code | string | Código do modo de entrada de acordo com a ISO-8583. |
channel.entryMode.description | string | Descrição do modo de entrada. |
channel.retrievalReferenceNumber | string | Identificador de transação da rede do cartão. |
channel.merchant | object | Objeto que contém informações referentes ao estabelecimento/comerciante que aceitou a transação. Seus campos são baseados na ISO-8583. |
channel.merchant.mcc | string | Código mcc da transação. |
channel.merchant.mcg | string | Descrição do tipo do mcc. |
channel.merchant.city | string | Cidade do merchant para identificar parte de sua localização. |
channel.merchant.stateOrCountryCode | string | Código do estado ou do país do merchant para identificar parte da sua localização. |
channel.merchant.state | string | Estado do merchant para identificar parte de sua localização |
channel.merchant.name | string | Nome do merchant. |
channel.merchant.zipCode | string | Código postal do merchant. |
channel.merchant.terminalId | string | Identificador do terminal do merchant. |
channel.merchant.acquirerCode | string | Código do credenciador. |
channel.settlement | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.settlement.value | number | Valor da transação sem taxas. |
channel.settlement.currency | string | Código da moeda com base na ISO-4217. |
channel.localAmount | object | Objeto que contém informações sobre o valor da transação sem taxas. |
channel.localAmount.value | number | Valor da transação sem taxas. |
channel.localAmount.currency | string | Código da moeda local com base na ISO-4217. |
channel.name | string | Nome do canal que iniciou a transação no banco. No contexto do autorizador, o canal será sempre “CARD_NETWORK”. |
fees | object | Objeto que contém informações sobre as taxas aplicadas na transação. |
fees.markup | number | Percentual do markup. |
fees.iof | number | Percentual do IOF. |
fees.dollarExchangeRate | object | Objeto que contém informações sobre a cotação atual do dólar, em reais. |
fees.dollarExchangeRate.value | number | Cotação atual do dólar, em reais. |
fees.dollarExchangeRate.currency | string | Código da moeda local com base na ISO-4217. |
authorizationTransactionId | string | Identificador da transação gerado pela plataforma de autorização do Bankly. |
card | object | Objeto que contém informações sobre o cartão utilizado na transação. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
card.function | string | Função do cartão, a qual pode ser: “Pre”, “Pos”, “Debit”. |
card.type | string | Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”. |
clearingDate | string | Data de confirmação processada pela plataforma de autorização do Bankly, no formato YYYY-MM-DDTHH:mm:SS. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"entityId": "6c8e5350-a4ac-4a9a-a8b7-9835633bf51d",
"companyKey": "COMPANY_KEY",
"name": "VOUCHER_WAS_PROCESSED",
"timestamp": "2022-04-25T03:04:28.9712289Z",
"correlationId": "ae72c7d2-91bb-4f55-918b-1a84ca678019",
"metadata": null,
"data": {
"amount": {
"value": 100,
"currency": "BRL"
},
"withoutFeeAmount": {
"value": 100,
"currency": "BRL"
},
"iofAmount": {
"value": 0,
"currency": "BRL"
},
"markupAmount": {
"value": 0,
"currency": "BRL"
},
"withdrawalFeeAmount": {
"value": 0,
"currency": "BRL"
},
"account": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
},
"channel": {
"authorizationCode": "SYUTM0",
"entryMode": {
"code": "090550S99001",
"description": "EletronicCommerceSecureWithUCAF"
},
"retrievalReferenceNumber": "100284045256",
"merchant": {
"mcc": "8999",
"mcg": "Ecommerce",
"city": "SANTARÉM",
"stateOrCountryCode": "BRA",
"state": "BRA",
"name": "MERCADO",
"zipCode": null,
"terminalId": "10250284",
"acquirerCode": "012088"
},
"settlement": {
"value": 100,
"currency": "USD"
},
"localAmount": {
"value": 100,
"currency": "BRL"
},
"name": "CARD_NETWORK"
},
"fees": {
"markup": 0,
"iof": 0,
"dollarExchangeRate": {
"value": 0,
"currency": "BRL"
}
},
"authorizationTransactionId": "a5275aa0-2d34-4564-a320-1202c5d52c9b",
"card": {
"proxy": "0000000000000000000",
"alias": "Compras",
"function": "Pre",
"type": "Virtual"
},
"clearingDate": "2022-04-25T03:04:28.970992Z"
},
"idempotencyKey": "ae72c7d2-91bb-4f55-918b-1a84ca678019",
"context": "Authorization"
}
]
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 |
Motivos para uma transação negada (deniedRules
)
deniedRules
)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. |
Updated 26 days ago