Getting Started

Welcome to Fatoorah Pay! This guide will help you integrate payment processing into your application in just a few steps.

Overview

Fatoorah Pay is a payment gateway service that enables you to:

Accept card payments from customers
Create shareable payment links
Process payments programmatically
Receive real-time webhook notifications
Query transaction history

Prerequisites

Before you begin, ensure you have:

A Fatoorah Pay account (Sign up here)
A server environment (for webhook handling)
Basic knowledge of REST APIs
Your preferred programming language (Node.js, Python, PHP, etc.)

Step 1: Create Your Account

Visit Fatoorah Pay Dashboard
Click Sign Up or Register
Complete the registration form
Verify your email address
Log in to your dashboard

Step 2: Generate Your API Key

API keys are used to authenticate your requests to the Fatoorah Pay API.

Via Dashboard

Log in to the Fatoorah Pay Dashboard
Navigate to Account > API Keys
Click Generate New Key
Select environment: TEST (for development)
Give it a descriptive name (e.g., "My Integration - Development")
Copy the key immediately - it's shown only once!
Store it securely (environment variable, secrets manager)

API Key Format

Test Keys: sk_test_xxxxxxxxxxxxxx
Live Keys: sk_live_xxxxxxxxxxxxxx

Important:

Test keys can only be used with isLive: false
Live keys can only be used with isLive: true
Never commit API keys to version control

Step 3: Make Your First API Call

Let's create a simple payment link to verify your setup works.

Using cURL

curl -X POST https://pay.fatoorah.ai/api/v1/payment-links \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_test_your_key_here" \
  -d '{
    "isLive": false,
    "data": {
      "amount_cents": 10000,
      "full_name": "Test Customer",
      "phone_number": "+966501234567",
      "description": "My First Payment"
    }
  }'

Expected Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayId": "PL-M3N5Q8R2W7",
    "amountCents": 10000,
    "currency": "SAR",
    "clientSecret": "sau_csk_test_abc123xyz",
    "paymentLink": "https://pay.fatoorah.ai/checkout/pay/550e8400-e29b-41d4-a716-446655440000",
    "status": "UNPAID",
    "expiresAt": "2025-12-05T10:00:00+03:00",
    "isExpired": false,
    "createdAt": "2025-12-04T10:00:00+03:00"
  }
}

What Just Happened?

You sent a request to create a payment link
Fatoorah Pay validated your API key
A payment link was created
You received a shareable URL (paymentLink) that customers can use to pay

Step 4: Test with Test Credentials

Now let's test the complete payment flow using test credentials.

4.1 Open the Payment Link

Copy the paymentLink URL from the response and open it in your browser. You should see the Fatoorah Pay checkout page.

4.2 Complete a Test Payment

Use these test card details:

Card Number: 4987654321098769
CVV: 123
Expiry: Any future date (e.g., 12/25)
Cardholder Name: Any name

4.3 Verify Payment

After completing the payment:

You'll be redirected to a receipt page
The payment status will be PAID
You can query the transaction using the API

Query the Transaction

curl -X GET "https://pay.fatoorah.ai/api/v1/transactions" \
  -H "X-API-KEY: sk_test_your_key_here"

Step 5: Set Up Webhooks (Recommended)

Webhooks notify your server when payment status changes. This is essential for production integrations.

5.1 Create a Webhook Endpoint

Create an endpoint on your server to receive webhooks:

// Node.js example
app.post('/webhooks/payment', (req, res) => {
  // Verify webhook signature
  // Process payment status update
  res.status(200).send('OK');
});

5.2 Configure Webhook URL

When creating a payment, include your webhook URL:

{
  "isLive": false,
  "data": {
    "amount_cents": 10000,
    "full_name": "Test Customer",
    "phone_number": "+966501234567",
    "description": "Payment with Webhook",
    "notification_url": "https://your-server.com/webhooks/payment"
  }
}

5.3 Test Webhook Locally

For local development, use ngrok to expose your server:

ngrok http 8080

Use the ngrok URL as your notification_url.

See the Webhook Setup Guide for detailed instructions.

Next Steps

Now that you've completed the basics, explore these guides:

Payment Methods

Payment Links - Create shareable payment links
Payment Intentions - Process payments programmatically

Integration

Authentication - API key authentication details
Webhooks - Webhook setup and handling

Operations

Test Credentials - Test cards and sandbox environment
Errors and Retries - Error handling

Common Integration Patterns

Pattern 1: E-commerce Checkout

Customer → Add to Cart → Checkout
         ↓
Create Payment Link (API)
         ↓
Redirect to Payment Page
         ↓
Customer Pays
         ↓
Webhook Callback → Verify → Fulfill Order

Pattern 2: Subscription Service

User Signs Up
    ↓
Create Payment Intention (API)
    ↓
Customer Completes Payment
    ↓
Webhook Notification
    ↓
Activate Subscription

Pattern 3: Invoice Payment

Generate Invoice
    ↓
Create Payment Link with External Reference
    ↓
Send Link to Customer (Email/SMS)
    ↓
Customer Pays
    ↓
Webhook → Update Invoice Status

Best Practices

Always verify webhooks - Use HMAC signature verification
Handle errors gracefully - Implement retry logic for failed requests
Use test environment first - Test thoroughly before going live
Store API keys securely - Never commit keys to version control
Monitor webhook delivery - Set up logging and alerts
Idempotency - Handle duplicate webhook deliveries

Support

Need help? We're here for you:

Email: support@fatoorah.ai
Dashboard: https://app.fatoorah.sa
Documentation: This guide and related docs

What's Next?

Read the Authentication Guide for detailed API key information
Explore Payment Links for shareable payment URLs
Set up Webhooks for real-time notifications

Happy integrating! 🚀