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.

POST

Refund Payment

Process a full refund for a completed payment. The refund will be sent back to the original payer's Tahweel wallet.

Endpoint

POST/merchant/payment/{paymentId}/refund

Path Parameters

ParameterTypeRequiredDescription
paymentIdstringRequiredThe payment ID of the completed payment to refund

cURL Example

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

Response

Success Response (200)

{
  "status": 200,
  "message": "Refund processed successfully",
  "data": {
    "payment_id": "PAY-abc123xyz",
    "refund_amount": "97.50",
    "refund_fee": "2.50",
    "status": "refunded",
    "refunded_at": "2024-12-25 15:00:00"
  }
}

Response Fields

payment_idThe payment ID that was refunded.
refund_amountThe amount refunded to the customer (original amount minus refund fee).
refund_feeThe refund processing fee charged.
statusUpdated payment status (refunded).

Error Responses

404Payment Not Found

{
  "status": 404,
  "message": "Payment not found"
}

400Already Refunded

{
  "status": 400,
  "message": "Payment has already been refunded"
}

400Payment Not Completed

{
  "status": 400,
  "message": "Only completed payments can be refunded"
}

400Insufficient Balance

{
  "status": 400,
  "message": "Insufficient store balance for refund"
}

Important Notes

  • • Only "completed" payments can be refunded.
  • • Refunds are full amount only - partial refunds are not supported.
  • • Your store must have sufficient balance to cover the refund amount.
  • • A refund fee may be applied based on your merchant settings.
  • • Refunds are processed immediately and cannot be reversed.

Refund Flow

1

Verify Payment Status

Ensure the payment status is "completed" before initiating refund.

2

Check Store Balance

Confirm your store has sufficient balance to cover the refund amount.

3

Process Refund

Call the refund API endpoint with the payment ID.

4

Confirm Refund

The refund is sent to the customer's Tahweel wallet immediately.

PreviousPayment Status
NextWebhooks