Payment Links API Reference

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 Payment Links API enables merchants to programmatically create, manage, and track payment links for collecting payments from customers.

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

Generate Payment Link

Creates a new payment link that can be shared with customers via email, SMS, or other channels.

Request Parameters

Parameter
service_command   String Max: 20 Required Must be set to PAYMENT_LINK for payment link generation requests. Example. PAYMENT_LINK
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 that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. INV-2024-001
amount   Integer Max: 10 Required Payment amount in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer. Example. 125000
currency   String Max: 3 Required Three-letter ISO 4217 currency code for the payment amount. Example. AED
language   String Max: 2 Required Interface and notification language. Supported values: en (English) or ar (Arabic). Example. en
customer_email   String Max: 254 Required Valid customer email address for payment notifications and receipt delivery. Example. customer@example.com
request_expiry_date   String Max: 25 Required Payment link expiration timestamp in ISO 8601 format with timezone. Example. 2024-12-31T23:59:59+04:00
notification_type   String Max: 20 Required Notification method for customer. Values: EMAIL, SMS, NONE, or combinations like EMAIL,SMS. Example. EMAIL
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
link_command   String Max: 15 Optional Transaction type for the payment link. AUTHORIZATION for auth-only, PURCHASE for immediate capture (default). Example. PURCHASE
payment_option   String Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, etc. Example. VISA
order_description   String Max: 150 Optional Human-readable description of the order or service being paid for. Example. Premium subscription - 1 year
customer_name   String Max: 40 Optional Full name of the customer making the payment. Example. John Smith
customer_phone   String Max: 19 Optional Customer phone number in international format. Required if SMS notification is enabled. Example. 971501234567
return_url   String Max: 400 Optional Custom URL where customer will be redirected after payment completion. Example. https://yoursite.com/payment-success

Multiply your transaction 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.

The merchant_reference must be unique per transactions.

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

Response Parameters

Parameter
service_command   Alpha Max: 20 Command. Possible/expected values: PAYMENT_LINK Example. PAYMENT_LINK
access_code   Alphanumeric Max: 20 Access code. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 The ID of the Merchant. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 The Merchant's unique order number. Example. XYZ2939-yu898
amount   Numeric Max: 10 The transaction's amount. Example. 100 USD=1.00 USD
currency   Alpha Max: 3 The currency of the transaction's amount in ISO code 3. Example. USD
language   Alpha Max: 2 The invoice and received messages language. Possible/expected values: en / ar Example. en
customer_email   Alphanumeric Max: 254 The customer's email. Example. customer@domain.com
request_expiry_date   Alphanumeric Max: 25 The invoice link expiry date. Example. 2017-12-20T15:36:55+03:00
notification_type   Alpha Max: 20 The way the Customer wants to use to get his notification. Possible/expected values: SMS, EMAIL, NONE Example. EMAIL
signature   Alphanumeric Max: 200 A string hashed using the Secure Hash Algorithm. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
link_command   Alphanumeric Max: 15 Link operation to be executed. Possible/expected values: AUTHORIZATION/PURCHASE Example. PURCHASE
payment_link_id   Alphanumeric Max: 20 The ID of the generated Invoice payment link. Example. 148708392700020346
payment_link   Alphanumeric Max: 150 The generated invoice link notified to the Customer by one of the notification types, used to complete the payment process. Example. https://checkout.payfort.com/dfc3d762
payment_option   Alpha Max: 10 Payment option. Possible/expected values: MASTERCARD, VISA, AMEX, SADAD, NAPS, KNET, MADA, MEEZA Example. VISA
order_description   Alphanumeric Max: 150 It holds the description of the order. Example. iPhone 6-S
customer_name   Alpha Max: 40 The customer's name. Example. John Smith
response_message   Alphanumeric Max: 150 Message description of the response code. It returns according to the request language. Example. Success
response_code   Numeric Max: 5 Response Code carries the value of our system's response. The code is made up of five digits, the first 2 digits refer to the request status, and the last 3 digits refer to the request messages. Example. 20064
status   Numeric Max: 2 A two-digit numeric value that indicates the status of the transaction. Example. 20
customer_phone   Numeric Max: 19 The Customer mobile number. Example. 00962797219966
return_url   Alphanumeric Max: 400 The URL of the Merchant's page to be redirected to when the order is processed. Example. https://www.merchant.com

Response Code

Once the customer completes the payment through the link, the payment response will be sent to your webhook.
For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Request Sample

