Integrate Non-PCI 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 Non-PCI certified merchants using the secure tokenization approach. This method allows you to build custom payment experiences while Amazon Payment Services handles PCI compliance requirements.

Prerequisites

Before starting your integration, ensure you have:

Test Account Access
Contact merchantsupport-ps@amazon.com to obtain access to our test environment for testing and development.
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

Create Payment Form

Build a custom payment form on your checkout page to collect customer card details. The form should include proper validation and user experience enhancements.

<form id="paymentForm" class="payment-form">
    <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" 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="MM/YY" maxlength="5" required>
            <div class="error-message" id="expiryError"></div>
        </div>
        
        <div class="form-group">
            <label for="cvv">CVV</label>

Tokenization Request

When the customer submits the payment form, you can either do tokenization or create token as HTTPS POST FORM directly from your frontend to Amazon Payment Services.

TOKENIZATION: Securely converts card details into a temporary token for immediate payment processing
CREATE_TOKEN: Generates permanent tokens without charging customers

Use the appropriate endpoint based on your environment:

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

Sample Tokenization/Create Token Request

<form action="https://sbcheckout.payfort.com/FortAPI/paymentPage" 
      method="post" target="form" id="paymentForm">
    <input type="hidden" name="service_command" value="TOKENIZATION">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="merchant_identifier" value="WeVJHPYm">
    <input type="hidden" name="access_code" value="s4lwuuoY5upZlZY5D6dr">
    <input type="hidden" name="signature" value="calculated_signature_here">
    <input type="hidden" name="return_url" value="https://yoursite.com/tokenization-result">
    <input type="hidden" name="expiry_date" value="2505">
    <input type="hidden" name="card_number" value="4557012345678902">
    <input type="hidden" name="card_security_code" value="123">
    <input type="hidden" name="merchant_reference" value="ORD-12345-2024">
    <input type="hidden" name="card_holder_name" value="John Doe">
</form>

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 Tokenization Response

{
    "access_code": "s4lwuuoY5upZlZY5D6dr",
    "card_bin": "455701",
    "card_holder_name": "John Doe",
    "card_number": "455701******8902",
    "expiry_date": "2505",
    "language": "en",
    "merchant_identifier": "WeVJHPYm",
    "merchant_reference": "ORD-12345-2024",
    "response_code": "18000",
    "response_message": "Success",
    "return_url": "https://yoursite.com/tokenization-result",
    "service_command": "TOKENIZATION",
    "signature": "e59ff5567f5308657f24d29234deccf6e7f9dcf6bd9ecf9efa8281bc5ee3319c",
    "status": "18",
    "token_name": "8bc8ba22dcc34b838024ef03f8d89786",
    "client_ip": "192.168.1.1"
}

Process Payment

After successful tokenization, use the received token to process the payment through a server-to-server API call. This step should be performed from your backend for security.

Use the appropriate endpoint based on your environment:

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

Sample 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",
    "signature": "calculated_signature_here",
    "token_name": "8bc8ba22dcc34b838024ef03f8d89786"
}

Use PURCHASE to capture the payment immediately
Use AUTHORIZATION to place a hold on the amount and capture it later

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.

Create Token vs Payment Tokenization

Aspect	Create Token Service	Payment Tokenization
Purpose	Generate permanent token without charging customer	Generate token during successful payment processing
Card Authentication	Card NOT authenticated by acquirer bank	Card authenticated by acquirer bank
Validation	Basic format validation only	Full payment validation
Risk Level	Higher risk of future payment failures	Lower risk due to validated card

When using create_token service, since the card is not authenticated by the acquirer bank, there's a higher risk of transaction failures in subsequent payments due to card validity issues.

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.

Prerequisites​

Integration Steps​

Create Payment Form​

Tokenization Request​

Sample Tokenization/Create Token Request​

Sample Tokenization Response​

Process Payment​

Sample Payment Request​

Handle 3D Secure Authentication​

Create Token vs Payment Tokenization​

Check transaction status​

Handling the response​

Go-live​

Support​