Refunds and Voids

This guide explains how to process refunds and void transactions using the Fatoorah Pay API.

Overview

Fatoorah Pay supports two types of transaction reversals:

Refunds - Return money to customer after payment is captured
Voids - Cancel an authorized payment before capture

Refunds

A refund returns money to the customer's original payment method after a payment has been successfully processed.

When to Use Refunds

Customer requests a return
Product/service not delivered
Duplicate payment
Customer cancellation

Refund Process

Identify Transaction - Get the transaction ID or display ID
Create Refund Request - Specify refund amount
Process Refund - Fatoorah Pay processes the refund
Receive Webhook - Get notification when refund completes

Creating a Refund

curl -X POST https://pay.fatoorah.ai/api/v1/transactions/refund \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_test_your_key_here" \
  -d '{
    "transaction_id": "FT-K7X9M2P4Q1",
    "amount_cents": 10000,
    "reason": "Customer requested refund"
  }'

Refund Response

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "displayId": "FT-REFUND123",
    "amountCents": 10000,
    "currency": "SAR",
    "status": "REFUNDED",
    "transactionType": "REFUND",
    "parentTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-12-04T11:00:00+03:00"
  }
}

Partial Refunds

You can refund a portion of the original payment:

{
  "transaction_id": "FT-K7X9M2P4Q1",
  "amount_cents": 5000,  // Refund only 50 SAR from 100 SAR payment
  "reason": "Partial refund for returned item"
}

Refund Limitations

Can only refund transactions that are PAID
Refund amount cannot exceed original payment amount
Some payment methods may have refund restrictions
Refunds may take 5-10 business days to process

Voids

A void cancels an authorized payment before it's captured. The authorization is released and no money is transferred.

When to Use Voids

Cancel order before fulfillment
Payment authorization expires
Customer cancels before processing

Void Process

Identify Transaction - Get the transaction ID
Create Void Request - Request void
Process Void - Fatoorah Pay voids the authorization
Receive Webhook - Get notification when void completes

Creating a Void

curl -X POST https://pay.fatoorah.ai/api/v1/transactions/void \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_test_your_key_here" \
  -d '{
    "transaction_id": "FT-K7X9M2P4Q1",
    "reason": "Order cancelled"
  }'

Void Response

{
  "success": true,
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "displayId": "FT-VOID456",
    "status": "VOIDED",
    "transactionType": "VOID",
    "parentTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-12-04T11:30:00+03:00"
  }
}

Void Limitations

Can only void transactions that are PENDING or authorized but not captured
Cannot void already captured payments (use refund instead)
Authorization may expire automatically

Webhook Notifications

You'll receive webhook notifications for refunds and voids:

Refund Webhook

{
  "event": "payment.refunded",
  "transaction_id": "FT-REFUND123",
  "parent_transaction_id": "FT-K7X9M2P4Q1",
  "amount_cents": 10000,
  "status": "REFUNDED"
}

Void Webhook

{
  "event": "payment.voided",
  "transaction_id": "FT-VOID456",
  "parent_transaction_id": "FT-K7X9M2P4Q1",
  "status": "VOIDED"
}

Status Updates

After processing a refund or void:

Original transaction status updates
New transaction record created (refund/void)
Webhook notification sent
Transaction history updated

Best Practices

Verify transaction status - Check transaction is eligible for refund/void
Handle webhooks - Process refund/void webhooks to update your system
Log all actions - Keep audit trail of refunds and voids
Notify customers - Inform customers when refunds are processed
Monitor processing - Track refund/void status

Related Guides

Webhook Events - Refund and void webhooks
Errors and Retries - Error handling