Requisição de Autorização
Uma vez que o programa está configurado, o portador do cartão foi adicionado e tem um cartão ativo, este cartão pode ser usado para fazer compras em vários pontos de venda ao redor do mundo. Sempre que uma transação for iniciada em algum ponto de captura, uma Authorization será criada para autorizar este movimento. Será feita uma Requisição de Autorização Authorization Request ao sistema do cliente para que este decida pela aprovação ou não desta autorização com base nas informações contidas neste pedido.
A entidade Authorization contém a situação atual dos valores autorizados e capturados e pode assumir os seguintes valores de estado:
| Estado | Descrição |
|---|---|
| pending | Requisição de autorização foi aprovada e nenhum evento de captura ou cancelamento foi processado |
| unauthorized | Requisição de autorização não foi aprovada |
| completed | Pelo menos um valor capturado com sucesso para a autorização em questão (seja um valor igual, a menor ou a maior que o valor total aprovado nas requisições de autorização) |
| reversed | Autorização foi estornada por completo ou expirou sem captura |
Detalhamento dos campos de uma Autorização pode ser encontrado em Buscar Autorização
A Requisição de Autorização Authorization Request quando enviada para o cliente conterá os Cabeçalhos de Autenticação e possuirá a seguinte composição:
Requisição de Autorização
Request Body
{
"authorization_key": "c91ce179-517c-48f9-9c28-18368457b67f",
"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"card": {
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"type": "virtual",
"card_name": "ecommerce sample",
"printed_name": "Aurora Catarina",
"status": "active",
"brand": "visa",
"bin": "123456",
"last_four_digits": "5695"
},
"terminal_id": "123456",
"terminal_country_code": "BRA",
"terminal_type": "2",
"terminal_pin_entry_capability": true,
"terminal_magnetic_stripe_capability": true,
"terminal_contactless_capability": false,
"terminal_chip_capability": true,
"merchant_acquirer_code": "250",
"merchant_code": "123456",
"merchant_name": "VASP LINHAS AEREAS",
"merchant_street": "RUA CMDTE X, 127",
"merchant_city": "SAO PAULO, SP",
"merchant_region": "BRA",
"merchant_postal_code": "04570-140",
"merchant_mcc": "3036",
"authorization_code": "473890",
"nsu": "123456",
"acquirer_reference_number": "12312423",
"merchant_currency_code": "BRL",
"merchant_amount": 10.59,
"billing_currency_code": "BRL",
"billing_amount": 10.59,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"number_of_installments": 1,
"authorization_type": "authorization",
"pan_entry_mode": "chip",
"pin_sent": true,
"autorization": {Objeto Autorização}
}
Authorization Request
| Campo | Tipo | Descrição |
|---|---|---|
authorization_request_key | string | Identificador único da Requisição de Autorização |
authorization_key | string | Identificador único da entidade Autorização relacionada com esta requisição |
card | object | Objeto Card |
terminal_id | string | O identificador do terminal enviado pela adquirente na mensageria de autenticação |
terminal_country_code | string | O código do país do terminal, enviado na mensagem de autorização conforme ISO 3166-1 alpha-3 |
terminal_type | string | O tipo de terminal conforme recebido na mensageria de autorização |
terminal_pin_entry_capability | boolean | Existe a possibilidade de inserir a senha do cartão no terminal? |
terminal_magnetic_stripe_capability | boolean | O terminal é capaz de ler tarja magnética? |
terminal_contactless_capability | boolean | O terminal é capaz de iniciar transações contactless? |
terminal_chip_capability | boolean | O terminal é capaz de iniciar transações utilizando o chip EMV? |
merchant_acquirer_code | string | O identificador da adquirente conforme mensageria de autorização |
merchant_code | string | O identificador do lojista na adquirente conforme mensageria de autorização |
merchant_name | string | O nome do lojista de acordo com a mensageria de autorização |
merchant_street | string | A rua do endereço do lojista |
merchant_city | string | A cidade do endereço do lojista |
merchant_region | string | A região do endereço do lojista |
merchant_postal_code | string | O código postal (CEP) do endereço do lojista |
merchant_mcc | string | Merchant Category Code - identificação do tipo de estabelecimento - Lista Atualizada pode ser encontrada aqui |
authorization_code | string | Código de Autorização de 6 dígitos |
nsu | string | Número sequencial único que define uma autorização |
acquirer_reference_number | string | Identificador único da autorização na adquirente |
merchant_currency_code | string | A moeda utilizada na transação - ISO 4217-alpha |
merchant_amount | decimal | Valor da transação na moeda em que a transação foi realizada |
billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
billing_amount | decimal | Valor da transação na moeda de cobrança do portador do cartão |
processing_datetime | timestamp utc | Horário em que a requisição de autorização foi processada |
number_of_installments | int | Número de parcelas sendo autorizadas nesta requisição |
authorization_request_type | enum | Enumerador de Tipos de Requisição de Autorização |
pan_entry_mode | enum | Modos de entrada do PAN - Chip, Digitada, Tarja, Fallback, Contactless |
pin_sent | boolean | Foi inserida uma senha no terminal? |
authorization | object | Objeto Autorização detalhado em GET Autorização, presente apenas quando o tipo de autorização for incremental. |
Objeto Card
| Campo | Tipo | Descrição |
|---|---|---|
card_key | string | Chave de identificação do cartão |
account_key | string | Identificador da conta do titular |
type | string | Tipo de cartão |
card_name | string | Identificador alphanumérico do cartão |
printed_name | string | Nome impresso no cartão |
status | string | Status atual do cartão |
brand | string | Bandeira do cartão |
bin | string | BIN do cartão |
last_four_digits | string | Últimos 4 dígitos do cartão |
Tipos de Requisição de Autorização
| Enumerador | Descrição |
|---|---|
| authorization | Requisição de autorização comum |
| incremental_authorization | Requisição de autorização incremental para uma Autorização preexistente |
| partial_reversal_authorization | Autorização para realizar o estorno parcial de uma transação prévia, aparece apenas em eventos, não é autorizada explicitamente pelo cliente |
| reversal_authorization | Autorização para realizar o estorno de uma transação prévia, aparece apenas em eventos, não é autorizada explicitamente pelo cliente |
Modos de Entrada do PAN
| Enumerador | ISO 8583 | Descrição |
|---|---|---|
| unknown | 00 | PAN entry mode desconhecido. |
| typed | 01 | PAN inserido manualmente (digitado). |
| bar_code | 03 | PAN inserido por meio de leitora de código de barras |
| ocr | 04 | PAN inserido por meio de OCR (Optical Character Recognition) |
| chip | 05 | PAN inserido por cartão com circuito integrado (Chip) |
| track_1 | 06 | PAN inserido pela Track 1 do cartão de tarja |
| contactless | 07 | PAN inserido por meio de Contactless EMV |
| fallback_typed | 79 | Foi tentado utilizar o leitor de cartão ou de tarja do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então digitada o PAN. Em alguns casos a adquirente não está homologada para utilizar o CHIP ou a tarja e envia este código. |
| fallback_magnetic_stripe | 80 | Foi tentado utilizar o leitor de cartão do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então utilizada a tarja magnética do cartão. |
| ecommerce | 81 | Transação de e-commerce / não presencial |
| magnetic_stripe | 90 | Transação de tarja (Cartão não possui chip ou dispositivo não possui leitor/não foi homologado) |
Resposta de aprovação ou negação de uma requisição de autorização
A resposta à Rquisição de Autorização deverá ser sempre com HTTP Status 201 e o parecer deve ser informado no campo approve. Caso o parecer seja negativo, um enumerador de razão de negação deverá ser escolhido e é possível enviar uma descrição em texto para detalhar essa negação.
Response Body
"authorization_request_response": "unauthorized",
"denial_reason": "fraud_suspicion",
"denial_reason_details": "Customer tried to perform a transaction 10 times the average transactions"
Detalhe
| Campo | Tipo | Descrição |
|---|---|---|
authorization_request_response (required) | enumerator | authorized caso a autorização seja aprovada ou unauthorized caso a autorização seja negada |
denial_reason | enum | Enumerador Razão de Negação |
denial_reason_details | string | Deny reason details |
Enumerador Razão de Negação
| Enumerador | Descrição |
|---|---|
| fraud_suspicion | Movimentação com comportamento suspeito |
| blocked_customer | Portador com restrições |
Resposta negativa
Qualquer HTTP status que não seja 2XX será interpretado como incapacidade do cliente de processar a autorização. Será então aplicada a regra de decisão configurada no programa do cliente para os casos de indisponibilidade.
Importante: Autorizações que sejam negadas pelos critérios básicos de validação de cartões serão respondidas automaticamente pela QI sem o envio de uma requisição de autorização. O cliente receberá apenas um webhook de autorização negada.
Autorização Incremental
Uma Authorization poderá receber mais de uma Authorization Request, situação que chamamos de autorização incremental. Cada Authorization Request pode ou não ser autorizado e a entidade Authorization irá sempre representar o resultado do que for capturado com sucesso dentre as N autorizações.
Uma autorização incremental poderá ser identificada pelo campo authorization_type com valor incremental_authorization. Sempre que a requisição for deste tipo, o objeto Authorization relacionado será enviado junto ao payload da Authorization Request.