Non-PCI Custom Integration API

Copy page

Copy page as Markdown for LLMs

Open in Claude

Ask questions about this page

Non-PCI custom integration allows you to build your own payment form that captures payment data and securely submits it to Amazon Payment Services through tokenization. This approach provides maximum control over your payment form design while maintaining security and reducing PCI compliance requirements.

API Endpoints

https://sbcheckout.payfort.com/FortAPI/paymentPage

https://checkout.payfort.com/FortAPI/paymentPage

Tokenization

Request Format

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Submission: HTML Form (Client-side HTTPS POST)

Tokenization requests must be submitted as HTTPS POST forms directly from the client browser to ensure card data never touches your server.

Request Parameters

Parameter
service_command   Alpha Max: 20 Required Service command for tokenization request. Value: TOKENIZATION Example. TOKENIZATION
access_code   Alphanumeric Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Special characters: - _ . Example. XYZ9239-yu898
language   Alpha Max: 2 Required Tokenization page and response language. Supported values: en (English) or ar (Arabic). Example. en
expiry_date   Numeric Max: 4 Required Card expiry date in YYMM format. Must be a future date. Example. 2105
card_number   Numeric Max: 19 Required Complete credit card number. MEEZA cards: 19 digits, AMEX: 15 digits, Others: 16 digits. Example. 4005550000000001
card_security_code   Numeric Max: 4 Required Card security code (CVV/CVC). AMEX accepts 4 digits, others accept 3 digits. Example. 123
signature   Alphanumeric Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name   Alphanumeric Max: 100 Optional Previously generated token for card updates or re-tokenization. Special characters: . @ - _ Example. Op9Vmp
card_holder_name   Alpha Max: 50 Optional Cardholder name as it appears on the card. Alphabetic characters, spaces, hyphens, periods, and apostrophes allowed. Special characters: ' - . Example. John Smith
remember_me   Alpha Max: 3 Optional Enable token generation for future payments. Values: YES, NO Example. YES
return_url   Alphanumeric Max: 400 Optional URL where customer will be redirected after tokenization completion. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com/tokenization-callback

Exclude these parameters when calculating the signature for tokenization requests:

• card_security_code, card_number , expiry_date, card_holder_name remember_me

This ensures sensitive card data is not included in signature calculations.

Response Parameters

Parameter
service_command   Alpha Max: 20 Service command from the request. Value: TOKENIZATION Example. TOKENIZATION
access_code   Alphanumeric Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Unique order reference from the request. Example. XYZ9239-yu898
language   Alpha Max: 2 Language used for the tokenization process. Example. en
expiry_date   Numeric Max: 4 Card expiry date from the request. Example. 2105
card_number   Numeric Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001*
signature   Alphanumeric Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name   Alphanumeric Max: 100 Generated token for future payment processing. Example. COp9Vmp
response_message   Alphanumeric Max: 150 Human-readable response description in requested language. Example. Success
response_code   Numeric Max: 5 Numeric response code indicating tokenization result. Example. 18000
status   Numeric Max: 2 Two-digit status code indicating tokenization state. Example. 18
card_bin   Numeric Max: 8 First 6-8 digits of the card number for identification. Example. 478773
card_holder_name   Alpha Max: 50 Cardholder name from the request. Example. John Smith
remember_me   Alpha Max: 3 Token save indication from the request. Example. YES
return_url   Alphanumeric Max: 400 Return URL from the request. Example. https://www.merchant.com/tokenization-callback

Contact integration@payfort.com to activate additional response parameters like issuer_country, acquirer_response_message and issuer_name for enhanced transaction insights.

Tokenization Sample Request

