Hosted Checkout 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 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   String Max: 20 Required Transaction type to be executed. AUTHORIZATION for auth-only transactions, PURCHASE for immediate capture. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings → Security 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 order reference that must be unique per merchant. Alphanumeric characters, hyphens (-), underscores (_), and periods (.) allowed. Example. XYZ9239-yu898
amount   Integer 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   String Max: 3 Required Three-letter ISO 4217 currency code. Example. AED
language   String Max: 2 Required Response language for error messages and transaction descriptions. Values: en, ar Example. en
customer_email   String Max: 254 Required Customer's valid email address for transaction receipts and notifications. Must follow standard email format (user@domain.com). Example. customer@example.com
signature   String Max: 200 Required SHA-256 HMAC signature calculated using your secret key and request parameters for authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name   String Max: 100 Optional Previously saved payment token for returning customers or generated token for future payments. Example. Op9Vmp
payment_option   String Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, SADAD, NAPS, KNET, etc. Example. VISA
eci   String Max: 16 Optional Electronic Commerce Indicator classifying the transaction channel. Values: ECOMMERCE Example. ECOMMERCE
order_description   String Max: 150 Optional Descriptive text about the purchase that appears in transaction records and may be shown to customers. Example. Premium Subscription - 12 months
statement_descriptor   String Max: 50 Optional Custom text that appears on the customer's credit card statement. Use your business name or recognizable identifier. Example. TECHSTORE ONLINE
customer_ip   String 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. Example. 192.178.1.10
customer_name   String Max: 40 Optional Customer's full name as provided during checkout. Example. John Smith
phone_number   String Max: 19 Optional Customer's phone number in international format (country code + number). Used for transaction verification and notifications. Example. 971501234567
return_url   String Max: 400 Optional Custom URL where customer will be redirected after payment completion. Example. https://www.merchant.com/return
remember_me   String Max: 2 Optional Enable token generation for future payments. Customer can opt-in during checkout. Values: NO Example. NO
settlement_reference   String Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Example. XYZ9239-yu898
merchant_extra   String Max: 999 Optional Custom field for storing additional transaction metadata. This data is returned in responses and webhook notifications. Example. customer_id:12345,campaign:summer2024
merchant_extra1   String Max: 250 Optional Additional custom field for merchant-specific data such as product categories or sales channels. Example. product_category:electronics
merchant_extra2   String Max: 250 Optional Additional custom field for storing order-specific information like shipping methods or promotional codes. Example. shipping_method:express
merchant_extra3   String Max: 250 Optional Additional custom field for integration-specific data such as affiliate IDs or marketing campaign codes. Example. affiliate_id:partner123
merchant_extra4   String Max: 250 Optional Additional custom field for business-specific metadata like sales representative IDs or store locations. Example. store_location:dubai_mall
merchant_extra5   String Max: 250 Optional Additional custom field for extended transaction context such as subscription plan details or loyalty program information. Example. subscription_plan:premium_annual
agreement_id   String Max: 15 Optional Identifier for recurring payment agreements. Example. AGR123456789
recurring_mode   String Max: 20 Optional Indicates this transaction is part of a recurring payment setup. Values: UNSCHEDULED, VARIABLE, FIXED Example. UNSCHEDULED
recurring_transactions_count   Integer Max: 100 Optional Number of payments in recurring agreement. Required for VARIABLE or FIXED recurring modes. Example. 12
recurring_expiry_date   Date Format: YYYY-MM-DD Optional End date for recurring payment agreement in ISO date format. Example. 2024-10-05
recurring_days_between_payments   Integer 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   String Max: 20 Transaction type executed. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
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 order reference from the request. Example. XYZ9239-yu898
amount   Integer Max: 10 Transaction amount processed. Example. 10000
currency   String Max: 3 Currency code used for the transaction. Example. AED
language   String Max: 2 Language used for the checkout page. Example. en
customer_email   String Max: 254 Customer email address used. Example. customer1@domain.com
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Integer Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
payment_option   String Max: 10 Payment method used by customer. Example. VISA
token_name   String Max: 100 Generated token for future payments (if tokenization enabled). Example. Op9Vmp
authorization_code   String Max: 100 Authorization code from payment processor. Example. P1000000000000372136
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   Integer Max: 5 Numeric response code indicating transaction result. Example. 14000
status   Integer Max: 2 Two-digit status code indicating transaction state. Example. 20
card_holder_name   String Max: 50 Name on the payment card used. Example. John Smith
expiry_date   String Max: 4 Masked card expiry date (MMYY format). Example. 2105
card_number   String 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