Hosted Checkout API

Copy page

Copy page as Markdown for LLMs

Open in Claude

Ask questions about this page

The hosted checkout integration allows merchants to redirect customers to a secure Amazon Payment Services payment page where they can enter their payment details and complete transactions. This approach reduces PCI compliance requirements while providing a trusted payment environment.

API Endpoints

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

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

Request Format

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Submission: HTML Form (Client-side 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 → Security Settings. Example. zx0IPmPy5jp1vAz8Kpg7
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. Special characters: - _ . Example. XYZ9239-yu898
amount   Numeric Max: 10 Required Transaction amount in smallest currency unit (no decimal points). For AED: multiply by 100 (1.00 AED = 100), for USD: multiply by 100 (1.00 USD = 100), for KWD: multiply by 1000 (1.000 KWD = 1000). Example. 10000
currency   Alpha Max: 3 Required Three-letter ISO 4217 currency code. Example. AED
language   Alpha Max: 2 Required Response language for error messages and transaction descriptions. Values: en, ar Example. en
customer_email   Alphanumeric Max: 254 Required Customer's valid email address for transaction receipts and notifications. Must follow standard email format (user@domain.com). Special characters: _ - . @ + Example. customer@example.com
signature   Alphanumeric Max: 200 Required SHA-256 HMAC signature calculated using your secret key and request parameters for authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name   Alphanumeric Max: 100 Optional Previously saved payment token for returning customers or generated token for future payments. Special characters: . @ - _ Example. Op9Vmp
payment_option   Alpha Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, SADAD, NAPS, KNET, etc. Example. VISA
eci   Alpha Max: 16 Optional Electronic Commerce Indicator classifying the transaction channel. Values: ECOMMERCE Example. ECOMMERCE
order_description   Alphanumeric Max: 150 Optional Descriptive text about the purchase that appears in transaction records and may be shown to customers. Special characters: ' / . _ - # : $ Space Example. Premium Subscription - 12 months
statement_descriptor   Alphanumeric Max: 50 Optional Custom text that appears on the customer's credit card statement. Use your business name or recognizable identifier. Special characters: - Example. TECHSTORE ONLINE
customer_ip   Alphanumeric Max: 45 Optional Customer's public IP address at the time of payment initiation. Used for fraud detection and geolocation verification. Supports both IPv4 and IPv6 formats. Special characters: . : Example. 192.178.1.10
customer_name   Alpha Max: 40 Optional Customer's full name as provided during checkout. Special characters: _ \ / - . ' Space Example. John Smith
phone_number   Alphanumeric Max: 19 Optional Customer's phone number in international format (country code + number). Used for transaction verification and notifications. Special characters: + - ( ) Space Example. 971501234567
return_url   Alphanumeric Max: 400 Optional Custom URL where customer will be redirected after payment completion. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com/return
remember_me   Alpha Max: 2 Optional Enable token generation for future payments. Customer can opt-in during checkout. Values: NO Example. NO
settlement_reference   Alphanumeric Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Special characters: - _ . Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999 Optional Custom field for storing additional transaction metadata. This data is returned in responses and webhook notifications. Special characters: . ; / _ - , ' @ Example. customer_id:12345,campaign:summer2024
merchant_extra1   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data such as product categories or sales channels. Special characters: . ; / _ - , ' @ Example. product_category:electronics
merchant_extra2   Alphanumeric Max: 250 Optional Additional custom field for storing order-specific information like shipping methods or promotional codes. Special characters: . ; / _ - , ' @ Example. shipping_method:express
merchant_extra3   Alphanumeric Max: 250 Optional Additional custom field for integration-specific data such as affiliate IDs or marketing campaign codes. Special characters: . ; / _ - , ' @ Example. affiliate_id:partner123
merchant_extra4   Alphanumeric Max: 250 Optional Additional custom field for business-specific metadata like sales representative IDs or store locations. Special characters: . ; / _ - , ' @ Example. store_location:dubai_mall
merchant_extra5   Alphanumeric Max: 250 Optional Additional custom field for extended transaction context such as subscription plan details or loyalty program information. Special characters: . ; / _ - , ' @ Example. subscription_plan:premium_annual
agreement_id   Alphanumeric Max: 15 Optional Identifier for recurring payment agreements. Do not use any special characters. Example. AGR123456789
recurring_mode   Alphanumeric Max: 20 Optional Indicates this transaction is part of a recurring payment setup. Values: UNSCHEDULED, VARIABLE, FIXED Example. UNSCHEDULED
recurring_transactions_count   Alphanumeric Max: 100 Optional Number of payments in recurring agreement. Required for VARIABLE or FIXED recurring modes. Example. 12
recurring_expiry_date   Numeric Format: YYYY-MM-DD Optional End date for recurring payment agreement in ISO date format. Special characters: - Example. 2024-10-05
recurring_days_between_payments   Numeric Optional Interval in days between recurring payments as agreed with customer. Example. 30

If the payment_option parameter is not specified, the hosted checkout automatically displays the relevant local payment methods based on the transaction currency and your Amazon Payment Services account configuration (e.g., STC Pay for SAR, KNET for KWD, NAPS for QAR). When using these local payment methods, you must submit the request with the PURCHASE command, as using AUTHORIZATION will result in the error: “Operation not valid for this payment option".

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

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. zx0IPmPy5jp1vAz8Kpg7
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 checkout page. Example. en
customer_email   Alphanumeric Max: 254 Customer email address used. Example. customer1@domain.com
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 by customer. Example. VISA
token_name   Alphanumeric Max: 100 Generated token for future payments (if tokenization enabled). Example. Op9Vmp
authorization_code   Alphanumeric Max: 100 Authorization code from payment processor. Example. P1000000000000372136
response_message   Alphanumeric Max: 150 Human-readable response description in requested language. Example. Success
response_code   Numeric Max: 5 Numeric response code indicating transaction result. Example. 20064
status   Numeric Max: 2 Two-digit status code indicating transaction state. Example. 04
card_holder_name   Alpha Max: 50 Name on the payment card used. Example. John Smith
expiry_date   Numeric Max: 4 Masked card expiry date (YYMM format). Example. 2105
card_number   Numeric Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001*

Response Codes

The response of the 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.

Sample Request

<!-- HTTPS POST form submitted directly to APS from frontend -->

<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="hosted_checkout_form">
    
    <!-- Required Transaction Parameters -->
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="ORD-PREMIUM-2024-1725887587">
    
    <!-- Amount: AED 250.00 (25000 fils) -->
    <input type="hidden" name="amount" value="25000">
    <input type="hidden" name="currency" value="AED">
    <input type="hidden" name="language" value="en">
    
    <!-- Customer Information -->
    <input type="hidden" name="customer_email" value="john.smith@example.com">
    <input type="hidden" name="customer_ip" value="192.168.1.100">
    
    <!-- Order Details -->
    <input type="hidden" name="order_description" value="Premium Subscription - Annual Plan">
    
    <!-- Post-payment redirect URL -->
    <input type="hidden" name="return_url" value="https://www.mystore.com/payment/callback">
    
          <input type="hidden" name="signature" value="a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234">
    
    <!-- Submit button -->
    <button type="submit">Pay Securely with Amazon Payment Services</button>
    
</form>

# Frontend: Generate HTTPS POST form for hosted checkout
from flask import Flask, render_template_string

app = Flask(__name__)

@app.route('/checkout')
def checkout():
    # Generate HTML form for frontend submission
    form_html = '''
<!DOCTYPE html>
<html>
<head>
    <title>Secure Payment Checkout</title>
</head>
<body>
    <h2>Secure Payment Checkout</h2>
    <p>Redirecting to Amazon Payment Services secure gateway...</p>
    
    <!-- HTTPS POST form submitted directly from frontend -->
    <form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="checkout_form">
        <input type="hidden" name="command" value="PURCHASE">
        <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
        <input type="hidden" name="merchant_identifier" value="CycHZxVj">
        <input type="hidden" name="merchant_reference" value="ORD-PREMIUM-2024-1725887587">
        <input type="hidden" name="amount" value="25000">
        <input type="hidden" name="currency" value="AED">
        <input type="hidden" name="language" value="en">
        <input type="hidden" name="customer_email" value="john.smith@example.com">
        <input type="hidden" name="order_description" value="Premium Subscription - Annual Plan">
        <input type="hidden" name="return_url" value="https://www.mystore.com/payment/callback">
        <input type="hidden" name="signature" value="a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234">
        <button type="submit">Pay Now</button>
    </form>
    
    <!-- Auto-submit form -->
    <script>
        document.getElementById('checkout_form').submit();
    </script>
</body>
</html>'''
    
    return form_html

if __name__ == '__main__':
    app.run(debug=True)

<?php
// Frontend: Generate HTTPS POST form for hosted checkout

function generateCheckoutForm() {
    // Generate HTML form for frontend submission
    $formHtml = '<!DOCTYPE html>
<html>
<head>
    <title>Secure Payment Checkout</title>
</head>
<body>
    <h2>Secure Payment Checkout</h2>
    <p>Redirecting to Amazon Payment Services secure gateway...</p>
    
    <!-- HTTPS POST form submitted directly from frontend -->
    <form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="checkout_form">
        <input type="hidden" name="command" value="PURCHASE">
        <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
        <input type="hidden" name="merchant_identifier" value="CycHZxVj">
        <input type="hidden" name="merchant_reference" value="ORD-PREMIUM-2024-1725887587">
        <input type="hidden" name="amount" value="25000">
        <input type="hidden" name="currency" value="AED">
        <input type="hidden" name="language" value="en">
        <input type="hidden" name="customer_email" value="john.smith@example.com">
        <input type="hidden" name="order_description" value="Premium Subscription - Annual Plan">
        <input type="hidden" name="return_url" value="https://www.mystore.com/payment/callback">
        <input type="hidden" name="signature" value="a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234">
        <button type="submit">Pay Now</button>
    </form>
    
    <!-- Auto-submit form -->
    <script>
        document.getElementById("checkout_form").submit();
    </script>
</body>
</html>';
    
    return $formHtml;
}

// Usage
echo generateCheckoutForm();
?>

// Frontend: React component for HTTPS POST form submission
import React from 'react';

const APSCheckout = () => {
    const handleSubmit = (e) => {
        // Form will submit to APS via HTTPS POST
        console.log('Redirecting to Amazon Payment Services...');
    };
    
    return (
        <div className="checkout-container">
            <h2>Secure Payment Checkout</h2>
            <p>You will be redirected to Amazon Payment Services secure gateway</p>
            
            {/* HTTPS POST form submitted directly from frontend */}
            <form 
                method="post" 
                action="https://sbcheckout.payfort.com/FortAPI/paymentPage"
                onSubmit={handleSubmit}
                id="checkout_form"
            >
                <input type="hidden" name="command" value="PURCHASE" />
                <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7" />
                <input type="hidden" name="merchant_identifier" value="CycHZxVj" />
                <input type="hidden" name="merchant_reference" value="ORD-PREMIUM-2024-1725887587" />
                <input type="hidden" name="amount" value="25000" />
                <input type="hidden" name="currency" value="AED" />
                <input type="hidden" name="language" value="en" />
                <input type="hidden" name="customer_email" value="john.smith@example.com" />
                <input type="hidden" name="order_description" value="Premium Subscription - Annual Plan" />
                <input type="hidden" name="return_url" value="https://www.mystore.com/payment/callback" />
                <input type="hidden" name="signature" value="a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234" />
                
                <button type="submit" className="pay-button">
                    Pay Securely with APS
                </button>
            </form>
            
            <div className="security-notice">
                🔒 Your payment will be processed securely by Amazon Payment Services.
            </div>
        </div>
    );
};

export default APSCheckout;

# Frontend form submission via cURL (for testing purposes)
# In production, use HTML form submitted from browser

curl -X POST https://sbcheckout.payfort.com/FortAPI/paymentPage \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "command=PURCHASE" \
  -d "access_code=zx0IPmPy5jp1vAz8Kpg7" \
  -d "merchant_identifier=CycHZxVj" \
  -d "merchant_reference=ORD-PREMIUM-2024-1725887587" \
  -d "amount=25000" \
  -d "currency=AED" \
  -d "language=en" \
  -d "customer_email=john.smith@example.com" \
  -d "order_description=Premium Subscription - Annual Plan" \
  -d "return_url=https://www.mystore.com/payment/callback" \
  -d "signature=a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234"

# Note: For hosted checkout, use HTML form submission from browser
# cURL shown here for testing reference only

# Generate simple HTML form (bash example)
#!/bin/bash

cat << EOF > checkout_form.html
<!DOCTYPE html>
<html>
<head><title>Secure Checkout</title></head>
<body>
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage">
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="ORD-PREMIUM-2024-1725887587">
    <input type="hidden" name="amount" value="25000">
    <input type="hidden" name="currency" value="AED">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="customer_email" value="john.smith@example.com">
    <input type="hidden" name="order_description" value="Premium Subscription - Annual Plan">
    <input type="hidden" name="return_url" value="https://www.mystore.com/payment/callback">
    <input type="hidden" name="signature" value="a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234">
    <button type="submit">Pay Now</button>
</form>
</body>
</html>
EOF

echo "Checkout form generated for frontend submission"

Sample Response

command=PURCHASE
access_code=zx0IPmPy5jp1vAz8Kpg7
merchant_identifier=CycHZxVj
merchant_reference=ORD-PREMIUM-2024-1725887587
amount=25000
currency=AED
language=en
response_code=14000
response_message=Success
status=20
fort_id=149295435400084008
payment_option=VISA
authorization_code=P1000000000000372136
customer_email=john.smith@example.com
customer_name=John Smith
card_holder_name=John Smith
card_number=400555*****0001
expiry_date=2512
token_name=Op9VmpKj8Nm2Qx4
signature=b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2

Testing The Integration

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbcheckout.payfort.com/FortAPI/paymentPage
• Test Cards: Use our comprehensive Testing Cards

Go-Live Process

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