<!-- HTTPS POST form submitted directly to APS from client browser -->
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tokenization_form">
    
    <!-- Required Tokenization Parameters -->
    <input type="hidden" name="service_command" value="TOKENIZATION">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="return_url" value="https://www.merchant.com/tokenization-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card input fields (client-side only) -->
    <div class="form-group">
        <label for="card_number">Card Number *</label>
        <input type="text" 
               id="card_number" 
               name="card_number" 
               placeholder="1234 5678 9012 3456"
               maxlength="19"
               required>
    </div>
    
    <div class="form-row">
        <div class="form-group">
            <label for="expiry_date">Expiry Date *</label>
            <input type="text" 
                   id="expiry_date" 
                   name="expiry_date" 
                   placeholder="YYMM"
                   maxlength="4"
                   required>
        </div>
        
        <div class="form-group">
            <label for="card_security_code">CVV *</label>
            <input type="text" 
                   id="card_security_code" 
                   name="card_security_code" 
                   placeholder="123"
                   maxlength="4"
                   required>
        </div>
    </div>
    
    <div class="form-group">
        <label for="card_holder_name">Cardholder Name</label>
        <input type="text" 
               id="card_holder_name" 
               name="card_holder_name" 
               placeholder="John Smith"
               maxlength="50">
    </div>
    
    <div class="form-group checkbox-group">
        <label>
            <input type="hidden" name="remember_me" value="NO">
            <input type="checkbox" id="save_card" onchange="toggleRememberMe(this)">
            Save this card for future payments
        </label>
    </div>
    
    <button type="submit" class="tokenize-button">
        Securely Save Card
    </button>
</form>

# Frontend: HTML form for tokenization (HTTPS POST from client browser)
tokenization_form = '''
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tokenization_form">
    <input type="hidden" name="service_command" value="TOKENIZATION">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="return_url" value="https://www.merchant.com/tokenization-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card input fields -->
    <div class="form-group">
        <label for="card_number">Card Number *</label>
        <input type="text" id="card_number" name="card_number" placeholder="1234 5678 9012 3456" maxlength="19" required>
    </div>
    
    <div class="form-row">
        <div class="form-group">
            <label for="expiry_date">Expiry Date *</label>
            <input type="text" id="expiry_date" name="expiry_date" placeholder="YYMM" maxlength="4" required>
        </div>
        <div class="form-group">
            <label for="card_security_code">CVV *</label>
            <input type="text" id="card_security_code" name="card_security_code" placeholder="123" maxlength="4" required>
        </div>
    </div>
    
    <div class="form-group">
        <label for="card_holder_name">Cardholder Name</label>
        <input type="text" id="card_holder_name" name="card_holder_name" placeholder="John Smith" maxlength="50">
    </div>
    
    <div class="form-group">
        <input type="hidden" name="remember_me" value="YES">
    </div>
    
    <button type="submit" class="tokenize-button">Securely Save Card</button>
</form>
'''

<?php
// Frontend: HTML form for tokenization (HTTPS POST from client browser)
$tokenization_form = '
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="tokenization_form">
    <input type="hidden" name="service_command" value="TOKENIZATION">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="return_url" value="https://www.merchant.com/tokenization-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card input fields -->
    <div class="form-group">
        <label for="card_number">Card Number *</label>
        <input type="text" id="card_number" name="card_number" placeholder="1234 5678 9012 3456" maxlength="19" required>
    </div>
    
    <div class="form-row">
        <div class="form-group">
            <label for="expiry_date">Expiry Date *</label>
            <input type="text" id="expiry_date" name="expiry_date" placeholder="YYMM" maxlength="4" required>
        </div>
        <div class="form-group">
            <label for="card_security_code">CVV *</label>
            <input type="text" id="card_security_code" name="card_security_code" placeholder="123" maxlength="4" required>
        </div>
    </div>
    
    <div class="form-group">
        <label for="card_holder_name">Cardholder Name</label>
        <input type="text" id="card_holder_name" name="card_holder_name" placeholder="John Smith" maxlength="50">
    </div>
    
    <div class="form-group">
        <input type="hidden" name="remember_me" value="YES">
    </div>
    
    <button type="submit" class="tokenize-button">Securely Save Card</button>
</form>';

echo $tokenization_form;
?>

# Frontend: HTML form for tokenization (HTTPS POST from client browser)
# Note: Tokenization must use HTML form submission, not direct cURL

cat << 'EOF' > tokenization_form.html
<!DOCTYPE html>
<html>
<head><title>Secure Tokenization</title></head>
<body>
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage">
    <input type="hidden" name="service_command" value="TOKENIZATION">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="return_url" value="https://www.merchant.com/tokenization-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card fields filled by customer -->
    <input type="text" name="card_number" placeholder="Card Number" required>
    <input type="text" name="expiry_date" placeholder="YYMM" required>
    <input type="text" name="card_security_code" placeholder="CVV" required>
    <input type="text" name="card_holder_name" placeholder="Cardholder Name">
    <input type="hidden" name="remember_me" value="YES">
    
    <button type="submit">Save Card Securely</button>
