Tahweel Docs
API Base URL

Use for all API requests

ProductionSandbox
https://connect.tahweel.io

Same endpoint for both environments — your API credentials determine Production or Sandbox mode.

GET

Payment Status

Check the current status of a payment. Use this endpoint for polling the payment status or as an alternative to webhooks.

Endpoint

GET/merchant/payment/{paymentId}/status

Path Parameters

ParameterTypeRequiredDescription
paymentIdstringRequiredThe payment ID returned from create payment API

cURL Example

curl -X GET "https://connect.tahweel.io/merchant/payment/PAY-abc123xyz/status" \
  -H "api-key: your_api_key" \
  -H "api-secret: your_api_secret"

Response

Success Response (200) - Completed

{
  "status": 200,
  "message": "Payment request status fetched successfully",
  "data": {
    "payment_id": "PAY-abc123xyz",
    "status": "completed"
  }
}

Success Response (200) - Pending

{
  "status": 200,
  "message": "Payment request status fetched successfully",
  "data": {
    "payment_id": "PAY-abc123xyz",
    "status": "pending"
  }
}

Payment Status Values

pending

Payment is awaiting customer action. QR code has not been scanned yet.

completed

Payment was successful. Funds have been transferred.

failed

Payment failed due to insufficient balance or other error.

refunded

Payment was refunded to the customer.

expired

Payment request expired before customer completed payment.

Error Response (404)

{
  "status_code": 404,
  "message": "Invalid payment id"
}

Polling Best Practices

  • • Poll every 3-5 seconds for active payment sessions
  • • Stop polling once status changes from "pending"
  • • Use webhooks for production to reduce API calls
  • • Payment requests typically expire after 15 minutes if not completed
PreviousPayment Details
NextRefund Payment