Integrate PCI-Certified Custom Integration

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

This guide walks you through implementing Custom Integration for PCI DSS Level 1 certified merchants using direct payment processing. This method provides full control over payment processing and card data handling for enterprises with existing secure infrastructure.

Prerequisites

Before starting your integration, ensure you have:

1. PCI DSS Level 1 Compliance
   This integration method requires active PCI DSS Level 1 certification, including:

   • Valid PCI DSS certification.
   • PCI DSS onsite assessment.
   • Regular security assessments and compliance audits.

2. Test Account Access
   Contact merchantsupport-ps@amazon.com to obtain access to our test environment for testing and development.

3. Security Credentials
   Retrieve your integration credentials from the merchant dashboard:

   1. Log into your Amazon Payment Services test account
   2. Navigate to Merchant Management → Security Settings
   3. Save the following values:
      • Access Code - Authentication token for API requests
      • Merchant Identifier - Your unique merchant ID
      • SHA Request/Response - Keys for signature calculation

Integration Steps

1

Create Payment Form

Create Payment Form

Build a custom payment form on your checkout page to collect customer card details. The form must be hosted on PCI DSS Level 1 compliant infrastructure and include proper validation and security enhancements.

<!-- This form must be hosted on PCI DSS Level 1 compliant infrastructure -->
<form id="securePaymentForm" class="secure-payment-form" method="post">
    <div class="form-group">
        <label for="cardNumber">Card Number</label>
        <input type="text" id="cardNumber" name="card_number" 
               placeholder="1234 5678 9012 3456" 
               maxlength="19" 
               autocomplete="cc-number" 
               required>
        <div class="error-message" id="cardNumberError"></div>
    </div>
    
    <div class="form-row">
        <div class="form-group">
            <label for="expiryDate">Expiry Date</label>
            <input type="text" id="expiryDate" name="expiry_date" 
                   placeholder="YYMM" 
                   maxlength="4" 

2

Process Payment

Process Payment

Process payments directly through server-to-server API calls. This approach requires strict PCI compliance but provides full control over the payment process.

Use the appropriate endpoint based on your environment:

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

https://paymentservices.payfort.com/FortAPI/paymentApi

Sample Direct Payment Request

{
    "command": "PURCHASE",
    "access_code": "s4lwuuoY5upZlZY5D6dr",
    "merchant_identifier": "WeVJHPYm",
    "merchant_reference": "ORD-12345-2024",
    "amount": "2000",
    "currency": "AED",
    "language": "en",
    "customer_email": "customer@example.com",
    "card_number": "4557012345678902",
    "expiry_date": "2505",
    "card_security_code": "123",
    "card_holder_name": "John Doe",
    "customer_ip": "192.168.1.1",
    "signature": "calculated_signature_here"
}

Make sure merchant reference value is unique value per request.

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

Before sending the transaction amount, multiply it by the currency's decimal factor based on its ISO 3-letter code, e.g. AED (2 decimals): 500 AED should be sent in the request as 50000. For currencies with 3 decimal places, VISA requires amounts to be rounded to end in zero, E.g 3.475 becomes 3480.

Sample Direct Payment Response

{
    "command": "PURCHASE",
    "access_code": "s4lwuuoY5upZlZY5D6dr",
    "merchant_identifier": "WeVJHPYm",
    "merchant_reference": "ORD-12345-2024",
    "amount": "2000",
    "currency": "AED",
    "language": "en",
    "customer_email": "customer@example.com",
    "card_number": "455701******8902",
    "expiry_date": "2505",
    "card_holder_name": "John Doe",
    "response_code": "20064",
    "response_message": "3-D Secure check requested",
    "status": "20",
    "3ds_url": "https://sbcheckout.payfort.com/FortAPI/paymentPage?PaymentRequestId=...",
    "signature": "calculated_response_signature"
}

3

Handle 3D Secure Authentication

Handle 3D Secure Authentication

If 3D Secure authentication is required, redirect the customer to the provided 3DS URL. After authentication, the customer will be redirected back to your return URL with the final transaction status.

You will not receive a 3D Secure URL in the response if 3DS is downgraded using Flex 3D Secure or by sending the check_3ds parameter with value NO in the payment request.

If you plan to enable recurring payments for future transactions, make sure to store the agreement_id returned in the response to process future recurring payments.

For detailed parameter specifications, refer to our Custom Integration API Reference.

Check transaction status

To check the transaction status, check the Check a Transaction Status section.

Handling the response

If you have a webhook, check the webhook section to understand how we send transaction responses to your system.

Go-live

Test your integration using one of our testing cards.
Make sure to visit our go-live checklist to go live with your integration.

Support

Need help with your integration? Contact our technical support team at merchantsupport-ps@amazon.com.