</form>
</body>
</html>
EOF

echo "Tokenization form created - open tokenization_form.html in browser"

Sample Tokenization Response

<!-- Tokenization response received as POST form data to your return_url -->
service_command=TOKENIZATION&access_code=zx0IPmPy5jp1vAz
&merchant_identifier=CycHZxVj&
merchant_reference=TOKEN-XYZ9239-yu898&language=en&expiry_date=2105
&card_number=400555******0001
&signature=c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4
&token_name=COp9Vmp&
response_message=Success&response_code=18000&status=18&card_bin=400555&
card_holder_name=John+Smith&remember_me=YES
&return_url=https%3A//www.merchant.com/tokenization-callback

Create Token

The CREATE_TOKEN service allows you to create permanent tokens for saved cards without processing a payment. This service is ideal for card-on-file scenarios where you want to securely store customer payment methods for future use.

The CREATE_TOKEN is not recommended since card is not validated and may increase future payment failures, we recommend using the TOKENIZATION instead, which provides better security and user experience.

Request Format

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Submission: HTML Form (Client-side HTTPS POST)

CREATE_TOKEN requests must be submitted as HTTPS POST forms directly from the client browser to ensure card data never touches your server.

Request Parameters

Parameter
service_command   Alpha Max: 20 Required Service command for create token request. Value: CREATE_TOKEN Example. CREATE_TOKEN
access_code   Alphanumeric Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Special characters: - _ . Example. XYZ9239-yu898
language   Alpha Max: 2 Required Create token page and response language. Supported values: en (English) or ar (Arabic). Example. en
card_number   Numeric Max: 19 Required Complete credit card number. MEEZA cards: 19 digits, AMEX: 15 digits, Others: 16 digits. Example. 4005550000000001
expiry_date   Numeric Max: 4 Required Card expiry date in YYMM format. Must be a future date. Example. 2105
return_url   Alphanumeric Max: 400 Required URL where customer will be redirected after token creation completion. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com/create-token-callback
signature   Alphanumeric Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
currency   Alpha Max: 3 Required Three-letter ISO 4217 currency code. Required for token creation context. Example. USD
token_name   Alphanumeric Max: 100 Optional Custom token name for identification. If not provided, system will generate one. Special characters: . @ - _ Example. CustomerCard123
card_holder_name   Alpha Max: 50 Optional Cardholder name as it appears on the card. Alphabetic characters, spaces, hyphens, periods, and apostrophes allowed. Special characters: ' - . Example. John Smith

Exclude these parameters when calculating the signature for CREATE_TOKEN requests:

• card_number, expiry_date, card_holder_name

This ensures sensitive card data is not included in signature calculations.

Response Parameters

Parameter
service_command   Alpha Max: 20 Service command from the request. Value: CREATE_TOKEN Example. CREATE_TOKEN
access_code   Alphanumeric Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Unique order reference from the request. Example. XYZ9239-yu898
language   Alpha Max: 2 Language used for the token creation process. Example. en
card_number   Numeric Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001*
expiry_date   Numeric Max: 4 Card expiry date from the request. Example. 2105
return_url   Alphanumeric Max: 400 Return URL from the request. Example. https://www.merchant.com/create-token-callback
signature   Alphanumeric Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
currency   Alpha Max: 3 Currency code from the request. Example. USD
token_name   Alphanumeric Max: 100 Generated or provided token name for future payment processing. Example. CustomerCard123
card_holder_name   Alpha Max: 50 Cardholder name from the request. Example. John Smith
response_message   Alphanumeric Max: 150 Human-readable response description in requested language. Example. Success
response_code   Numeric Max: 5 Numeric response code indicating token creation result. Example. 18000
status   Numeric Max: 2 Two-digit status code indicating token creation state. Example. 18

CREATE_TOKEN Sample Request

