Authorization decisions

Business Visa & Personal Visa only The Authorization Decision API lets you make real-time approve/decline decisions on card transactions. When a transaction passes UQPAY’s internal risk controls, the transaction details are forwarded to your endpoint for a final decision.

Prerequisites

Pass UQPAY’s risk control review to enable the feature
A publicly accessible HTTPS endpoint to receive authorization requests
PGP key pair for request/response encryption

How it works

Key principles:

You only receive authorization requests for transactions that have already passed UQPAY’s risk controls.
Transactions declined by UQPAY are not sent to your endpoint — you receive only the issuing.transaction.authorization webhook notification.
You must respond within the configured timeout period (1 to 5 seconds, set per your agreement with UQPAY). If no valid response is received, the transaction result is determined by your configured default timeout action (approve or decline).

Security: PGP encryption

The entire request and response body is PGP-encrypted. Before integration, you and UQPAY exchange PGP public keys:

Direction	Encryption
UQPAY → You (request)	Encrypted with your public key. Decrypt with your private key.
You → UQPAY (response)	Encrypt with UQPAY’s public key before sending.

UQPAY PGP public key

API specification

Request

UQPAY sends a POST request to your configured endpoint with these headers:

Header	Description
`Content-Type`	`application/json; charset=utf-8`
`x-request-id`	Unique UUID for each request

The decrypted request body contains:

Field	Type	Description
`transaction_id`	string (UUID)	Unique transaction identifier
`transaction_type`	integer	`1000` Authorization, `1100` Transfer Out, `1200` Cash Withdrawal, `2000` Refund
`card_id`	string (UUID)	Card identifier
`processing_code`	string	Card schema process code
`billing_amount`	float	Billing amount
`transaction_amount`	float	Transaction amount
`auth_amount`	float	Authorization amount
`date_of_transaction`	string	Format: `YYYY-MM-DD HH:MM:SS`
`billing_currency_code`	string	3-character ISO currency code
`transaction_currency_code`	string	3-character ISO currency code
`auth_currency_code`	string	3-character ISO currency code
`card_balance`	float	Card available balance
`merchant_id`	string	Merchant identifier
`merchant_name`	string	Merchant name
`merchant_category_code`	string	MCC
`merchant_city`	string	Merchant city
`merchant_country`	string	2-character ISO country code
`terminal_id`	string	Terminal identifier
`pos_entry_mode`	string	POS entry mode (see below)
`pos_condition_code`	string	Transaction condition code (see below)
`pos_env`	string	POS environment — use to identify credential-on-file, installment, and recurring (subscription) transactions (see below)
`eci`	string	Mail/phone, e-commerce, and payment indicator (see below)
`pin_entry_capability`	string	`0` Unknown, `1` Can accept PIN, `2` Cannot accept PIN, `8` PIN pad down
`retrieval_reference_number`	string	RRN, 12 digits
`system_trace_audit_number`	string	STAN, 6 digits
`acquiring_institution_country_code`	string	2-character ISO country code
`acquiring_institution_id`	string	Acquiring institution identifier
`wallet_type`	string	`APPLE`, `SAMSUNG`, `GOOGLE`, `GOOGLE ECOMMERCE`, `GOOGLE PAY`, `MI PAY`, `Garmin Pay`, `ECOMMERCE`

POS entry mode values

Code	Description
`00`	Unknown or terminal not used
`01`	Manual (key entry)
`02`	Magnetic stripe read; CVV checking may not be possible
`03`	Optical code
`05`	Contact ICC read using VSDC chip data rules
`07`	Contactless device read using qVSDC chip data rules
`10`	Credential on file
`90`	Magnetic stripe read with exact Track 1/2 content (CVV check possible)
`91`	Contactless device read using magnetic stripe data rules
`95`	ICC read; CVV or iCVV checking may not be possible

POS condition code values

Code	Description
`00`	Normal transaction
`01`	Customer not present
`02`	Unattended cardholder-activated environment, PIN data present
`03`	Merchant suspicious of transaction (or card)
`05`	Customer present, card not present
`06`	Preauthorized request
`08`	Mail, telephone, recurring, advance, or installment order
`51`	Address/CVV2/account verification without authorization
`59`	E-commerce request by public network

POS environment values

