Payment Intentions

Payment intentions represent the lifecycle of a payment from creation to completion. Use payment intentions when you want to integrate payments directly into your application flow with full programmatic control.

What are Payment Intentions?

Payment intentions are payment objects that you create programmatically and manage through their lifecycle. Unlike payment links (which are shareable URLs), payment intentions give you:

Full control over the payment flow
Detailed line items and billing information
Programmatic status management
Integration with your checkout process

When to Use Payment Intentions

Payment intentions are ideal for:

✅ E-commerce checkouts - Integrated checkout flows
✅ In-app payments - Mobile and web applications
✅ Custom checkout pages - Your own payment UI
✅ Multi-step processes - Complex payment flows
✅ Real-time status updates - Immediate payment confirmation

Not ideal for:

❌ Simple email/SMS payments (use Payment Links instead)
❌ Manual order processing (use Payment Links instead)

Creating a Payment Intention

Basic Request

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": "Product A",
          "amount": 10000,
          "description": "Product description",
          "quantity": 1
        }
      ],
      "billing_data": {
        "first_name": "Ahmed",
        "last_name": "Al-Saud",
        "phone_number": "+966501234567",
        "email": "ahmed@example.com",
        "apartment": "NA",
        "floor": "NA",
        "street": "NA",
        "building": "NA",
        "city": "Riyadh",
        "state": "Riyadh",
        "country": "SA"
      }
    }
  }'

Required Fields

amount - Total payment amount in cents (must equal sum of item amounts)
currency - Currency code (ISO 4217, e.g., "SAR")
items - Array of line items (at least one required)
billing_data - Customer billing information

Line Items Structure

Each item requires:

name - Item name
amount - Item amount in cents
description - Item description
quantity - Item quantity

Billing Data Structure

Required fields:

first_name - Customer's first name
last_name - Customer's last name
phone_number - Customer's phone number (format: ^\\+?[0-9. ()-]{7,25}$)
apartment - Apartment number (use "NA" if not applicable)
floor - Floor number (use "NA" if not applicable)
street - Street address (use "NA" if not applicable)
building - Building number (use "NA" if not applicable)
city - City name
state - State/province name
country - Country code (ISO 3166-1 alpha-2, e.g., "SA")

Optional fields:

email - Customer's email address
id - Billing data ID (optional)

Optional Fields

notification_url - Webhook URL for payment status updates
redirection_url - URL to redirect customer after payment
expires_at - Custom expiration timestamp (defaults to 24 hours)
special_reference - Special reference number
extras - Additional metadata (JSON object)

Note: Payment platform and payment methods are automatically configured based on your account settings.

Response

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "displayId": "PI-X4Y6Z9A1B3",
    "amountCents": 10000,
    "currency": "SAR",
    "clientSecret": "sau_csk_test_def456uvw",
    "paymentLink": "https://pay.fatoorah.ai/checkout/pay/660e8400-e29b-41d4-a716-446655440001",
    "status": "UNPAID",
    "expiresAt": "2025-12-05T10:00:00+03:00",
    "isExpired": false,
    "items": [
      {
        "name": "Product A",
        "amount": 10000,
        "description": "Product description",
        "quantity": 1
      }
    ],
    "billingData": {
      "first_name": "Ahmed",
      "last_name": "Al-Saud",
      "phone_number": "+966501234567",
      "email": "ahmed@example.com",
      "city": "Riyadh",
      "state": "Riyadh",
      "country": "SA"
    },
    "createdAt": "2025-12-04T10:00:00+03:00"
  }
}

Payment Flow

Step 1: Create Intention

Create a payment intention with order details:

const intention = await createIntention({
  amount: 10000,
  currency: "SAR",
  items: [
    { name: "Product A", amount: 10000, description: "Description", quantity: 1 }
  ],
  billing_data: { /* ... */ }
});

Step 2: Redirect the Customer to the Payment

Use the paymentLink field from the API response to redirect your customer to the hosted checkout page:

