> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waypay.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Transaction/Order Status

> Retrieve transaction details using payment intent ID, order reference, or transaction reference

## Overview

Retrieve detailed information about a specific transaction using one of three identifiers: the payment intent ID, your merchant order reference, or the Waypay transaction reference. This flexibility allows you to query transactions using whichever identifier is most convenient for your system.

## Path Parameters

<ParamField path="identifier" type="string" required>
  Transaction identifier - can be one of three types:

  You can provide any of the following:

  * **Payment Intent ID** - The UUID returned when creating a payment (e.g., `550e8400-e29b-41d4-a716-446655440000`)
  * **Merchant Order Reference** - Your `orderRef` provided when creating the transaction (e.g., `ORD123456`)
  * **Transaction Reference** - The `txnRef` returned by Waypay (e.g., `WP20251212123456`)

  <Tip>
    **Recommended:** Use your merchant order reference for the easiest integration with your existing systems.
  </Tip>
</ParamField>

<ParamField path="version" type="string" required>
  API version (e.g., "1")
</ParamField>

## Response

<ResponseField name="id" type="uuid">
  Unique transaction identifier
</ResponseField>

<ResponseField name="amount" type="number">
  Transaction amount
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (e.g., "PKR", "USD")
</ResponseField>

<ResponseField name="fee" type="number">
  Transaction processing fee
</ResponseField>

<ResponseField name="netAmount" type="number">
  Net amount after fees
</ResponseField>

<ResponseField name="txType" type="integer">
  Transaction type:

  * `0` - CardDeposit (Deposit)
  * `1` - WalletDeposit
  * `2` - Transfer
  * `3` - Withdrawal
  * `4` - WalletWithdrawal
  * `5` - Fee
  * `6` - Reversal (Reversed)
  * `7` - Settlement
  * `8` - Refund
</ResponseField>

<ResponseField name="txnType" type="string">
  Transaction type description (e.g., "Deposit", "WalletDeposit", "Withdrawal")
</ResponseField>

<ResponseField name="description" type="string">
  Transaction description
</ResponseField>

<ResponseField name="transactionNotes" type="string">
  Additional transaction notes
</ResponseField>

<ResponseField name="txnprovider" type="string">
  Payment provider used
</ResponseField>

<ResponseField name="txnRef" type="string">
  Transaction reference number
</ResponseField>

<ResponseField name="status" type="integer">
  Transaction status:

  * `1` - Pending
  * `2` - Completed
  * `3` - Failed
  * `4` - Cancelled
  * `5` - RefundRequested
  * `6` - RefundFailed
  * `7` - Refunded
  * `8` - InProgress
  * `9` - OnHold
  * `10` - Reversed
  * `11` - Disputed
  * `12` - Settled
</ResponseField>

<ResponseField name="statusText" type="string">
  Human-readable status description (e.g., "Pending", "Completed", "Failed")
</ResponseField>

<ResponseField name="createdAtUtc" type="datetime">
  Transaction creation timestamp (UTC)
</ResponseField>

<ResponseField name="isLive" type="boolean">
  Whether this is a live or test transaction
</ResponseField>

<ResponseField name="transactionMode" type="string">
  Transaction mode (e.g., "Live", "Test")
</ResponseField>

<ResponseField name="merchantOrderRef" type="string">
  Your merchant order reference (the orderRef you provided)
</ResponseField>

<ResponseField name="paymentIntentId" type="uuid">
  Payment intent identifier
</ResponseField>

<ResponseField name="appliedFeeRuleName" type="string">
  Name of the fee rule applied to this transaction
</ResponseField>

<ResponseField name="feeCalculationBreakdown" type="string">
  Detailed breakdown of how the fee was calculated
</ResponseField>

