Authentication

Learn how to authenticate your API requests to the Tahweel Merchant API.

API Keys

The Tahweel Merchant API uses API Key and Secret pair for authentication. You can find your credentials in the Merchant Dashboard under your approved store settings.

How to Get Your API Credentials

Register as a Merchant

Start Here

Create a Store

Navigate to your merchant dashboard and create a new store with your business details, logo, and contact information.

Wait for Store Approval

Review Period

Your store will be reviewed by the Tahweel team. You'll receive an email notification once your store is approved.

Access API Credentials

Final Step

Once approved, go to the Approved Store page in your dashboard. You'll find both Production and Sandbox API credentials there.

⚠️

Security Warning

Never expose your API Secret in client-side code or public repositories. Always make API calls from your server.

Types of Keys

LIVE

Production Keys

Use these keys for live transactions. Real money will be processed.

TEST

Sandbox Keys

Use these keys for testing and development. No real transactions are processed.

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.

💡

Sandbox vs Production

The API URL is the same for both environments. When you create a store, you'll receive two sets of credentials: Production keys for live transactions and Sandbox keys for testing. The system automatically detects the environment based on which API key you use.

Request Headers

Include the following headers in all API requests:

Header	Value	Description
`Content-Type`	`application/json`	Required for all requests with body
`api-key`	`your_api_key`	Your merchant API key
`api-secret`	`your_api_secret`	Your merchant API secret

Code Examples

cURL

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"
  }'

JavaScript / Node.js

const response = await fetch('https://connect.tahweel.io/merchant/payment/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'your_api_key',
    'api-secret': 'your_api_secret'
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'USD'
  })
});

const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.tahweel.io/merchant/payment/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 100,
    "currency" => "USD"
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: your_api_key",
    "api-secret: your_api_secret"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Authentication Errors

If authentication fails, you will receive one of the following error responses:

401Unauthorized

Invalid or missing API credentials

403Forbidden

API key does not have permission for this operation

PreviousIntroduction

NextCreate Payment