<!-- HTTPS POST form submitted directly to APS from client browser -->
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="create_token_form">
    
    <!-- Required CREATE_TOKEN Parameters -->
    <input type="hidden" name="service_command" value="CREATE_TOKEN">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="CREATE-TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="return_url" value="https://www.merchant.com/create-token-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card input fields (client-side only) -->
    <div class="form-group">
        <label for="card_number">Card Number *</label>
        <input type="text" 
               id="card_number" 
               name="card_number" 
               placeholder="1234 5678 9012 3456"
               maxlength="19"
               required>
    </div>
    
    <div class="form-group">
        <label for="expiry_date">Expiry Date *</label>
        <input type="text" 
               id="expiry_date" 
               name="expiry_date" 
               placeholder="YYMM"
               maxlength="4"
               required>
    </div>
    
    <div class="form-group">
        <label for="card_holder_name">Cardholder Name</label>
        <input type="text" 
               id="card_holder_name" 
               name="card_holder_name" 
               placeholder="John Smith"
               maxlength="50">
    </div>
    
    <div class="form-group">
        <label for="token_name">Token Name (Optional)</label>
        <input type="text" 
               id="token_name" 
               name="token_name" 
               placeholder="CustomerCard123"
               maxlength="100">
    </div>
    
    <button type="submit" class="create-token-button">
        Create Secure Token
    </button>
</form>

# Frontend: HTML form for CREATE_TOKEN (HTTPS POST from client browser)
create_token_form = '''
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="create_token_form">
    <input type="hidden" name="service_command" value="CREATE_TOKEN">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="CREATE-TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="return_url" value="https://www.merchant.com/create-token-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card input fields -->
    <div class="form-group">
        <label for="card_number">Card Number *</label>
        <input type="text" id="card_number" name="card_number" placeholder="1234 5678 9012 3456" maxlength="19" required>
    </div>
    
    <div class="form-group">
        <label for="expiry_date">Expiry Date *</label>
        <input type="text" id="expiry_date" name="expiry_date" placeholder="YYMM" maxlength="4" required>
    </div>
    
    <div class="form-group">
        <label for="card_holder_name">Cardholder Name</label>
        <input type="text" id="card_holder_name" name="card_holder_name" placeholder="John Smith" maxlength="50">
    </div>
    
    <div class="form-group">
        <label for="token_name">Token Name (Optional)</label>
        <input type="text" id="token_name" name="token_name" placeholder="CustomerCard123" maxlength="100">
    </div>
    
    <button type="submit" class="create-token-button">Create Secure Token</button>
</form>
'''

<?php
// Frontend: HTML form for CREATE_TOKEN (HTTPS POST from client browser)
$create_token_form = '
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="create_token_form">
    <input type="hidden" name="service_command" value="CREATE_TOKEN">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="CREATE-TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="return_url" value="https://www.merchant.com/create-token-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card input fields -->
    <div class="form-group">
        <label for="card_number">Card Number *</label>
        <input type="text" id="card_number" name="card_number" placeholder="1234 5678 9012 3456" maxlength="19" required>
    </div>
    
    <div class="form-group">
        <label for="expiry_date">Expiry Date *</label>
        <input type="text" id="expiry_date" name="expiry_date" placeholder="YYMM" maxlength="4" required>
    </div>
    
    <div class="form-group">
        <label for="card_holder_name">Cardholder Name</label>
        <input type="text" id="card_holder_name" name="card_holder_name" placeholder="John Smith" maxlength="50">
    </div>
    
    <div class="form-group">
        <label for="token_name">Token Name (Optional)</label>
        <input type="text" id="token_name" name="token_name" placeholder="CustomerCard123" maxlength="100">
    </div>
    
    <button type="submit" class="create-token-button">Create Secure Token</button>
</form>';

echo $create_token_form;
?>

# Frontend: HTML form for CREATE_TOKEN (HTTPS POST from client browser)
# Note: CREATE_TOKEN must use HTML form submission, not direct cURL

cat << 'EOF' > create_token_form.html
<!DOCTYPE html>
<html>
<head><title>Create Secure Token</title></head>
<body>
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage">
    <input type="hidden" name="service_command" value="CREATE_TOKEN">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="CREATE-TOKEN-XYZ9239-yu898">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="return_url" value="https://www.merchant.com/create-token-callback">
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Card fields filled by customer -->
    <input type="text" name="card_number" placeholder="Card Number" required>
    <input type="text" name="expiry_date" placeholder="YYMM" required>
    <input type="text" name="card_holder_name" placeholder="Cardholder Name">
    <input type="text" name="token_name" placeholder="Token Name (Optional)">
    
    <button type="submit">Create Secure Token</button>
