Alghahim Pay provides a unified payment processor API for seamless integration across all your internal products. Process payments programmatically with secure API keys, manage payment links, and track transactions in real-time.
https://pay.iicar.org/api/v1All API requests require authentication using an API key in the Authorization header:
Authorization: Bearer ap_live_xxxxxxxxxxxxxxxxxxxxAPI keys are generated in your API Keys dashboard. Keep your API keys secure and never share them publicly.
API rate limits are enforced per API key. Default rate limit is 1000 requests per hour. Rate limit information is included in response headers:
X-RateLimit-Limit: Total requests allowed per hourX-RateLimit-Remaining: Remaining requests this hourX-RateLimit-Reset: Unix timestamp when limit resetsAll responses are returned as JSON. Success responses return a 200-299 status code, while errors return 400+ status codes.
{
"success": true,
"data": { /* resource data */ },
"message": "Operation completed successfully"
}Payment Links are shareable URLs that allow users to make payments. They can be fixed-amount or flexible-amount payment links.
POST /payment-links{
"amount_usd": 99.99,
"amount_type": "fixed",
"description": "Premium package subscription",
"custom_path": "premium-plan-2024",
"product_slug": "mobile-app",
"minimum_amount_usd": 20,
"is_active": true
}| Parameter | Type | Required | Description |
|---|---|---|---|
amount_usd | number | Yes | Payment amount in USD |
amount_type | string | Yes | "fixed" or "flexible" |
description | string | No | Link description shown to users |
custom_path | string | No | Custom URL path (auto-generated if omitted) |
product_slug | string | No | Associate with a product for tracking |
minimum_amount_usd | number | No | Minimum for flexible payments (default: 20) |
{
"id": "c7b8d5e2-4f9a-11ef-a236-0242ac120002",
"custom_path": "premium-plan-2024",
"amount_usd": "99.99",
"amount_type": "fixed",
"description": "Premium package subscription",
"product_slug": "mobile-app",
"payment_url": "https://pay.iicar.org/pay/premium-plan-2024",
"is_active": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}GET /payment-links?status=active&product_slug=mobile-appstatus - Filter by status: active, inactiveproduct_slug - Filter by productlimit - Number of results (default: 50, max: 100)offset - Pagination offsetGET /payment-links/c7b8d5e2-4f9a-11ef-a236-0242ac120002PATCH /payment-links/c7b8d5e2-4f9a-11ef-a236-0242ac120002Update payment link properties like description, status, and amount.
POST /payment-links/c7b8d5e2-4f9a-11ef-a236-0242ac120002/disableDisable a payment link to prevent new payments.
Retrieve payment transaction data and monitor payment status in real-time.
GET /payments?status=completed&limit=50&offset=0| Parameter | Type | Description |
|---|---|---|
status | string | pending, completed, failed, refunded |
product_slug | string | Filter by product |
limit | number | Results per page (default: 50, max: 100) |
offset | number | Pagination offset |
{
"payments": [
{
"id": "pay_abc123xyz",
"link_id": "c7b8d5e2-4f9a-11ef-a236-0242ac120002",
"amount_usd": "99.99",
"status": "completed",
"email": "user@example.com",
"reference": "PAY_2024_001",
"product_slug": "mobile-app",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:35:00Z"
}
],
"total": 150,
"limit": 50,
"offset": 0
}GET /payments/pay_abc123xyzAPI keys are used to authenticate your requests to the Alghahim Pay API. Generate and manage keys from your API Keys dashboard.
API keys follow this format:
ap_live_32randomcharactersandnumbers1234ap_live - Production environment prefix32 characters - Random unique identifierEach API key can be scoped to specific permissions:
The API uses standard HTTP status codes and returns detailed error messages to help you troubleshoot issues.
{
"error": "payment_not_found",
"message": "Payment with ID 'pay_invalid' not found",
"status_code": 404
}| Status Code | Meaning | Action |
|---|---|---|
| 200 OK | Request succeeded | None |
| 400 Bad Request | Invalid parameters | Check request format |
| 401 Unauthorized | Invalid API key | Verify API key |
| 403 Forbidden | Insufficient permissions | Check key permissions |
| 404 Not Found | Resource not found | Verify resource ID |
| 429 Too Many Requests | Rate limit exceeded | Wait before retrying |
| 500 Server Error | Server error | Retry with backoff |
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || '60';
console.log(`Rate limited. Retry after ${retryAfter} seconds`);
// Implement exponential backoff
}// Initialize API client
const API_KEY = 'ap_live_xxxxxxxxxxxxxxxxxxxx';
const API_URL = 'https://pay.iicar.org/api/v1';
async function createPaymentLink(amount, description) {
try {
const response = await fetch(`${API_URL}/payment-links`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount_usd: amount,
amount_type: 'fixed',
description: description,
product_slug: 'my-product'
})
});
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
console.log('Payment link created:', data.payment_url);
return data;
} catch (error) {
console.error('Error creating payment link:', error);
}
}
// Create a $99.99 payment link
await createPaymentLink(99.99, 'Premium subscription');curl -X POST https://pay.iicar.org/api/v1/payment-links \
-H "Authorization: Bearer ap_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"amount_usd": 99.99,
"amount_type": "fixed",
"description": "Premium subscription",
"product_slug": "my-product"
}'import requests
API_KEY = 'ap_live_xxxxxxxxxxxxxxxxxxxx'
API_URL = 'https://pay.iicar.org/api/v1'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
# Create payment link
payload = {
'amount_usd': 99.99,
'amount_type': 'fixed',
'description': 'Premium subscription',
'product_slug': 'my-product'
}
response = requests.post(
f'{API_URL}/payment-links',
json=payload,
headers=headers
)
data = response.json()
print(f'Payment URL: {data["payment_url"]}')For support with API integration, visit your API Keys dashboard or contact our support team.