Update Payment Link 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 Update Payment Link API enables merchants to modify existing payment link properties including amount, status, expiry date, and customer details to adapt to changing business 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
service_command   String Max: 20 Required Must be set to UPDATE_PAYMENT_LINK for update operations. Example. UPDATE_PAYMENT_LINK
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
language   String Max: 2 Required Response language for error messages and notifications. Values: en (English) or ar (Arabic). Example. en
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
merchant_identifier   String Max: 20 Conditional Unique merchant identifier. Required if payment_link_id is not provided. Example. CycHZxVj
merchant_reference   String Max: 40 Conditional Original order reference used during payment link creation. Required if payment_link_id is not provided. Example. INV-2024-001
payment_link_id   String Max: 20 Conditional Unique payment link identifier. Required if merchant identifiers are not provided. Example. 148708392700020346
payment_link_status   String Max: 10 Optional New status for the payment link. Values: Open (activate) or Closed (deactivate). Example. Open
amount   Integer Max: 10 Optional New payment amount in smallest currency unit. Must be provided with currency parameter. Example. 150000
currency   String Max: 3 Optional Currency code for amount update. Required when updating amount. Example. AED
request_expiry_date   String Max: 25 Optional New expiration timestamp in ISO 8601 format. Required when reopening expired links. Example. 2025-01-31T23:59:59+04:00
order_description   String Max: 150 Optional Updated description for the order or service being paid for. Example. Premium subscription - Extended 1 year
customer_name   String Max: 40 Optional Updated customer name for the payment link. Example. John Smith Jr.
payment_option   String Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, etc. Example. VISA

Update Scenarios

Scenario	From Status	To Status	Required Fields
Close Active Link	Open	Closed	payment_link_status
Reopen Closed Link	Closed	Open	payment_link_status
Extend Expired Link	Expired	Open	payment_link_status, request_expiry_date
Update Amount	Open/Closed	Same	amount, currency
Update Details	Any	Same	Respective fields

• Cannot update Paid payment links
• When reopening Expired links, new expiry date is mandatory
• Amount updates require both amount and currency parameters
• Status changes are irreversible once payment is completed

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.

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

Response Parameters

Parameter
service_command   Alpha Max: 20 Command. Possible/expected values: UPDATE_PAYMENT_LINK Example. UPDATE_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
payment_link_id   Alphanumeric Max: 20 The ID of the updated payment link. Example. 148708392700020346
payment_link_status   Alpha Max: 10 Updated status of the payment link. Possible/expected values: Open, Closed Example. Open
amount   Numeric Max: 10 The updated transaction amount. Example. 150000
currency   Alpha Max: 3 The currency of the transaction's amount in ISO code 3. Example. AED
language   Alpha Max: 2 The language of the response messages. Possible/expected values: en / ar Example. en
request_expiry_date   Alphanumeric Max: 25 The updated payment link expiry date. Example. 2025-01-31T23:59:59+04:00
order_description   Alphanumeric Max: 150 Updated description of the order. Example. Premium subscription - Extended 1 year
customer_name   Alpha Max: 40 The updated customer name. Example. John Smith Jr.
payment_option   Alpha Max: 10 Updated payment option. Possible/expected values: MASTERCARD, VISA, AMEX, MADA Example. VISA
signature   Alphanumeric Max: 200 A string hashed using the Secure Hash Algorithm. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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. 48000
status   Numeric Max: 2 A two-digit numeric value that indicates the status of the transaction. Example. 20

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Request Sample

