Query Transaction/Order Status

​

Overview

​

Path Parameters

​

Response

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'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1000.00,
  "currency": "PKR",
  "fee": 25.00,
  "netAmount": 975.00,
  "txType": 0,
  "txnType": "Payment",
  "description": "Product Purchase",
  "transactionNotes": "Payment completed successfully",
  "txnprovider": "JazzCash",
  "txnRef": "WP20251212123456",
  "status": 3,
  "statusText": "Success",
  "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"
}

​

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

​

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

​

Which Identifier Should You Use?

​

Response Fields Explained

​

Transaction Types (txType)

​

Transaction Status (status)

​

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

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

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

function handleWebhook(webhookData) {
  const txnRef = webhookData.data.TransactionReference;
  const transaction = await getTransactionByRef(txnRef);
  // Verify the webhook data matches the actual transaction
  if (transaction.status === 3) {
    fulfillOrder(transaction.merchantOrderRef);
  }
}

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

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

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

​

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