Authorization Decision API Integration Guide

This guide provides instructions for integrating with the Authorization Decision API, which allows partners to participate in transaction authorization decisions for card transactions.

Prerequisites

Only partners that have passed risk control review are eligible to configure and use this functionality.

Overview

The Authorization Decision API enables partners to make real-time authorization decisions for card transactions. When a transaction passes UQPAY's internal risk control, the transaction details are sent to your endpoint for a final authorization decision.

Decision Flow

The authorization decision process follows these key principles:

Partner Decision Authority: Partners can only make authorization decisions for transactions that have been approved by UQPAY's internal risk control. Only when UQPAY approves a transaction will the transaction details be sent to your endpoint for your decision (approve or decline).
Declined Transactions: When UQPAY declines a transaction, you will only receive a transaction notification (issuing.transaction.authorization webhook event), but you will not receive an authorization decision request.
Response Requirement: You must respond correctly to authorization decision requests within the timeout period. If no valid response is received before timeout, the transaction result will be determined by the configured default timeout result (which can be set to either approve or decline).
Timeout Configuration: The current timeout period is 5 seconds.

Security

The entire request body is encrypted before being sent to your endpoint.

PGP Key Exchange:

UQPAY and partners will exchange PGP public keys to ensure secure communication:

Key Exchange: UQPAY and partners will exchange their respective PGP public keys
Request Decryption: Partners will use their private key to decrypt the authorization decision request body sent by UQPAY
Response Encryption: Partners must encrypt the response body using UQPAY's public key before sending it back

UQPAY PGP Public Key

API Specification

Request Method

POST

Endpoint Configuration

Provide your endpoint URL to UQPAY to receive Authorization Decision request.

Request Headers

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

Request Body

The request body contains the following fields:

Field	Type	Description	Constraints	Example
`transaction_id`	string (UUID)	Unique transaction identifier		`"550e8400-e29b-41d4-a716-446655440000"`
`transaction_type`	integer	Transaction type	`1000` Authorization `1100` Transfer Out `1200` Cash Withdrawal `2000` Refund	`1000`
`card_id`	string (UUID)	Card identifier		`"550e8400-e29b-41d4-a716-446655440000"`
`processing_code`	string	Card schema process code	`00`	`"00"`
`billing_amount`	float	Billing amount		`100.50`
`transaction_amount`	float	Transaction amount		`100.00`
`auth_amount`	float	Authorization amount		`101.00`
`date_of_transaction`	string	Transaction date and time	Format: `YYYY-MM-DD HH:MM:SS`	`"2025-11-14 15:07:25"`
`billing_currency_code`	string	Billing currency code	3-character ISO code	`"SGD"`
`transaction_currency_code`	string	Transaction currency code	3-character ISO code	`"SGD"`
`auth_currency_code`	string	Authorization currency code	3-character ISO code	`"SGD"`
`card_balance`	float	Card available balance		`500.00`
`merchant_id`	string	Merchant identifier		`"MERCHANT123"`
`merchant_name`	string	Merchant name		`"Example Store"`
`merchant_category_code`	string	Merchant Category Code (MCC)		`"5411"`
`merchant_city`	string	Merchant city		`"Singapore"`
`merchant_country`	string	Merchant country	2-character ISO code	`"SG"`
`terminal_id`	string	Terminal identifier		`"TERM001"`
`pos_entry_mode`	string	Point of Sale Entry Mode	`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 integrated circuit card read using VSDC chip data rules `07` Contactless device-read-originated using qVSDC chip data rules `10` Credential on file `90` Magnetic stripe read and exact content of Track 1 or Track 2 included (CVV check possible) `91` Contactless device-read-originated using magnetic stripe data rules `95` Integrated circuit card read; CVV or iCVV checking may not be possible	`"05"`
`pos_condition_code`	string	Transaction condition code	`00` Normal transaction of this type `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/anticipated amount/account verification without authorization; product eligibility inquiry without authorization `59` E-commerce request by public network	`"00"`
`pin_entry_capability`	string	PIN Entry Capability	`0` Unknown `1` Terminal can accept and forward online PINs `2` Terminal cannot accept and forward online PINs `8` Terminal PIN pad down	`"1"`
`retrieval_reference_number`	string	Retrieval Reference Number (RRN), 12 digits	12 digits	`"123456789012"`
`system_trace_audit_number`	string	System Trace Audit Number (STAN), 6 digits	6 digits	`"123456"`
`acquiring_institution_country_code`	string	Acquiring institution country code	2-character ISO code	`"SG"`
`acquiring_institution_id`	string	Acquiring institution identifier		`"ACQ001"`
`wallet_type`	string	Wallet type	`"APPLE"` `"SAMSUNG"` `"GOOGLE"` `"GOOGLE ECOMMERCE"` `"GOOGLE PAY"` `"MI PAY"` `"Garmin Pay"` `"ECOMMERCE"`	`"APPLE"`

Example Request Body:

{
  "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",
  "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 Body

You must respond with HTTP status code 200 and the following structure. The response body must be encrypted using UQPAY's public key before sending.

Field	Type	Description	Example
`transaction_id`	string (UUID)	Transaction identifier (must match the `transaction_id` from the request body, otherwise UQPAY will decline the transaction)	`"550e8400-e29b-41d4-a716-446655440000"`
`response_code`	string	Authorization response code	`"00"`
`partner_reference_id`	string	Your internal reference ID for reconciliation purposes (optional, can be empty string)	`"550e8400-e29b-41d4-a716-446655440002"` or `""`

Example Response Body:

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "response_code": "00",
  "partner_reference_id": ""
}

Response Codes

The authorization decision is determined by the HTTP status code and the response_code field:

Approved: HTTP status code 200 AND response_code = "00" AND the transaction_id in the response matches the transaction_id in the request
Declined: All non-APPROVED cases will be declined
Timeout: If no response is received within the timeout period, the transaction result will be determined by the configured default timeout result (approve or decline)

Available response_code values:

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

Integration Steps

Contact UQPAY: Reach out to UQPAY to enable the Authorization Decision API feature.
Exchange Configuration Information:
- Provide your endpoint URL to receive Authorization Decision requests
- Exchange PGP public keys with UQPAY (provide yours and save UQPAY's)
- Add UQPAY's egress IP to your firewall whitelist:
  - Production: 18.139.246.78
Implement Endpoint: Implement a POST endpoint that:
- Accepts encrypted JSON request bodies
- Decrypts the request body using your private key
- Processes the transaction authorization decision based on your business logic
- Encrypts the response using UQPAY's public key
- Returns the encrypted response within the timeout period with the required structure
Handle Timeout: Ensure your endpoint responds within the timeout period.
Test Integration: Work with UQPAY to test the integration and verify that requests and responses are processed correctly.

Important Notes

You only receive authorization requests for transactions that have passed UQPAY's internal risk control checks.
Transactions declined by UQPAY will not be sent to your endpoint for decision.
You must respond within the timeout period with your authorization decision. If no response is received before timeout, the transaction result will be determined by the configured default timeout result (which can be set to either approve or decline).
Ensure you have properly integrated and tested the integration before going live. Transactions will be declined if you fail to respond correctly to authorization decision requests.