// In your frontend
window.location.href = intention.paymentLink;

Step 3: Customer Completes Payment

Customer enters payment details and completes payment through the checkout.

Step 4: Receive Webhook

Your server receives a webhook notification:

{
  "event": "payment.succeeded",
  "intention_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "PAID",
  "amount_cents": 10000,
  "transaction_id": "FT-K7X9M2P4Q1"
}

Step 5: Fulfill Order

Update your order status and fulfill the order.

Status Management

Payment Statuses

UNPAID - Payment intention created, awaiting payment
PAID - Payment completed successfully
EXPIRED - Payment intention expired (default: 24 hours)
FAILED - Payment failed or was declined

Checking Status

curl -X GET "https://pay.fatoorah.ai/api/v1/intentions/660e8400-e29b-41d4-a716-446655440001" \
  -H "X-API-KEY: sk_test_your_key_here"

Using Webhooks (Recommended)

Set up webhooks for real-time status updates:

{
  "data": {
    "notification_url": "https://your-server.com/webhooks/payment"
  }
}

See Webhook Setup for detailed instructions.

Expiration Handling

Payment intentions expire after 24 hours by default. You can customize:

Custom Expiration

{
  "data": {
    "expires_at": "2025-12-10T23:59:59+03:00"
  }
}

Handling Expiration

Monitor isExpired field
Create new intention if expired
Notify customer before expiration

Multiple Line Items

Payment intentions support multiple line items:

{
  "data": {
    "amount": 30000,
    "currency": "SAR",
    "items": [
      {
        "name": "Product A",
        "amount": 10000,
        "description": "Product A description",
        "quantity": 1
      },
      {
        "name": "Product B",
        "amount": 20000,
        "description": "Product B description",
        "quantity": 2
      }
    ]
  }
}

Important: The amount field must equal the sum of all item amounts.

Complete Example

E-commerce Checkout Flow

// 1. Create payment intention
const intention = await fetch('https://pay.fatoorah.ai/api/v1/intentions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': process.env.FATOORAH_API_KEY
  },
  body: JSON.stringify({
    isLive: false,
    data: {
      amount: cart.total * 100,
      currency: 'SAR',
      items: cart.items.map(item => ({
        name: item.name,
        amount: item.price * 100,
        description: item.description,
        quantity: item.quantity
      })),
      billing_data: {
        first_name: customer.firstName,
        last_name: customer.lastName,
        phone_number: customer.phone,
        email: customer.email,
        apartment: 'NA',
        floor: 'NA',
        street: 'NA',
        building: 'NA',
        city: customer.city,
        state: customer.state,
        country: 'SA'
      },
      notification_url: 'https://your-server.com/webhooks/payment',
      redirection_url: 'https://your-app.com/checkout/success'
    }
  })
}).then(res => res.json());

// 2. Redirect the Customer to the Payment
// (In your frontend)
window.location.href = intention.paymentLink;

// 3. Handle webhook (on your server)
app.post('/webhooks/payment', (req, res) => {
  if (req.body.event === 'payment.succeeded') {
    fulfillOrder(req.body.intention_id);
  }
  res.status(200).send('OK');
});

Listing Payment Intentions

Retrieve all payment intentions:

curl -X GET "https://pay.fatoorah.ai/api/v1/intentions?page=0&size=20" \
  -H "X-API-KEY: sk_test_your_key_here"

Query Parameters

page - Page number (0-indexed, default: 0)
size - Page size (default: 10, max: 100)

Best Practices

Validate amounts - Ensure total amount equals sum of item amounts
Set expiration - Use appropriate expiration for your use case
Use webhooks - Get real-time payment notifications
Handle errors - Implement proper error handling
Idempotency - Handle duplicate webhook deliveries
Monitor status - Regularly check intention status

Related Guides

Payment Links - For shareable payment URLs
Webhook Setup - Real-time notifications
Test Credentials - Test cards and sandbox