Check Payment Link Status 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 Check Payment Link Status API enables merchants to retrieve the current status and usage statistics of existing payment links to monitor payment progress and customer interactions. This RESTful API provides comprehensive status information for effective payment link management.

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

Check Payment Link Status

Retrieve comprehensive status information including payment attempts, current state, and expiration details.

Request Parameters

Parameter
query_command   String Max: 30 Required Must be set to CHECK_PAYMENT_LINK_STATUS for status inquiry requests. Example. CHECK_PAYMENT_LINK_STATUS
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 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
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. a1b2c3d4e5f6789012345678901234567890abcd

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

Response Parameters

Parameter
query_command   Alpha Max: 30 Command. Possible/expected values: CHECK_PAYMENT_LINK_STATUS Example. CHECK_PAYMENT_LINK_STATUS
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 payment link. Example. 148708392700020346
payment_link_status   Alpha Max: 10 Current status of the payment link. Possible/expected values: Open, Closed, Paid, Expired Example. Open
user_attempts_count   Numeric Max: 5 Number of times customer accessed the payment link. Example. 3
amount   Numeric Max: 10 The transaction's amount. Example. 125000
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 payment link expiry date. Example. 2024-12-31T23:59:59+04:00
customer_email   Alphanumeric Max: 254 The customer's email. Example. customer@domain.com
signature   Alphanumeric Max: 200 A string hashed using the Secure Hash Algorithm. Example. a1b2c3d4e5f6789012345678901234567890abcd
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. 20000
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

{
  "query_command": "CHECK_PAYMENT_LINK_STATUS",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

curl -X POST https://sbpaymentservices.PayFort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "query_command": "CHECK_PAYMENT_LINK_STATUS",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "INV-2024-001",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

import json
import requests

# Request parameters
params = {
    'query_command': 'CHECK_PAYMENT_LINK_STATUS',
    'access_code': 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier': 'CycHZxVj',
    'merchant_reference': 'INV-2024-001',
    '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()
    
    # Display status information
    print(f"Status: {result.get('payment_link_status')}")
    print(f"Attempts: {result.get('user_attempts_count')}")
    print(f"Amount: {result.get('amount')} {result.get('currency')}")
    print(f"Expires: {result.get('request_expiry_date')}")
    
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

<?php

// Request parameters
$params = [
    'query_command' => 'CHECK_PAYMENT_LINK_STATUS',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'INV-2024-001',
    '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);
    
    // Display status information
    echo "Status: " . ($result['payment_link_status'] ?? 'Unknown') . "\n";
    echo "Attempts: " . ($result['user_attempts_count'] ?? 0) . "\n";
    echo "Amount: " . ($result['amount'] ?? 0) . " " . ($result['currency'] ?? '') . "\n";
    echo "Expires: " . ($result['request_expiry_date'] ?? 'N/A') . "\n";
}
?>

const axios = require('axios');

// Request parameters
const params = {
    query_command: 'CHECK_PAYMENT_LINK_STATUS',
    access_code: 'zx0IPmPy5jp1vAz8Kpg7',
    merchant_identifier: 'CycHZxVj',
    merchant_reference: 'INV-2024-001',
    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
        }
    );
    
    const result = response.data;
    
    // Display status information
    console.log(`Status: ${result.payment_link_status}`);
    console.log(`Attempts: ${result.user_attempts_count}`);
    console.log(`Amount: ${result.amount} ${result.currency}`);
    console.log(`Expires: ${result.request_expiry_date}`);
    
} catch (error) {
    console.error('Error:', error.message);
}

Status Response

{
  "query_command": "CHECK_PAYMENT_LINK_STATUS",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "amount": "125000",
  "currency": "AED",
  "language": "en",
  "request_expiry_date": "2024-12-31T23:59:59+04:00",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "payment_link_id": "148708392700020346",
  "payment_link_status": "Open",
  "user_attempts_count": 3,
  "customer_email": "customer@example.com",
  "response_message": "Success",
  "response_code": "20000",
  "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