Refund API

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

The refund operation allows merchants to return the entire amount of a captured transaction, or return part of it. Refunds can be processed for full or partial amounts depending on merchant requirements.

API Endpoints

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

https://paymentservices.payfort.com/FortAPI/paymentApi

Request Format

• Method: POST
• Content-Type: application/json
• Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
command   String Max: 20 Required Operation command for refund request. Value: REFUND Example. REFUND
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required Unique order reference from the original captured transaction. You can send merchant_reference and/or fort_id to identify the transaction. Example. ORD-2024-001 Special chars: - _ .
amount   Integer Max: 10 Required Refund amount in smallest currency unit (e.g., fils for AED, cents for USD). Cannot exceed remaining refundable amount. Example. 25000
currency   String Max: 3 Required Three-letter ISO 4217 currency code matching the original transaction currency. Example. AED
language   String Max: 2 Required Response language for messages and notifications. Values: en, ar Example. en
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Integer Max: 20 Optional Unique transaction reference from Amazon Payment Services. Alternative to merchant_reference for transaction identification. Example. 149295435400084008
maintenance_reference   String Max: 200 Optional Unique refund operation reference. Allows retry of refund request using the same reference if the transaction was declined. Example. REF-2024-001
order_description   String Max: 150 Optional Human-readable description of the refund or order details. Example. Premium Wireless Headphones - Customer Return Special chars: ' / . _ - # : $ Space

Multiply your refund amount by the currency decimal code per ISO code 3 before sending the amount parameter. For currencies with three-decimal codes, round VISA transactions to zero in the final decimal place to avoid declined transactions. Example: For 500 AED (2 decimal places per ISO code 3), multiply by 100 to send 50000 in your request.

You can send merchant_reference and/or fort_id in the refund request to identify the original captured transaction. At least one of these parameters is required.

Check signature calculation section to learn how to calculate the signature.

Full Refund Sample Request

{
  "command": "REFUND",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "ORD-2024-001",
  "amount": 25000,
  "currency": "AED",
  "language": "en",
  "fort_id": "149295435400084008",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "maintenance_reference": "REF-2024-001",
  "order_description": "Premium Wireless Headphones - Full Refund"
}

import requests

# Refund request data
refund_data = {
    "command": "REFUND",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "ORD-2024-001",
    "amount": "25000",
    "currency": "AED",
    "language": "en",
    "fort_id": "149295435400084008",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "maintenance_reference": "REF-2024-001",
    "order_description": "Premium Wireless Headphones - Full Refund"
}

# Send refund request
response = requests.post(
    "https://sbpaymentservices.payfort.com/FortAPI/paymentApi",
    json=refund_data,
    headers={"Content-Type": "application/json"}
)

result = response.json()

<?php
// Refund request data
$refundData = [
    'command' => 'REFUND',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'ORD-2024-001',
    'amount' => '25000',
    'currency' => 'AED',
    'language' => 'en',
    'fort_id' => '149295435400084008',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
    'maintenance_reference' => 'REF-2024-001',
    'order_description' => 'Premium Wireless Headphones - Full Refund'
];

// Send refund request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($refundData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>

// Refund request data
const refundData = {
  command: "REFUND",
  access_code: "zx0IPmPy5jp1vAz8Kpg7",
  merchant_identifier: "CycHZxVj",
  merchant_reference: "ORD-2024-001",
  amount: "25000",
  currency: "AED",
  language: "en",
  fort_id: "149295435400084008",
  signature: "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  maintenance_reference: "REF-2024-001",
  order_description: "Premium Wireless Headphones - Full Refund"
};

// Send refund request
const response = await fetch("https://sbpaymentservices.payfort.com/FortAPI/paymentApi", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(refundData)
});

const result = await response.json();

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "command": "REFUND",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "ORD-2024-001",
    "amount": "25000",
    "currency": "AED",
    "language": "en",
    "fort_id": "149295435400084008",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "maintenance_reference": "REF-2024-001",
    "order_description": "Premium Wireless Headphones - Full Refund"
  }'

Sample Response

{
  "command": "REFUND",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "ORD-2024-001",
  "amount": 25000,
  "currency": "AED",
  "language": "en",
  "fort_id": "149295435400084008",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "order_description": "Premium Wireless Headphones - Full Refund",
  "maintenance_reference": "REF-2024-001",
  "response_message": "Success",
  "response_code": "06000",
  "status": "06"
}

Response Parameters

Parameter
command   String Max: 20 Operation command from the request. Value: REFUND Example. REFUND
access_code   String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   String Max: 40 Unique order reference from the request. Example. ORD-2024-001
amount   Integer Max: 10 Refunded transaction amount in smallest currency unit. Example. 25000
currency   String Max: 3 Currency code used for the refund. Example. AED
language   String Max: 2 Language used for the response messages. Example. en
signature   String Max: 200 Response signature for verification and security validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Integer Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
maintenance_reference   String Max: 200 Unique refund operation reference from the request. Example. REF-2024-001
order_description   String Max: 150 Description of the refunded order or transaction. Example. Premium Wireless Headphones - Full Refund
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating refund result. First 2 digits represent status, last 3 represent message. Example. 06000
status   String Max: 2 Two-digit status code indicating refund transaction state. Example. 06

Response Codes

The response of refund will be returned to your configured notification URL. For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Testing The Integration

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
• Test Scenarios: Test both full and partial refunds with various amounts
• Test Cards: Use our comprehensive Testing Cards

Go-Live Process

When ready to move to production, follow our Go-Live checklist

If you prefer using your account dashboard, you can refund payments by navigating to the "Order Transaction Management" tab. For more information, see our refunding payment guide.