<RequestExample>
  ```bash cURL (by Payment Intent ID) theme={null}
  curl --request GET \
    --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/550e8400-e29b-41d4-a716-446655440000 \
    --header 'SWICH-API-Key: pk_test_xxxxxxxx'
  ```

  ```bash cURL (by Order Reference) theme={null}
  curl --request GET \
    --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/ORD123456 \
    --header 'SWICH-API-Key: pk_test_xxxxxxxx'
  ```

  ```bash cURL (by Transaction Reference) theme={null}
  curl --request GET \
    --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/WP20251212123456 \
    --header 'SWICH-API-Key: pk_test_xxxxxxxx'
  ```

  ```javascript Node.js (by Payment Intent ID) theme={null}
  const response = await fetch(
    'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/550e8400-e29b-41d4-a716-446655440000',
    {
      method: 'GET',
      headers: {
        'SWICH-API-Key': 'pk_test_xxxxxxxx'
      }
    }
  );

  const data = await response.json();
  ```

  ```javascript Node.js (by Order Reference) theme={null}
  const response = await fetch(
    'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/ORD123456',
    {
      method: 'GET',
      headers: {
        'SWICH-API-Key': 'pk_test_xxxxxxxx'
      }
    }
  );

  const data = await response.json();
  ```

  ```javascript Node.js (by Transaction Reference) theme={null}
  const response = await fetch(
    'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/WP20251212123456',
    {
      method: 'GET',
      headers: {
        'SWICH-API-Key': 'pk_test_xxxxxxxx'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python (by Payment Intent ID) theme={null}
  import requests

  response = requests.get(
      'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/550e8400-e29b-41d4-a716-446655440000',
      headers={'SWICH-API-Key': 'pk_test_xxxxxxxx'}
  )
  ```

  ```python Python (by Order Reference) theme={null}
  import requests

  response = requests.get(
      'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/ORD123456',
      headers={'SWICH-API-Key': 'pk_test_xxxxxxxx'}
  )
  ```

  ```python Python (by Transaction Reference) theme={null}
  import requests

  response = requests.get(
      'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/WP20251212123456',
      headers={'SWICH-API-Key': 'pk_test_xxxxxxxx'}
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 1000.00,
    "currency": "PKR",
    "fee": 25.00,
    "netAmount": 975.00,
    "txType": 1,
    "txnType": "WalletDeposit",
    "description": "Product Purchase",
    "transactionNotes": "Payment completed successfully",
    "txnprovider": "JazzCash",
    "txnRef": "WP20251212123456",
    "status": 2,
    "statusText": "Completed",
    "createdAtUtc": "2025-12-12T10:30:00Z",
    "isLive": false,
    "transactionMode": "Test",
    "merchantOrderRef": "ORD123456",
    "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
    "appliedFeeRuleName": "Standard Fee",
    "feeCalculationBreakdown": "2.5% of 1000.00 = 25.00"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
    "title": "Not Found",
    "status": 404,
    "detail": "Transaction not found"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Bad Request",
    "status": 400,
    "detail": "Invalid transaction reference format"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Invalid or missing API key"
  }
  ```
</ResponseExample>

## Query by Payment Intent ID, Order Reference, or Transaction Reference

This endpoint supports querying transactions using three types of identifiers, giving you maximum flexibility:

### Payment Intent ID (paymentIntentId)