{
  "service_command": "UPDATE_PAYMENT_LINK",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "amount": "150000",
  "currency": "AED",
  "language": "en",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

curl -X POST https://sbpaymentservices.PayFort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "service_command": "UPDATE_PAYMENT_LINK",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "INV-2024-001",
    "amount": "150000",
    "currency": "AED",
    "language": "en",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

import json
import requests

# Update amount example
params = {
    'service_command': 'UPDATE_PAYMENT_LINK',
    'access_code': 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier': 'CycHZxVj',
    'merchant_reference': 'INV-2024-001',
    'amount': '150000',
    'currency': 'AED',
    'language': 'en',
    'signature': '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
}

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(f"Amount update result: {result.get('response_message')}")
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

# Close payment link example
params = {
    'service_command': 'UPDATE_PAYMENT_LINK',
    'access_code': 'zx0IPmPy5jp1vAz8Kpg7',
    'payment_link_id': '148708392700020346',
    'payment_link_status': 'Closed',
    'language': 'en',
    'signature': '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
}

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(f"Close result: {result.get('response_message')}")
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

# Extend expired link example
params = {
    'service_command': 'UPDATE_PAYMENT_LINK',
    'access_code': 'zx0IPmPy5jp1vAz8Kpg7',
    'payment_link_id': '148708392700020346',
    'payment_link_status': 'Open',
    'request_expiry_date': '2025-01-31T23:59:59+04:00',
    'language': 'en',
    'signature': '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
}

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(f"Extension result: {result.get('response_message')}")
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

<?php

// Update amount example
$params = [
    'service_command' => 'UPDATE_PAYMENT_LINK',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'INV-2024-001',
    'amount' => '150000',
    'currency' => 'AED',
    'language' => 'en',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
];

$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 "Amount update: " . ($result['response_message'] ?? 'Unknown') . "\n";
}

// Close payment link example
$params = [
    'service_command' => 'UPDATE_PAYMENT_LINK',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'payment_link_id' => '148708392700020346',
    'payment_link_status' => 'Closed',
    'language' => 'en',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
];

$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 "Close result: " . ($result['response_message'] ?? 'Unknown') . "\n";
}

// Extend expired link example
$params = [
    'service_command' => 'UPDATE_PAYMENT_LINK',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'payment_link_id' => '148708392700020346',
    'payment_link_status' => 'Open',
    'request_expiry_date' => '2025-01-31T23:59:59+04:00',
    'language' => 'en',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
];

$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 "Extension result: " . ($result['response_message'] ?? 'Unknown') . "\n";
}
?>

const axios = require('axios');

// Update amount example
const params = {
    service_command: 'UPDATE_PAYMENT_LINK',
    access_code: 'zx0IPmPy5jp1vAz8Kpg7',
    merchant_identifier: 'CycHZxVj',
    merchant_reference: 'INV-2024-001',
    amount: '150000',
    currency: 'AED',
    language: 'en',
    signature: '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};

try {
    const response = await axios.post(
        'https://sbpaymentservices.PayFort.com/FortAPI/paymentApi',
        params,
        {
            headers: { 'Content-Type': 'application/json' },
            timeout: 30000
        }
    );
    
    console.log('Amount update:', response.data.response_message);
} catch (error) {
    console.error('Error:', error.message);
}

// Close payment link example
const closeParams = {
    service_command: 'UPDATE_PAYMENT_LINK',
    access_code: 'zx0IPmPy5jp1vAz8Kpg7',
    payment_link_id: '148708392700020346',
    payment_link_status: 'Closed',
    language: 'en',
    signature: '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};

try {
    const response = await axios.post(
        'https://sbpaymentservices.PayFort.com/FortAPI/paymentApi',
        closeParams,
        {
            headers: { 'Content-Type': 'application/json' },
            timeout: 30000
        }
    );
    
    console.log('Close result:', response.data.response_message);
} catch (error) {
    console.error('Error:', error.message);
}

// Extend expired link example
const extendParams = {
    service_command: 'UPDATE_PAYMENT_LINK',
    access_code: 'zx0IPmPy5jp1vAz8Kpg7',
    payment_link_id: '148708392700020346',
    payment_link_status: 'Open',
    request_expiry_date: '2025-01-31T23:59:59+04:00',
    language: 'en',
    signature: '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};

try {
    const response = await axios.post(
        'https://sbpaymentservices.PayFort.com/FortAPI/paymentApi',
        extendParams,
        {
            headers: { 'Content-Type': 'application/json' },
            timeout: 30000
        }
    );
    
    console.log('Extension result:', response.data.response_message);
} catch (error) {
    console.error('Error:', error.message);
}

Response Sample

{
  "service_command": "UPDATE_PAYMENT_LINK",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "amount": "150000",
  "currency": "AED",
  "language": "en",
  "request_expiry_date": "2025-01-31T23:59:59+04:00",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "payment_link_id": "148708392700020346",
  "payment_link_status": "Open",
  "response_message": "Success",
    "response_code": "48000",
  "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