API Reference

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

Amazon Payment Services provides a comprehensive suite of APIs designed for seamless payment processing integration. This reference guide covers authentication, request/response handling, and implementation patterns for production-ready payment solutions.

Quick Start

Get Credentials

Secure your sandbox access and API authentication keys

Choose Integration

Select the optimal integration approach for your use case

Make API Calls

Implement secure API requests with proper validation

Handle Responses

Process responses and configure webhook endpoints

1

Retrieve API Credentials

Retrieve API Credentials

Before implementing API calls, ensure you have a test account ready.

Navigate to Merchant Management → Security Settings and collect the following authentication parameters:

Parameter	Type	Description	Security Level
access_code	String	Unique merchant access identifier	Confidential
merchant_identifier	String	Merchant account routing ID	Confidential
sha_request_phrase	String	Request signature secret key	Highly Confidential
sha_response_phrase	String	Response validation secret key	Highly Confidential

• Environment Variables: Store all credentials in environment variables, never in source code
• Access Control: Restrict credential access to authorized personnel only
• Key Rotation: Rotate SHA phrases every 90 days for enhanced security
• Network Security: Use HTTPS/TLS 1.2+ for all API communications

2

Select Integration Method

Select Integration Method

Choose the appropriate integration pattern based on your technical requirements, PCI compliance scope, and user experience goals.

Integration Type	Implementation Complexity	Customization Level	Time to Market
Payment Links	Very Low	Low	Fastest
Hosted Checkout	Low	Low	Fastest
Mobile Integration	Medium	None	Medium
Custom Integration (Non-PCI)	High	High	High
Custom Integration (PCI)	High	High	High

3

Implement API Requests

Implement API Requests

All Amazon Payment Services API endpoints follow standardized request/response patterns and mandatory signature validation.

Every API request must include these foundational parameters:

Required Parameters Schema

{
  "service_command" or "command": "TOKENIZATION" or "PURCHASE",
  "access_code": "string (required)",
  "merchant_identifier": "string (required)", 
  "merchant_reference": "string (required, unique)",
  "language": "string (required, en|ar)",
  "signature": "string (required, SHA-256)"
}

API Request Examples

{
  "service_command": "PAYMENT_LINK",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "INV-2024-001",
  "amount": "125000",
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "customer_name": "John Smith",
  "request_expiry_date": "2024-12-31T23:59:59+04:00",
  "notification_type": "EMAIL",
  "order_description": "Premium subscription - 1 year",
  "return_url": "https://yoursite.com/payment-success",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

<!-- 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">
    

<!-- 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">

# Server-to-server API request for custom integration
{
    "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"
  }

• Parameter Validation: Validate all parameters before signature calculation
• Amount Format: Always use minor currency units (cents for USD, fils for AED)
• Unique References: Generate unique merchant_reference for each transaction
• Signature Security: Never log or expose SHA phrases in application logs

4

Response Handling

Response Handling

Implement robust response processing with signature validation, error handling, and webhook integration for real-time transaction updates. check out our detailed Webhook Documentation.

5

Testing & Validation

Testing & Validation

Test Cards: Use our comprehensive Testing Cards

6

Go Live

Go-Live Process

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

Developer Resources

Complete Documentation

Comprehensive integration guides and API references

SDKs & Libraries

Official SDKs for popular programming languages

Testing Tools

Test cards and Postman collections for integration testing

Error Codes

Complete reference for troubleshooting API responses

• Developer Support: integration-ps@amazon.com