Authorization Request

---

Once the program is set up, the cardholder has been added and has an active card, which can be used to make purchases at various points of sale around the world. Whenever a purchase is started, an Authorization is created to authorize it. An Authorization Request is forwarded to the integration partner, so that it can decide whether or not to approve this authorization based on the information contained within the request.

The Authorization entity contains the current state of the authorized and captured values and can assume the following status values:

Status	Description
pending	Authorization request was authorized and no capture or reversal events were processed
unauthorized	Authorization request was not approved
completed	Authorization with at least one captured value (equal to, less than, or greater than the total authorized amount)
reversed	Authorization was voided in full or expired without capture

Authorization details can be found at Retrieve Authorization.

The Authorization Request contains Authentication Headers and has the following attributes:

Authorization Request

ENDPOINT

(client_url)/authorization_request

METHOD

POST

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_request_type": "authorization",
	"pan_entry_mode": "chip",
	"pin_sent": true,
	"authorization": {Authorization Object}
}

Authorization Request

Field	Type	Description
authorization_request_key	string	Authorization request unique identifier
authorization_key	string	Authorization unique identifier
card	object	Object Card
terminal_id	string	The terminal identifier sent by the acquirer in the authentication message
terminal_country_code	string	The country code of the terminal, sent in the authorization message according to ISO 3166-1 alpha-3
terminal_type	string	The endpoint type as received in the authorization message
terminal_pin_entry_capability	boolean	Is there a possibility to enter the card password in the terminal?
terminal_magnetic_stripe_capability	boolean	Is the terminal capable of reading the magnetic stripe?
terminal_contactless_capability	boolean	Is the terminal capable of initiating contactless transactions?
terminal_chip_capability	boolean	Is the terminal capable of initiating transactions using the EMV chip?
merchant_acquirer_code	string	The acquirer's identifier as per the authorization message
merchant_code	string	The identifier of the merchant in the acquirer according to the authorization message
merchant_name	string	The name of the merchant according to the authorization message
merchant_street	string	Merchant's address street
merchant_city	string	Merchant's address city
merchant_region	string	Merchant's address region
merchant_postal_code	string	Merchant's address postal code
merchant_mcc	string	Merchant's category code - Updated list can be found here
authorization_code	string	6-digit authorization code
nsu	string	Unique sequential number that defines an authorization
acquirer_reference_number	string	Unique identifier of the authorization in the acquirer
merchant_currency_code	string	The currency used by the merchant - ISO 4217-alpha
merchant_amount	decimal	Authorization amount in the merchant's currency
billing_currency_code	string	The cardholder's billing currency - ISO 4217-alpha
billing_amount	decimal	Authorization amount in cardholder's billing currency
processing_datetime	timestamp utc	Authorization's processing time
number_of_installations	int	Number of installments
authorization_request_type	enum	Enumerator of Authorization Request Types
pan_entry_mode	enum	PAN Input Modes - Chip, Typed, Stripe, Fallback, Contactless
pin_sent	boolean	Was a PIN entered in the terminal?
authorization	object	Authorization object in Retrieve Authorization - presented only when the type of the authorization request is incremental

Card Object

Field	Type	Description
card_key	string	Card unique identifier
account_key	string	Card linked account unique identifier
type	string	Card type
card_name	string	Card name
printed_name	string	Name printed on card
status	string	Current card status
brand	string	Card network name
bin	string	Card BIN
last_four_digits	string	Card's last four digits

Authorization Request Types

Enumerator	Description
authorization	Normal authorization request
incremental_authorization	Incremental authorization request
partial_reversal_authorization	Authorization to perform a partial reversal of a previous authorized Authorization
reversal_authorization	Authorization to fully reverse a previous Authorization

PAN Input Modes

Enumerator	ISO 8583	Description
unknown	00	PAN entry mode unknown.
typed	01	PAN entered manually (typed).
bar_code	03	PAN entered via barcode reader
ocr	04	PAN entered via OCR (Optical Character Recognition)
chip	05	PAN inserted by integrated circuit card (Chip)
track_1	06	PAN inserted by Track 1 of the stripe card
contactless	07	PAN entered via Contactless EMV
fallback_typed	79	An attempt was made to use the card or stripe reader on the device and the card but it was not possible to process the transaction with that information (Possibly a problem with the device or the card), so the PAN was entered. In some cases, the acquirer is not approved to use the CHIP or the stripe and sends this code.
fallback_magnetic_stripe	80	An attempt was made to use the card reader on the device and the card but it was not possible to process the transaction with that information (Possibly a problem with the device or the card), so the magnetic stripe on the card was used.
ecommerce	81	E-commerce / non-face-to-face transaction
magnetic_stripe	90	Stripe transaction (Card does not have a chip or device does not have a reader/was not approved)

Approve or deny response to an authorization request

The response to the Authorization Request must be always a HTTP Status 201 and the decision must be informed in the authorization_request_response attribute. If the decision is negative, a denial reason enumerator must be informed and the denial details can be provided.

ENDPOINT

(client_url)/authorization_request

METHOD

POST

HTTP STATUS

201

Response Body

{
    "approve": false,
    "denial_reason": "fraud_suspicion",
    "denial_reason_details": "Customer tried to perform a transaction 10 times the average transactions"
}

Detail

Field	Type	Description
authorization_request_response (required)	enumerator	authorized if the authorization is approved or unauthorized if the authorization is denied
denial_reason	enum	Denial Reason Enumerator
denial_reason_details	string	Denial reason details

Denial Reason Enumerator

Enumerator	Description
fraud_suspicion	Authorization request with suspicious behavior
blocked_cardholder	Cardholder blocked or with restrictions

Negative answer

Any HTTP status other than 201 will be interpreted as the client's inability to process the authorization. The decision rule configured in the client program will then be applied for cases of unavailability.

Important: Authorizations that are denied by the default card validation rules are automatically responded to the card network (Visa) by QI without forwarding the authorization request to the integration partner.

Incremental Authorization

An Authorization may receive more than one Authorization Request- the second and greater are called incremental authorizations. Each Authorization Request may or may not be authorized and the Authorization entity always represents the result of all authorized responses to Authorization Requests.

An incremental authorization can be identified by the authorization_type field with value incremental_authorization. Whenever the request is of this type, the related Authorization object will be sent together with the Authorization Request payload.