* **What it is:** A UUID generated by Waypay when you create any payment, deposit, or withdrawal order
* **Format:** UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`)
* **Where to get it:** Returned immediately in the API response when creating a transaction
* **Use case:** Query transactions right after creation using the payment intent ID you just received

### Merchant Order Reference (orderRef)

* **What it is:** Your own order reference that you provided when creating the transaction
* **Format:** Your custom format (e.g., `ORD123456`, `ORDER-2025-001`, `INV-2025-12345`)
* **Where to get it:** From your own system/database
* **Use case:** Query transactions using your internal order tracking system without storing Waypay IDs

### Transaction Reference (txnRef)

* **What it is:** A unique reference generated by Waypay after the transaction is processed
* **Format:** Waypay's format (e.g., `WP20251212123456`)
* **Where to get it:** Returned in webhook notifications and transaction details
* **Use case:** Query transactions when you have the Waypay transaction reference from webhooks or receipts

<Note>
  **Recommended Approach:** Use your merchant order reference (orderRef) for the easiest integration. This allows you to query transactions without storing any Waypay-generated identifiers.
</Note>

### Which Identifier Should You Use?

| Identifier                | Best For                                             | Availability                           | Format             |
| ------------------------- | ---------------------------------------------------- | -------------------------------------- | ------------------ |
| **Payment Intent ID**     | Immediate status checks after creating a transaction | Available instantly in API response    | UUID               |
| **Order Reference**       | Integration with existing order management systems   | Always available (you provide it)      | Your custom format |
| **Transaction Reference** | Webhook processing and customer receipts             | Available after transaction processing | Waypay format      |

## Response Fields Explained

### Transaction Types (txType)

The `txType` field indicates what type of transaction this is:

| Value | Type             | Description                                       |
| ----- | ---------------- | ------------------------------------------------- |
| 0     | CardDeposit      | Customer payment via card (displays as "Deposit") |
| 1     | WalletDeposit    | Payment via mobile wallet                         |
| 2     | Transfer         | Internal transfer between accounts                |
| 3     | Withdrawal       | Bank withdrawal/disbursement                      |
| 4     | WalletWithdrawal | Mobile wallet withdrawal                          |
| 5     | Fee              | Transaction processing fee                        |
| 6     | Reversal         | Transaction reversal (displays as "Reversed")     |
| 7     | Settlement       | Merchant settlement payout                        |
| 8     | Refund           | Money returned to customer                        |

### Transaction Status (status)

The `status` field shows the current state of the transaction:

| Value | Status          | Description                                      |
| ----- | --------------- | ------------------------------------------------ |
| 1     | Pending         | Transaction initiated, awaiting processing       |
| 2     | Completed       | Transaction completed successfully               |
| 3     | Failed          | Transaction failed                               |
| 4     | Cancelled       | Transaction cancelled by user or system          |
| 5     | RefundRequested | Refund has been requested                        |
| 6     | RefundFailed    | Refund attempt failed                            |
| 7     | Refunded        | Transaction has been refunded                    |
| 8     | InProgress      | Transaction is currently being processed         |
| 9     | OnHold          | Transaction temporarily on hold                  |
| 10    | Reversed        | Transaction has been reversed                    |
| 11    | Disputed        | Transaction is under dispute                     |
| 12    | Settled         | Transaction has been settled to merchant account |

## Best Practices

* **Use Order Reference**: Query by your `orderRef` for the easiest integration - no need to store Waypay identifiers
* **Store Payment Intent ID**: If you need immediate status checks, save the `paymentIntentId` returned from transaction creation
* **Poll Wisely**: Don't poll too frequently. Use webhooks for real-time updates instead
* **Handle 404s**: A 404 response means the identifier doesn't exist or you don't have access to it
* **Store Transaction IDs**: Save the `id` field from responses for your records and reconciliation
* **Check Status**: Always verify the `status` field before processing the transaction
* **Fee Transparency**: Use `feeCalculationBreakdown` to understand fee calculations
* **Reconciliation**: Use `merchantOrderRef` to match transactions with your orders
* **Live vs Test**: Check `isLive` to distinguish between production and test transactions
* **Choose the Right Identifier**: Use payment intent ID for immediate checks, order reference for long-term tracking

## Use Cases

<AccordionGroup>
  <Accordion title="Immediate Status Check After Payment Creation">
    Check transaction status immediately after creating a payment using the payment intent ID.

    ```javascript theme={null}
    // Step 1: Create payment
    const paymentResponse = await createPayment({
      amount: 1000,
      orderRef: { orderRef: 'ORD123456' },
      description: 'Product Purchase'
    });

    // Step 2: Immediately check status using payment intent ID
    const transaction = await getTransactionByRef(paymentResponse.paymentIntentId);
    console.log(`Payment ${paymentResponse.paymentIntentId} status: ${transaction.statusText}`);
    ```
  </Accordion>

  <Accordion title="Order Status Page">
    Display transaction status to customers on your order status page by querying with your order reference.

    ```javascript theme={null}
    const orderRef = 'ORD123456'; // From your database
    const transaction = await getTransactionByRef(orderRef);
    console.log(`Order ${orderRef} status: ${transaction.statusText}`);
    ```
  </Accordion>

  <Accordion title="Webhook Verification">
    Verify webhook notifications by querying the transaction using the txnRef from the webhook payload.

    ```javascript theme={null}
    function handleWebhook(webhookData) {
      const txnRef = webhookData.data.TransactionReference;
      const transaction = await getTransactionByRef(txnRef);
      // Verify the webhook data matches the actual transaction
      if (transaction.status === 2) { // Completed
        fulfillOrder(transaction.merchantOrderRef);
      }
    }
    ```
  </Accordion>

  <Accordion title="Reconciliation">
    Match transactions with your internal orders for accounting and reconciliation.

    ```javascript theme={null}
    const internalOrders = await getOrdersFromDatabase();
    for (const order of internalOrders) {
      const transaction = await getTransactionByRef(order.orderRef);
      await updateOrderStatus(order.id, transaction.status);
    }
    ```
  </Accordion>

  <Accordion title="Customer Support">
    Look up transaction details when customers contact support with their order number.

    ```javascript theme={null}
    const customerOrderNumber = 'ORD123456';
    const transaction = await getTransactionByRef(customerOrderNumber);
    console.log(`Transaction Status: ${transaction.statusText}`);
    console.log(`Amount: ${transaction.amount} ${transaction.currency}`);
    console.log(`Payment Method: ${transaction.txnprovider}`);
    console.log(`Waypay Reference: ${transaction.txnRef}`);
    ```
  </Accordion>

  <Accordion title="Payment Receipt Generation">
    Generate detailed payment receipts using the payment intent ID or transaction reference.

    ```javascript theme={null}
    const paymentIntentId = '550e8400-e29b-41d4-a716-446655440000';
    const transaction = await getTransactionByRef(paymentIntentId);

    const receipt = {
      orderId: transaction.merchantOrderRef,
      amount: transaction.amount,
      fee: transaction.fee,
      netAmount: transaction.netAmount,
      transactionRef: transaction.txnRef,
      paymentMethod: transaction.txnprovider,
      status: transaction.statusText,
      date: transaction.createdAtUtc
    };

    await generateReceipt(receipt);
    ```
  </Accordion>
</AccordionGroup>

## Common Error Scenarios

| Error            | Cause                                     | Solution                                                                                                |
| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 404 Not Found    | Identifier doesn't exist or access denied | Verify the identifier is correct and belongs to your merchant account                                   |
| 400 Bad Request  | Invalid identifier format                 | Ensure the identifier string is properly formatted (UUID for payment intent, your format for order ref) |
| 401 Unauthorized | Invalid or missing API key                | Check your API key is correct and has not expired                                                       |

## Security Considerations

* Keep API keys secure and never expose them in client-side code
* Use HTTPS for all API communications
* Implement proper error handling for failed queries
* Log all transaction queries for audit purposes
* Rate limit your queries to avoid overwhelming the API
* Validate transaction data before using it in your system

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup Webhooks" icon="webhook" href="/guides/webhooks">
    Get real-time transaction updates
  </Card>

  <Card title="Transaction Status Guide" icon="list-check" href="/guides/transaction-status">
    Understand transaction lifecycle
  </Card>

  <Card title="Create Refund" icon="rotate-left" href="/api-reference/endpoints/refund-create">
    Process refunds for transactions
  </Card>

  <Card title="Payment Endpoints" icon="credit-card" href="/api-reference/endpoints/payment-initiate">
    Create new payment transactions
  </Card>
</CardGroup>