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.

WEBHOOK

Webhooks

Configure your webhook endpoint to receive real-time notifications about transaction events.

Webhook Configuration

You can configure a webhook URL to receive real-time payment notifications for your store. The webhook URL can be set from the store details page once your store is approved. After configuration, your webhook endpoint will receive POST requests whenever a payment event occurs.

Webhook Requirements

Webhook URL must be a valid HTTPS endpoint
The endpoint must be publicly accessible
The endpoint should respond with 200 status code for successful requests
Ensure your server can handle POST requests
Webhook will be called for transaction events (success, refund, etc.)

Webhook Events

Webhooks are triggered when specific payment events occur. Currently, webhooks are sent for:

Event	Status Value	Description
`Payment Success`	success	Triggered when a customer successfully completes a payment
`Payment Refunded`	refunded	Triggered when a payment is refunded to the customer

Webhook Payload

When a payment is successfully completed, Tahweel sends a POST request to your configured webhook URL with the following JSON payload:

Success Payment Webhook

{
  "payment_id": "PAY-abc123xyz",
  "transaction_id": "TXN-789def456",
  "transaction_amount": 100.00,
  "admin_fee_amount": 2.50,
  "admin_fee_paid_by": "merchant",
  "currency": "USD",
  "fx_rate": 1.0,
  "reference_id": "ORDER-12345",
  "reference_note": "Payment for order #12345",
  "payload": {
    "order_id": "ORD-12345",
    "custom_field": "custom_value"
  },
  "status": "success"
}

Payload Fields

payment_idUnique identifier for the payment request.

transaction_idUnique identifier for the transaction.

transaction_amountThe amount received by the merchant (after fees if applicable).

admin_fee_amountThe admin/processing fee amount charged for this transaction.

admin_fee_paid_byWho paid the admin fee: "merchant" or "user".

currencyThe currency code of the transaction (e.g., USD, EUR, SAR).

fx_rateThe foreign exchange rate applied (1.0 if same currency).

reference_idYour custom reference ID passed during payment creation.

reference_noteYour custom reference note passed during payment creation.

payloadCustom payload object passed during payment creation.

statusPayment status: "success" or "refunded".

Refund Webhook

When a payment is refunded, you will receive the same payload structure with status set to "refunded":

{
  "payment_id": "PAY-abc123xyz",
  "transaction_id": "TXN-789def456",
  "transaction_amount": 100.00,
  "admin_fee_amount": 2.50,
  "admin_fee_paid_by": "merchant",
  "currency": "USD",
  "fx_rate": 1.0,
  "reference_id": "ORDER-12345",
  "reference_note": "Payment for order #12345",
  "payload": {
    "order_id": "ORD-12345",
    "custom_field": "custom_value"
  },
  "status": "refunded"
}

Handling Webhooks

Here's an example of how to handle webhook notifications in your application:

// Node.js/Express example
app.post('/webhook', (req, res) => {
  const {
    payment_id,
    transaction_id,
    transaction_amount,
    status,
    reference_id
  } = req.body;

  // Verify the payment status
  if (status === 'success') {
    // Update your order status
    // Send confirmation email
    // Fulfill the order
  } else if (status === 'refunded') {
    // Handle refund logic
    // Update order status to refunded
  }

  // Always respond with 200 OK
  res.status(200).send('OK');
});

Best Practices

Always respond with HTTP 200 status code to acknowledge receipt.
Process webhooks asynchronously to avoid timeouts.
Implement idempotency using payment_id to handle duplicate webhooks.
Log all incoming webhooks for debugging and auditing purposes.
Verify the webhook data by cross-checking with the Payment Status API if needed.

Webhook Flow

Configure Webhook URL

Set your webhook URL from the store details page after your store is approved.

Customer Completes Payment

When a customer pays using the Tahweel app, the payment is processed.

Webhook Notification Sent

Tahweel immediately sends a POST request to your webhook URL with payment details.

Process & Acknowledge

Your server processes the webhook and responds with HTTP 200 to acknowledge receipt.

Important Security Note

For critical operations, always verify the payment status using the Payment Status API before fulfilling orders. Do not rely solely on webhook notifications for order fulfillment of high-value transactions.

PreviousRefund Payment