Query Transaction/Order Status

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'

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/ORD123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx'

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/WP20251212123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx'

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();

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();

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();

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'}
)

import requests

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

import requests

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

{
  "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"
}

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

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

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

GET

Gateway

{version}

Transaction

by-ref

{identifier}

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'

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/ORD123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx'

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/WP20251212123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx'

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();

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();

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();

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'}
)

import requests

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

import requests

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

{
  "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"
}

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

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

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

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

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)

Recommended: Use your merchant order reference for the easiest integration with your existing systems.

string

required

API version (e.g., “1”)

Response

uuid

Unique transaction identifier

number

Transaction amount

string

Currency code (e.g., “PKR”, “USD”)

number

Transaction processing fee

number

Net amount after fees

integer

Transaction type:

0 - CardDeposit (Deposit)
1 - WalletDeposit
2 - Transfer
3 - Withdrawal
4 - WalletWithdrawal
5 - Fee
6 - Reversal (Reversed)
7 - Settlement
8 - Refund

string

Transaction type description (e.g., “Deposit”, “WalletDeposit”, “Withdrawal”)

string

Transaction description

string

Additional transaction notes

string

Payment provider used

string

Transaction reference number

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

string

Human-readable status description (e.g., “Pending”, “Completed”, “Failed”)

datetime

Transaction creation timestamp (UTC)

boolean

Whether this is a live or test transaction

string

Transaction mode (e.g., “Live”, “Test”)

string

Your merchant order reference (the orderRef you provided)

uuid

Payment intent identifier

string

Name of the fee rule applied to this transaction

string

Detailed breakdown of how the fee was calculated

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'

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/ORD123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx'

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/WP20251212123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx'

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();

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();

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();

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'}
)

import requests

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

import requests

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

{
  "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"
}

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

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

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

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

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

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

Immediate Status Check After Payment Creation

Check transaction status immediately after creating a payment using the payment intent ID.

// 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}`);

Order Status Page

Display transaction status to customers on your order status page by querying with your order reference.

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

Webhook Verification

Verify webhook notifications by querying the transaction using the txnRef from the webhook payload.

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);
  }
}

Reconciliation

Match transactions with your internal orders for accounting and reconciliation.

const internalOrders = await getOrdersFromDatabase();
for (const order of internalOrders) {
  const transaction = await getTransactionByRef(order.orderRef);
  await updateOrderStatus(order.id, transaction.status);
}

Customer Support

Look up transaction details when customers contact support with their order number.

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}`);

Payment Receipt Generation

Generate detailed payment receipts using the payment intent ID or transaction reference.

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);

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

Setup Webhooks

Get real-time transaction updates

Transaction Status Guide

Understand transaction lifecycle

Create Refund

Process refunds for transactions

Payment Endpoints

Create new payment transactions

Create Withdrawal Order Create Refund

API documentation

Authentication

Account Balance

Hosted Page Checkout

Deposit

Withdrawal

Order Status

Refund Endpoints

Settlement Endpoints

Errors

Overview

Path Parameters

Response

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

Payment Intent ID (paymentIntentId)

Merchant Order Reference (orderRef)

Transaction Reference (txnRef)

Which Identifier Should You Use?

Response Fields Explained

Transaction Types (txType)

Transaction Status (status)

Best Practices

Use Cases

Common Error Scenarios

Security Considerations

Next Steps

Setup Webhooks

Transaction Status Guide

Create Refund

Payment Endpoints

​Overview

​Path Parameters

​Response

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

​Payment Intent ID (paymentIntentId)

​Merchant Order Reference (orderRef)

​Transaction Reference (txnRef)

​Which Identifier Should You Use?

​Response Fields Explained

​Transaction Types (txType)

​Transaction Status (status)

​Best Practices

​Use Cases

​Common Error Scenarios

​Security Considerations

​Next Steps

Setup Webhooks

Transaction Status Guide

Create Refund

Payment Endpoints

Overview

Path Parameters

Response

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

Payment Intent ID (paymentIntentId)

Merchant Order Reference (orderRef)

Transaction Reference (txnRef)

Which Identifier Should You Use?

Response Fields Explained

Transaction Types (txType)

Transaction Status (status)

Best Practices

Use Cases

Common Error Scenarios

Security Considerations

Next Steps