Verify Card 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 verify card service allows PCI-compliant merchants to validate payment card details without processing an actual payment. This service pre-validates cards issued by Visa, Mastercard, and American Express (AMEX) as part of your risk management and fraud prevention workflow.

Read more about the verify service in our verify card guide.

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

This service can be used across custom integration only.

Request Parameters

Parameter
service_command   String Max: 20 Required Service command for card verification. Value: VERIFY_CARD Example. VERIFY_CARD
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 verification reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
currency   String Max: 3 Required Three-letter ISO 4217 currency code for the verification amount. Example. AED
language   String Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
expiry_date   String Max: 4 Required Card expiry date in YYMM format. Must be a future date. Example. 2105
card_number   String Max: 19 Required Complete credit card number for verification. MEEZA cards: 19 digits, AMEX: 15 digits, Others: 16 digits. Example. 4005550000000001
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
settlement_reference   String Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Example. XYZ9239-yu898

The merchant_reference must be unique per verification request.

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

Response Parameters

Parameter
service_command   String Max: 20 Service command from the request. Value: VERIFY_CARD Example. VERIFY_CARD
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 verification reference from the request. Example. XYZ9239-yu898
currency   String Max: 3 Currency code used for the verification. Example. AED
language   String Max: 2 Language used for the response. Example. en
expiry_date   String Max: 4 Card expiry date from the request. Example. 2105
card_number   String Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001*
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating verification result. Example. 80000
status   String Max: 2 Two-digit status code indicating verification state. Example. 80
settlement_reference   String Max: 22 Settlement reference from the request. Example. XYZ9239-yu898

Response Codes

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

Sample Request

{
  "service_command": "VERIFY_CARD",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "VERIFY-2024-1725887587",
  "currency": "AED",
  "language": "en",
  "expiry_date": "2105",
  "card_number": "4005550000000001",
  "settlement_reference": "VERIFY-REF-001",
  "signature": "eef26521d64ffd436b056ab9da0267334aa886acfe392f803e6705d0a5b0fc7a"
}

import requests
import json

# Request payload for card verification
request_data = {
    "service_command": "VERIFY_CARD",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "VERIFY-2024-1725887587",
    "currency": "AED",
    "language": "en",
    "expiry_date": "2105",
    "card_number": "4005550000000001",
    "settlement_reference": "VERIFY-REF-001",
    "signature": "eef26521d64ffd436b056ab9da0267334aa886acfe392f803e6705d0a5b0fc7a"
}

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

print(response.json())

<?php

// Request payload for card verification
$requestData = [
    'service_command' => 'VERIFY_CARD',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'VERIFY-2024-1725887587',
    'currency' => 'AED',
    'language' => 'en',
    'expiry_date' => '2105',
    'card_number' => '4005550000000001',
    'settlement_reference' => 'VERIFY-REF-001',
    'signature' => 'eef26521d64ffd436b056ab9da0267334aa886acfe392f803e6705d0a5b0fc7a'
];

// Send verification 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($requestData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

if ($httpCode === 200) {
    $result = json_decode($response, true);
    print_r($result);
} else {
    echo 'HTTP Error: ' . $httpCode;
}
?>

# Card verification request using cURL
curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "service_command": "VERIFY_CARD",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "VERIFY-2024-1725887587",
    "currency": "AED",
    "language": "en",
    "expiry_date": "2105",
    "card_number": "4005550000000001",
    "settlement_reference": "VERIFY-REF-001",
    "signature": "eef26521d64ffd436b056ab9da0267334aa886acfe392f803e6705d0a5b0fc7a"
  }'

Sample Response

{
  "service_command": "VERIFY_CARD",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "VERIFY-2024-1725887587",
  "currency": "AED",
  "language": "en",
  "expiry_date": "2105",
  "card_number": "400555******0001",
  "settlement_reference": "VERIFY-REF-001",
  "response_code": "80000",
  "response_message": "Success",
  "status": "80",
  "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4"
}

Every parameter the Merchant sends in the Request should be received by the Merchant in the Response - even the optional ones.

Check Status for Verify Service Command

You can retrieve the results of a verify command by making use of the check status API command. This allows you to query the status of a previously submitted card verification request.

Request Parameters

Parameter
query_command   String Max: 50 Required Query operations command for checking verification status. Value: CHECK_VERIFY_CARD_STATUS Example. CHECK_VERIFY_CARD_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 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required The same merchant reference used in the original verify card request. Example. XYZ9239-yu898
language   String Max: 2 Required Response language. Supported 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

Response Parameters

Parameter
query_command   String Max: 50 Query operations command from the request. Value: CHECK_VERIFY_CARD_STATUS Example. CHECK_VERIFY_CARD_STATUS
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 verification reference from the request. Example. XYZ9239-yu898
language   String Max: 2 Language used for the response. Example. en
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating query result. Example. 56000
status   String Max: 2 Two-digit status code indicating query state. Example. 56
transaction_status   String Max: 2 Status of the last verify operation performed on the specific card. Example. 80
transaction_message   String Max: 150 Message returned for the last verify operation performed on the specific card. Example. success

Sample Request

{
  "query_command": "CHECK_VERIFY_CARD_STATUS",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "VERIFY-2024-1725887587",
  "language": "en",
  "signature": "f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a"
}

import requests
import json

# Request payload for checking verification status
request_data = {
    "query_command": "CHECK_VERIFY_CARD_STATUS",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "VERIFY-2024-1725887587",
    "language": "en",
    "signature": "f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a"
}

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

print(response.json())

<?php

// Request payload for checking verification status
$requestData = [
    'query_command' => 'CHECK_VERIFY_CARD_STATUS',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'VERIFY-2024-1725887587',
    'language' => 'en',
    'signature' => 'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
];

// Send status check 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($requestData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

if ($httpCode === 200) {
    $result = json_decode($response, true);
    print_r($result);
} else {
    echo 'HTTP Error: ' . $httpCode;
}
?>

# Check verification status using cURL
curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "query_command": "CHECK_VERIFY_CARD_STATUS",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "VERIFY-2024-1725887587",
    "language": "en",
    "signature": "f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a"
  }'

Sample Response

{
  "query_command": "CHECK_VERIFY_CARD_STATUS",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "VERIFY-2024-1725887587",
  "language": "en",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "response_message": "Success",
  "response_code": "56000",
  "status": "56",
  "transaction_status": "80",
  "transaction_message": "success"
}

Response Codes

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 Cards: Use our comprehensive Testing Cards

Go-Live Process

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