Test Credentials

This guide provides test credentials and test card information for testing your Fatoorah Pay integration in the sandbox environment.

Overview

Fatoorah Pay provides a test environment (sandbox) where you can test your integration without processing real payments. All test transactions are simulated and no actual charges are made.

Important: Test credentials only work with test API keys (sk_test_xxx) and when isLive: false is set in your requests.

Test API Keys

Format

Test Keys: sk_test_xxxxxxxxxxxxxx
Live Keys: sk_live_xxxxxxxxxxxxxx

Generating Test API Keys

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

Environment Restrictions

Test keys (sk_test_xxx) can ONLY be used with isLive: false
Live keys (sk_live_xxx) can ONLY be used with isLive: true

Attempting to use a test key with isLive: true (or vice versa) will result in a 403 Forbidden error with code AK-403.

Test Cards

Use these test card numbers to simulate different payment scenarios. All test cards work in the sandbox environment only.

Successful Payment Cards

Scenario	Card Number	CVV	Expiry	Cardholder Name	Expected Result
Successful Payment	`5123456789012346`	`123`	Any future date (e.g., `12/30`)	Any name	Payment succeeds immediately
Successful Payment (Alternative)	`4111111111111111`	`123`	`12/30`	Test User	Payment succeeds

Test Card Details

When testing payments, use the following information:

Card Number: 5123456789012346
CVV: 123
Expiry Date: Any future date (e.g., 12/25, 12/30, 01/26)
Cardholder Name: Any name (e.g., "Test User", "Ahmed Al-Saud")

Using Test Payment Methods

Payment methods are automatically configured based on your account settings. All active test payment methods for your account are automatically included when creating payments.

Test Environment URLs

Base URLs

Base URL: https://pay.fatoorah.ai

Webhook Testing

For testing webhooks locally, you can use tools like:

ngrok: Expose your local server to the internet
```
ngrok http 8080
```
Then use the ngrok URL as your notification_url.
Webhook.site: Temporary webhook endpoint for testing
- Visit: https://webhook.site
- Copy the unique URL
- Use it as your notification_url

Sandbox Limitations

The test environment has the following characteristics:

✅ No real charges are processed
✅ All payment methods are available
✅ Full API functionality
✅ Webhook notifications work
⚠️ Test data is periodically cleared
⚠️ Rate limits may be lower than production

Testing Checklist

Follow this checklist to ensure your integration works correctly:

1. API Key Setup

Generate a test API key from the dashboard
Verify key format: sk_test_xxx
Store key securely (environment variable)

2. Create Test Payment

Create a payment link with isLive: false
Verify response contains paymentLink URL

3. Test Payment Flow

4. Test Webhooks

Set up webhook endpoint (use ngrok or webhook.site)
Create payment with notification_url
Complete payment
Verify webhook is received
Verify webhook signature (HMAC)

5. Test Error Handling

Test with invalid API key
Test with expired payment link
Test with invalid request data
Verify error responses are handled correctly

6. Test Transaction Queries

List all transactions
Get transaction by ID
Search transactions by external reference
Verify transaction status updates

Common Test Scenarios

Scenario 1: Basic Payment Link

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 User",
      "phone_number": "+966501234567",
      "description": "Test Payment"
    }
  }'

Scenario 2: Payment Link with Webhook

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": 25000,
      "full_name": "Test User",
      "phone_number": "+966501234567",
      "description": "Test Payment with Webhook",
      "notification_url": "https://your-webhook-url.com/payment",
      "external_reference_1": "TEST-001"
    }
  }'

Scenario 3: Payment Intention

curl -X POST https://pay.fatoorah.ai/api/v1/intentions \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_test_your_key_here" \
  -d '{
    "isLive": false,
    "data": {
      "amount": 10000,
      "currency": "SAR",
      "items": [
        {
          "name": "Test Product",
          "amount": 10000,
          "description": "Test item",
          "quantity": 1
        }
      ],
      "billing_data": {
        "first_name": "Test",
        "last_name": "User",
        "phone_number": "+966501234567",
        "email": "test@example.com",
        "apartment": "NA",
        "floor": "NA",
        "street": "NA",
        "building": "NA",
        "city": "Riyadh",
        "state": "Riyadh",
        "country": "SA"
      }
    }
  }'

Expected Responses

Successful Payment Link Creation

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

Successful Payment (Webhook)

After completing a payment, you'll receive a webhook with:

{
  "event": "payment.succeeded",
  "intention_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_link_id": null,
  "status": "PAID",
  "amount_cents": 10000,
  "currency": "SAR",
  "transaction_id": "FT-K7X9M2P4Q1",
  "paid_at": "2025-12-04T10:05:00+03:00",
  "display_id": "PI-X4Y6Z9A1B3"
}

Troubleshooting

Issue: "Invalid API key" error

Solution:

Verify you're using a test key (sk_test_xxx)
Ensure the key is copied correctly (no extra spaces)
Check that the key hasn't been revoked

Issue: "API key environment mismatch" error

Solution:

Test keys must use isLive: false
Live keys must use isLive: true
Verify your request matches your key type

Issue: Payment link expires immediately

Solution:

Check the expiresAt timestamp in the response
Default expiration is 24 hours from creation
Verify your server time is synchronized

Issue: Webhook not received

Solution:

Verify notification_url is publicly accessible (use ngrok for local testing)
Check that your webhook endpoint returns 200 OK
Verify webhook URL uses HTTPS in production
Check webhook delivery logs in dashboard

Additional Resources

Webhook Setup Guide - Detailed webhook configuration
Getting Started Guide - Quick start tutorial

Support

If you encounter issues with test credentials:

Email: support@fatoorah.ai
Dashboard: https://app.fatoorah.sa
Check the Errors and Retries guide for common error codes