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

Create Payment

Create a new payment request and generate a QR code for the customer to scan and pay.

Endpoint

POST/merchant/payment/create

Request Parameters

Parameter	Type	Required	Description
`amount`	number	Required	Transaction amount (must be greater than 0)
`currency`	string	Required	Currency code (e.g., USD, EUR, SAR)
`client`	object	Optional	Customer information (name, email, phone required if provided)
`products`	array	Optional	Array of products (name, quantity, price required for each)
`payload`	object	Optional	Custom data object to store with payment
`reference_id`	string	Optional	Your unique order/reference ID
`reference_note`	string	Optional	Note or description for the payment
`webhook_url`	string	Optional	URL to receive payment status updates

Request Body Example

{
  "amount": 100.00,
  "currency": "USD",
  "client": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "1234567890",
    "phone_dial_code": "+1"
  },
  "products": [
    {
      "name": "Product Name",
      "quantity": 2,
      "price": 50.00
    }
  ],
  "payload": {
    "order_id": "ORD-12345",
    "custom_field": "custom_value"
  },
  "reference_id": "ORDER-12345",
  "reference_note": "Payment for order #12345",
  "webhook_url": "https://yoursite.com/webhook"
}

cURL Example

curl -X POST "https://connect.tahweel.io/merchant/payment/create" \
  -H "Content-Type: application/json" \
  -H "api-key: your_api_key" \
  -H "api-secret: your_api_secret" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "reference_id": "ORDER-12345"
  }'

Response

Success Response (200)

{
  "message": "Payment request created successfully",
  "data": {
    "payment_id": "PAY-abc123xyz",
    "qr_code": "TW1234567890ABCDEF",
    "instructions": "<div>Open the Tahweel App...</div>"
  }
}

Response Fields

payment_idUnique identifier for the payment. Use this to check status or get details.

qr_codeA QR code number will be sent, which needs to be converted to a scannable QR Code.

instructionsHTML instructions for the customer on how to complete the payment.

Error Response (400)

{
  "status": 400,
  "message": "Validation error",
  "errors": [
    {
      "field": "amount",
      "message": "Amount is required"
    }
  ]
}

Important Notes

• Amount must be within your store's minimum and maximum transaction limits.
• Daily and monthly transaction limits apply based on your merchant settings.
• If client object is provided, all fields (name, email, phone) are required.
• If products array is provided, each product must have name, quantity, and price.
• Use the webhook_url to receive real-time payment status updates.

PreviousAuthentication

NextPayment Details