</form>
</body>
</html>
EOF

echo "CREATE_TOKEN form created - open create_token_form.html in browser"

Sample CREATE_TOKEN Response

<!-- CREATE_TOKEN response received as POST form data to your return_url -->
service_command=CREATE_TOKEN&access_code=zx0IPmPy5jp1vAz
&merchant_identifier=CycHZxVj&
merchant_reference=CREATE-TOKEN-XYZ9239-yu898&language=en&
card_number=400555******0001&expiry_date=2105
&return_url=https%3A//www.merchant.com/create-token-callback
&signature=c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4
&currency=USD&token_name=CustomerCard123&
card_holder_name=John+Smith&
response_message=Success&response_code=18000&status=18

Payment Processing

Upon successful tokenization, the response is returned to your configured or designated return URL. The provided token can then be used to process payments securely, eliminating the need to handle sensitive card data directly.

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   Alpha Max: 20 Required Transaction type to be executed. AUTHORIZATION for auth-only transactions, PURCHASE for immediate capture. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   Alphanumeric Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Special characters: - _ . Example. XYZ9239-yu898
amount   Numeric Max: 10 Required Payment amount in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer. Example. 10000
currency   Alpha Max: 3 Required Three-letter ISO 4217 currency code for the payment amount. Example. AED
language   Alpha Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
customer_email   Alphanumeric Max: 254 Required Valid customer email address for payment notifications and receipt delivery. Special characters: _ - . @ + Example. customer@domain.com
customer_ip   Alphanumeric Max: 45 Required Customer's IP address for fraud prevention. Mandatory if fraud service is active. Supports both IPv4 and IPv6 formats. Special characters: . : Example. 192.178.1.10
token_name   Alphanumeric Max: 100 Required Token generated from the tokenization process. Special characters: . @ - _ Example. Op9Vmp
signature   Alphanumeric Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
payment_option   Alpha Max: 10 Optional Payment option for the transaction. Values: MASTERCARD, VISA, AMEX, MADA (for Purchase operations and eci Ecommerce only), MEEZA (for Purchase operations and ECOMMERCE eci only) Example. VISA
eci   Alpha Max: 16 Optional Ecommerce indicator. Values: ECOMMERCE Example. ECOMMERCE
order_description   Alphanumeric Max: 150 Optional Human-readable description of the order or service being paid for. Special characters: ' / . _ - # : $ Space Example. iPhone 6-S
card_security_code   Numeric Max: 4 Optional Card security code (CVV/CVC). Only AMEX accepts 4 digits, others accept 3 digits. Example. 123
customer_name   Alpha Max: 40 Optional Full name of the customer making the payment. Special characters: _ \ / - . ' Space Example. John Smith
merchant_extra   Alphanumeric Max: 999 Optional Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Optional Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Optional Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Optional Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250 Optional Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250 Optional Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters: . ; / _ - , ' @ Example. JohnSmith
remember_me   Alpha Max: 3 Optional Indication to save this token for the user based on user selection. Tokenization service must be activated. Values: YES, NO Example. YES
phone_number   Alphanumeric Max: 19 Optional Customer phone number in international format for verification and notifications. Special characters: + - ( ) Space Example. 00962797219966
settlement_reference   Alphanumeric Max: 22 Optional Unique value submitted by merchant, passed to acquiring bank and displayed in acquirer settlement file. Special characters: - _ . Example. XYZ9239-yu898
return_url   Alphanumeric Max: 400 Optional URL where customer will be redirected after payment completion. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com
agreement_id   Alphanumeric Max: 15 Optional Identifier for the agreement with the payer to process payments for recurring payments. Do not use any special characters. Example. AGR123456789
recurring_mode   Alphanumeric Max: 20 Optional Indicates if subsequent payments within the agreement have same/different amount or are unscheduled. Values: UNSCHEDULED, VARIABLE, FIXED Example. UNSCHEDULED
recurring_transactions_count   Alphanumeric Max: 100 Optional Number of merchant-initiated payments within the recurring payment agreement. Required if recurring_mode = VARIABLE or FIXED. Example. 12
recurring_expiry_date   Numeric Max: 10 Optional Date when merchant needs to end the recurring payments. Format: YYYY-MM-DD. Special characters: - Example. 2024-10-05
recurring_days_between_payments   Numeric Max: 10 Optional Number of days between payments agreed with the payer under the agreement. Numeric only. Example. 30

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
command   Alpha Max: 20 Transaction type executed. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   Alphanumeric Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz
merchant_identifier   Alphanumeric Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Unique order reference from the request. Example. XYZ9239-yu898
amount   Numeric Max: 10 Transaction amount processed. Example. 10000
currency   Alpha Max: 3 Currency code used for the transaction. Example. AED
language   Alpha Max: 2 Language used for the response. Supported values: en/ar. Example. en
customer_email   Alphanumeric Max: 254 Customer email address used. Example. customer1@domain.com
customer_ip   Alphanumeric Max: 45 Customer's IP address. Supports IPv4 and IPv6 formats. Example. 192.178.1.10
token_name   Alphanumeric Max: 100 Token used for the payment. Example. COp9Vmp
signature   Alphanumeric Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Numeric Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
payment_option   Alpha Max: 10 Payment method used for the transaction. Values: MASTERCARD, VISA, AMEX, MADA (for Purchase operations and eci Ecommerce only), MEEZA (for Purchase operations and ECOMMERCE eci only) Example. VISA
eci   Alpha Max: 16 Ecommerce indicator. Values: ECOMMERCE Example. ECOMMERCE
order_description   Alphanumeric Max: 150 Description of the order. Example. iPhone 6-S
authorization_code   Alphanumeric Max: 100 Authorization code returned from the 3rd party. Example. P1000000000000372136
response_message   Alphanumeric Max: 150 Message description of the response code. 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 consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example. 20064
customer_name   Alpha Max: 40 Customer's name. Example. John Smith
merchant_extra   Alphanumeric Max: 999 Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250