Code	Description
`C`	Credential on file (for initial storage) / unscheduled card on file (for subsequent merchant-initiated transactions)
`I`	Installment payment
`R`	Recurring — the cardholder and merchant have agreed to periodic billing for goods and services, such as utility bills and magazines

ECI (mail/phone/e-commerce and payment indicator) values

Code	Description
`00`	Not applicable
`01`	Single transaction of a mail/phone order
`02`	Recurring transaction
`03`	Installment payment
`04`	Unknown classification
`05`	Secure electronic commerce transaction
`06`	Non-authenticated security transaction at a 3-D Secure-capable merchant, and the merchant attempted to authenticate the cardholder using 3-D Secure
`07`	Non-authenticated security transaction
`08`	Non-secure transaction

Example request body (decrypted):

{
  "transaction_id": "7ae57f4d-930d-41b9-83a8-4274f6a23a3b",
  "transaction_type": 1000,
  "card_id": "b3dd7e47-f8b7-4790-aa47-a0e37bae7757",
  "processing_code": "00",
  "billing_amount": "2.31",
  "transaction_amount": "2.31",
  "billing_currency_code": "SGD",
  "transaction_currency_code": "CAD",
  "auth_currency_code": "USD",
  "auth_amount": "0",
  "date_of_transaction": "2025-11-14 15:07:25",
  "card_balance": "90085.59",
  "merchant_category_code": "5972",
  "merchant_id": "CARD ACCEPTOR  ",
  "terminal_id": "TERMID01",
  "merchant_country": "US",
  "merchant_name": "ACQUIRER NAME",
  "merchant_city": "CITY NAME",
  "pos_entry_mode": "01",
  "pos_condition_code": "08",
  "pos_env": "R",
  "eci": "02",
  "pin_entry_capability": "2",
  "retrieval_reference_number": "529430718653",
  "system_trace_audit_number": "000653",
  "acquiring_institution_country_code": "TK",
  "acquiring_institution_id": "30954284708",
  "wallet_type": "GOOGLE ECOMMERCE"
}

Response

Respond with HTTP 200 and the following JSON body, encrypted with UQPAY’s PGP public key:

Field	Type	Description
`transaction_id`	string (UUID)	Must match the request’s `transaction_id`, otherwise the transaction is declined
`response_code`	string	Authorization response code (see table below)
`partner_reference_id`	string	Your internal reference ID for reconciliation (optional, can be empty)

Example response body (before encryption):

{
  "transaction_id": "7ae57f4d-930d-41b9-83a8-4274f6a23a3b",
  "response_code": "00",
  "partner_reference_id": ""
}

Response codes

Code	Description
`00`	Approved
`04`	Picked Card
`05`	Do Not Honor
`06`	Error
`13`	Invalid Amount
`14`	Invalid Account Number
`43`	Stolen Card
`51`	Insufficient Funds
`59`	Suspected Fraud
`65`	Activity Count Limit Exceeded

The transaction is approved only when all three conditions are met:

HTTP status code is 200
response_code is "00"
transaction_id matches the request

All other cases result in a decline.

Integration steps

Contact UQPAY — Reach out to UQPAY to enable the Authorization Decision API feature for your account.
Exchange configuration — Provide the following to UQPAY:
- Your PGP public key (RSA 2048-bit)
- Your authorization decision endpoint URL (HTTPS)
- Decision timeout window (1 to 5 seconds; defaults to 2 seconds)
- Default timeout action: decline (auto-decline on timeout) or delegate (UQPAY decides on your behalf)
UQPAY will provide their PGP public key (see above) and the egress IPs to add to your firewall allowlist: Production 18.139.246.78, 54.251.52.172.
Implement your endpoint — Build a POST endpoint that decrypts the request body using your PGP private key, evaluates the transaction based on your business logic, encrypts the response using UQPAY’s public key, and returns the encrypted response within the configured timeout period.
Test the integration — Work with UQPAY to run test transactions in the sandbox environment and verify correct encryption, decryption, and response handling.

Transactions are declined if your endpoint fails to respond correctly, including malformed responses, mismatched transaction_id, or responses received after the timeout. Test thoroughly before going live.

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

How it works

Security: PGP encryption

API specification

Request

Response

Response codes

Integration steps

​How it works

​Security: PGP encryption

​API specification

​Request

​Response

​Response codes

​Integration steps

​Related

How it works

Security: PGP encryption

API specification

Request

Response

Response codes

Integration steps

Related