{
  "service_command": "PAYMENT_LINK",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "amount": 125000,
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "customer_name": "John Smith",
  "customer_phone": "971501234567",
  "request_expiry_date": "2024-12-31T23:59:59+04:00",
  "notification_type": "EMAIL",
  "order_description": "Premium subscription - 1 year",
  "link_command": "PURCHASE",
  "return_url": "https://yoursite.com/payment-success",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

curl -X POST https://sbpaymentservices.PayFort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "service_command": "PAYMENT_LINK",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "INV-2024-001",
    "amount": 125000,
    "currency": "AED",
    "language": "en",
    "customer_email": "customer@example.com",
    "request_expiry_date": "2024-12-31T23:59:59+04:00",
    "notification_type": "EMAIL",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

import json
import requests
from datetime import datetime, timedelta

# Request parameters
params = {
    'service_command': 'PAYMENT_LINK',
    'access_code': 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier': 'CycHZxVj',
    'merchant_reference': 'INV-2024-001',
    'amount': '125000',
    'currency': 'AED',
    'language': 'en',
    'customer_email': 'customer@example.com',
    'customer_name': 'John Smith',
    'customer_phone': '971501234567',
    'request_expiry_date': '2024-12-31T23:59:59+04:00',
    'notification_type': 'EMAIL',
    'order_description': 'Premium subscription - 1 year',
    'link_command': 'PURCHASE',
    'return_url': 'https://yoursite.com/payment-success',
    'signature': '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
}

# Make API request
try:
    response = requests.post(
        "https://sbpaymentservices.PayFort.com/FortAPI/paymentApi",
        json=params,
        headers={'Content-Type': 'application/json'},
        timeout=30
    )
    response.raise_for_status()
    result = response.json()
    print(json.dumps(result, indent=2))
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

<?php

// Request parameters
$params = [
    'service_command' => 'PAYMENT_LINK',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'INV-2024-001',
    'amount' => '125000',
    'currency' => 'AED',
    'language' => 'en',
    'customer_email' => 'customer@example.com',
    'customer_name' => 'John Smith',
    'customer_phone' => '971501234567',
    'request_expiry_date' => '2024-12-31T23:59:59+04:00',
    'notification_type' => 'EMAIL',
    'order_description' => 'Premium subscription - 1 year',
    'link_command' => 'PURCHASE',
    'return_url' => 'https://yoursite.com/payment-success',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
];

// Make API request
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://sbpaymentservices.PayFort.com/FortAPI/paymentApi',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($params),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen(json_encode($params))
    ],
    CURLOPT_TIMEOUT => 30,
    CURLOPT_SSL_VERIFYPEER => true
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);

if ($error) {
    echo "Error: " . $error;
} elseif ($httpCode !== 200) {
    echo "HTTP Error: " . $httpCode;
} else {
    $result = json_decode($response, true);
    echo json_encode($result, JSON_PRETTY_PRINT);
}
?>

const axios = require('axios');

// Request parameters
const params = {
    service_command: 'PAYMENT_LINK',
    access_code: 'zx0IPmPy5jp1vAz8Kpg7',
    merchant_identifier: 'CycHZxVj',
    merchant_reference: 'INV-2024-001',
    amount: '125000',
    currency: 'AED',
    language: 'en',
    customer_email: 'customer@example.com',
    customer_name: 'John Smith',
    customer_phone: '971501234567',
    request_expiry_date: '2024-12-31T23:59:59+04:00',
    notification_type: 'EMAIL',
    order_description: 'Premium subscription - 1 year',
    link_command: 'PURCHASE',
    return_url: 'https://yoursite.com/payment-success',
    signature: '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};

// Make API request
try {
    const response = await axios.post(
        'https://sbpaymentservices.PayFort.com/FortAPI/paymentApi',
        params,
        {
            headers: { 'Content-Type': 'application/json' },
            timeout: 30000
        }
    );
    
    console.log(JSON.stringify(response.data, null, 2));
} catch (error) {
    console.error('Error:', error.message);
}

Response Sample

{
  "service_command": "PAYMENT_LINK",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "amount": 125000,
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "request_expiry_date": "2024-12-31T23:59:59+04:00",
  "notification_type": "EMAIL",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "payment_link_id": "148708392700020346",
  "payment_link": "https://checkout.payfort.com/dfc3d762",
  "response_message": "Success",
  "response_code": "20064",
  "status": "20"
}

Testing The Integration

Use the sandbox environment for development and testing:

• API URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
• Test Cards: Use our comprehensive Testing Cards

Go-Live Process

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