3D Secure Authentication

After submitting a payment request, 3D Secure authentication may be required based on the customer's card and issuing bank requirements. If 3DS is required, you must redirect the customer to the 3DS authentication URL provided in the response, otherwise the transaction will not be completed.

PURCHASE/AUTH Sample Request

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "amount": "10000",
  "currency": "USD",
  "language": "en",
  "customer_email": "customer@example.com",
  "token_name": "COp9Vmp",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

# Payment request using token
import requests

# Payment request data
payment_request = {
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": "10000",
    "currency": "USD",
    "language": "en",
    "customer_email": "customer@example.com",
    "token_name": "COp9Vmp",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

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

print(response.json())

<?php
// Payment request using token
$payment_request = [
    "command" => "PURCHASE",
    "access_code" => "zx0IPmPy5jp1vAz",
    "merchant_identifier" => "CycHZxVj",
    "merchant_reference" => "XYZ9239-yu898",
    "amount" => "10000",
    "currency" => "USD",
    "language" => "en",
    "customer_email" => "customer@example.com",
    "token_name" => "COp9Vmp",
    "signature" => "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
];

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

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

echo $response;
?>

# Payment request using token

# Example: Payment request using cURL
curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": "10000",
    "currency": "USD",
    "language": "en",
    "customer_email": "customer@example.com",
    "token_name": "COp9Vmp",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

Sample Payment Response

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "amount": "10000",
  "currency": "USD",
  "language": "en",
  "customer_email": "customer@example.com",
  "token_name": "COp9Vmp",
  "fort_id": "149295435400084008",
  "payment_option": "VISA",
  "authorization_code": "P1000000000000372136",
  "response_message": "Success",
    "response_code": "14000",
  "status": "20",
  "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4"
}

Client-side Validation

Download the complete client-side validation library that provides comprehensive validation for all payment form fields including card number validation with Luhn algorithm, expiry date validation, CVV validation, and cardholder name validation.
Click to download the file

Response Codes

The response of the payment transaction will be sent to your return URL and to your configured webhook.
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:

• Tokenization URL: https://sbcheckout.payfort.com/FortAPI/paymentPage
• Payment 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