Skip to main content
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:
DirectionEncryption
UQPAY → You (request)Encrypted with your public key. Decrypt with your private key.
You → UQPAY (response)Encrypt with UQPAY’s public key before sending.
-----BEGIN PGP PUBLIC KEY BLOCK-----

mQENBGkIsmwBCADUvVdRpSMTnhZ9/hfzkDmmChj/2DwcRLg2YB4/wA2pCwSSYdh9
LmFWdHk5OYe41a6H0z3Bc0C5PUp3dU2V9D1rZMBJkSOb8kSCprfh6ayegp8O3hX8
Q2CCveakh8vB+UkRkKumLXBcMasraUCXTOdQ4m9KKO3zSC16nJIT907Uo1973y1/
LqkWzkBUgDAjUpH/YocCo2jzAh6Uz90zoRQWJK4i8iTfBciALqgZTSSmuN/rEZ5z
5BM5AK2dA4D0LJ8Cr7R9Y8eHdsZrDrPpGoIDbyY/9wvpDLnxZc+SRihKUu2RWxNt
PFpjOkEl9AXkqU5N7LccAHnYnP1HAXAcSsjPABEBAAG0HlVRUEFZIDxpc3N1aW5n
LnRlY2hAdXFwYXkuY29tPokBUQQTAQgAOxYhBMzRRL71/SkUZCFtKL6p85GBc+r+
BQJpCLJsAhsDBQsJCAcCAiICBhUKCQgLAgQWAgMBAh4HAheAAAoJEL6p85GBc+r+
Ev4IAI2CGpMHHcTitO9V+Lf5c4BmXtNlHqnsqFQNVMrIfgt9re9dWCyvKxaCFCLK
cfw5Vjugt/qz7Wl63NpJpDhAl+eO+cZfYzYY5Tb/VHAKzihOFpAlKtPw1fhdANUC
LB1aGGq+cHsbltr7sBD1OuHUi95rKskr3jctd6lp97B6qFtqc58sChk7JoikJMqw
NybHIoyVjCKHWj0jBw+qppB4+IcfS3HXxGxGzy7iIAeB0wQX54OohMXJHgdopPuO
xufTif6dZbw1g0NwzWekirghf4BUW76WNDPR2BxD/zE3fxgoh7Mid1IC855JiHXW
SnEaB1XsBF/faGotMRpX8t7+H0a5AQ0EaQiybAEIALhicwMCb9nwReS91HUU2yC+
Xu7Ay3gd5/8xX9EC63XqzvFSE83OVzKOEEE9sGsvKQcCLKOoBksfPtnaZqek/mix
/ChNSHFZK5+UrZpsMgFNeUBYQg5zcX/w8T91WZJllmYjEdglzh89Gp82zwzF3Wmt
gB+c2/3hYBxuKXjhW5x5xSli8nCz2hxWLouXiNqfqBHUDJIHJQO2Nrms7FVp8S4Y
dXlDxJfJodn8JL8PIpuHyEV2+2BWADQrM+qxkyfcFbqpVEyGad8kMB2G10gOWM/f
3sZEQ238G/q7odEKsY5BVpYaPTL1PfpxEkq69oYkCfcdRCXZxj7dhqyDkzn0wXEA
EQEAAYkBNgQYAQgAIBYhBMzRRL71/SkUZCFtKL6p85GBc+r+BQJpCLJsAhsMAAoJ
EL6p85GBc+r+tM4IAI3P4yLnVR21DysTjlOueZVv75zJnjYTMHmS2BTIYVcwYCWX
n+Fjqn5ylxwuql53SjENavi543GzZ31z8w6wWVICS36WhGG6tpy5VOFzomqj1hAN
1lOPY3ADwCtphV4Cn21WbhA/MGF+l9rIVoVuMLdmug/wOeM2VkzVlnGJPhr+RFPE
L+6wV3UFP68uk3nGshwj09roeKZV/wRfCmJhnNt2ufQzl2FbtlbSP8xBIprW0xnf
UBqR1Wp4Lg0hCKWRgRFftMjqDz51iBWbxsdkF7GCMWuv7ko3THaYSDMcsxGndOTd
P8G2/doToAnlb3vozoRN/7uW7yIhpAL4PWJkzfU=
=4/ki
-----END PGP PUBLIC KEY BLOCK-----

​
API specification

​
Request

UQPAY sends a POST request to your configured endpoint with these headers:
HeaderDescription
Content-Typeapplication/json; charset=utf-8
x-request-idUnique UUID for each request
The decrypted request body contains:
FieldTypeDescription
transaction_idstring (UUID)Unique transaction identifier
transaction_typeinteger1000 Authorization, 1100 Transfer Out, 1200 Cash Withdrawal, 2000 Refund
card_idstring (UUID)Card identifier
processing_codestringCard schema process code
billing_amountfloatBilling amount
transaction_amountfloatTransaction amount
auth_amountfloatAuthorization amount
date_of_transactionstringFormat: YYYY-MM-DD HH:MM:SS
billing_currency_codestring3-character ISO currency code
transaction_currency_codestring3-character ISO currency code
auth_currency_codestring3-character ISO currency code
card_balancefloatCard available balance
merchant_idstringMerchant identifier
merchant_namestringMerchant name
merchant_category_codestringMCC
merchant_citystringMerchant city
merchant_countrystring2-character ISO country code
terminal_idstringTerminal identifier
pos_entry_modestringPOS entry mode (see below)
pos_condition_codestringTransaction condition code (see below)
pin_entry_capabilitystring0 Unknown, 1 Can accept PIN, 2 Cannot accept PIN, 8 PIN pad down
retrieval_reference_numberstringRRN, 12 digits
system_trace_audit_numberstringSTAN, 6 digits
acquiring_institution_country_codestring2-character ISO country code
acquiring_institution_idstringAcquiring institution identifier
wallet_typestringAPPLE, SAMSUNG, GOOGLE, GOOGLE ECOMMERCE, GOOGLE PAY, MI PAY, Garmin Pay, ECOMMERCE
CodeDescription
00Unknown or terminal not used
01Manual (key entry)
02Magnetic stripe read; CVV checking may not be possible
03Optical code
05Contact ICC read using VSDC chip data rules
07Contactless device read using qVSDC chip data rules
10Credential on file
90Magnetic stripe read with exact Track 1/2 content (CVV check possible)
91Contactless device read using magnetic stripe data rules
95ICC read; CVV or iCVV checking may not be possible
CodeDescription
00Normal transaction
01Customer not present
02Unattended cardholder-activated environment, PIN data present
03Merchant suspicious of transaction (or card)
05Customer present, card not present
06Preauthorized request
08Mail, telephone, recurring, advance, or installment order
51Address/CVV2/account verification without authorization
59E-commerce request by public network
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",
  "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:
FieldTypeDescription
transaction_idstring (UUID)Must match the request’s transaction_id, otherwise the transaction is declined
response_codestringAuthorization response code (see table below)
partner_reference_idstringYour 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

CodeDescription
00Approved
04Picked Card
05Do Not Honor
06Error
13Invalid Amount
14Invalid Account Number
43Stolen Card
51Insufficient Funds
59Suspected Fraud
65Activity Count Limit Exceeded
The transaction is approved only when all three conditions are met:
  1. HTTP status code is 200
  2. response_code is "00"
  3. transaction_id matches the request
All other cases result in a decline.

​
Integration steps

  1. Contact UQPAY — Reach out to UQPAY to enable the Authorization Decision API feature for your account.
  2. 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 IP to add to your firewall allowlist: Production 18.139.246.78.
  3. 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.
  4. 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.