> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorization decisions
> Integrate with the Authorization Decision API to approve or decline card transactions in real time.
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
```mermaid theme={null}
sequenceDiagram
participant C as Cardholder
participant U as UQPAY
participant P as Your endpoint
C->>U: Card transaction
U->>U: Internal risk control
alt UQPAY declines
U-->>C: Transaction declined
U->>P: issuing.transaction.authorization webhook (notification only)
else UQPAY approves
U->>P: Authorization decision request (encrypted)
P->>P: Decrypt → evaluate → encrypt response
P->>U: Authorization decision response (encrypted)
U-->>C: Transaction result
end
```
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. |
```
-----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:
| 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` |
| 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 |
| 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 |
| 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 |
| 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):**
```json theme={null}
{
"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):**
```json theme={null}
{
"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:
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 IPs to add to your firewall allowlist: **Production** `18.139.246.78`, `54.251.52.172`.
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.
## Related
* [Create Card API](/card-issuance/v1.6/api-reference/create-card)
* [Transaction Authorization webhook](/card-issuance/v1.6/webhooks/transaction)