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 Details

Retrieve complete details of a payment transaction including customer info, store details, webhook status, and products.

Endpoint

GET/merchant/payment/{paymentId}

Path Parameters

ParameterTypeRequiredDescription
paymentIdstringRequiredThe payment ID returned from create payment API

cURL Example

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

Response

Success Response (200)

{
  "status": 200,
  "message": "Payment request details fetched successfully",
  "data": {
    "payment_id": "PAY-abc123xyz",
    "qr_code": "TW1234567890ABCDEF",
    "amount": "100.00",
    "transaction_fee": "2.50",
    "donation_amount": "0.00",
    "currency": "USD",
    "status": "completed",
    "created_at": "2024-12-25 14:30:00",
    "is_sandbox_transaction": false,
    "client": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone_dial_code": "+1",
      "phone": "1234567890"
    },
    "user": {
      "id": 123,
      "name": "Tahweel User",
      "email": "user@tahweel.io",
      "phone": "0987654321",
      "tahweel_id": "TW123456"
    },
    "store": {
      "name": "My Store",
      "logo": "https://example.com/logo.png",
      "domain": "mystore.com",
      "email": "store@example.com",
      "phone": "1234567890"
    },
    "webhook": {
      "url": "https://yoursite.com/webhook",
      "called_at": "2024-12-25 14:35:00",
      "response": { "status": "received" }
    },
    "reference": {
      "id": "ORDER-12345",
      "note": "Payment for order #12345"
    },
    "request_amount": {
      "amount": "100.00",
      "currency": "USD",
      "conversion_rate": "1.0000"
    },
    "payload": {
      "custom_field": "custom_value"
    },
    "products": [
      {
        "name": "Product Name",
        "quantity": 2,
        "price": "50.00"
      }
    ]
  }
}

Response Fields Explained

Detailed breakdown of all fields returned in the payment details response

Payment Info
payment_idUnique payment identifier
amountNet amount after fees
transaction_feeApplied transaction fee
currencyStore currency code
Status Values
pending
completed
failed
refunded
expired
User Object

Contains information about the Tahweel user who made the payment. Only populated after a successful payment.

Webhook Object

Contains webhook delivery information including the URL, timestamp of the call, and the response received from your server.

Error Response (404)

{
  "status": 404,
  "message": "Payment request not found"
}
PreviousCreate Payment
NextPayment Status