Frequently Asked Questions

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 comprehensive FAQ addresses the most common questions and challenges developers encounter when integrating with Amazon Payment Services (APS). Each section provides practical solutions, step-by-step guidance, and direct links to relevant documentation.

Can't find what you're looking for? Check our Error Codes Guide or contact our support team at merchantsupport-ps@amazon.com

New to APS? Start with our Getting Started Guide for a smooth onboarding experience.

Quick Navigation

Error Troubleshooting

Common error messages and their solutions with step-by-step fixes.

Integration Help

Payment flows, status checking, and response handling guidance.

Apple Pay Issues

Certificate problems, testing, and configuration solutions.

Services & Features

Tokenization, installments, 3D Secure, and recurring payments.

Mobile Integration

SDK tokens, Direct Pay, and mobile app integration help.

Testing & Go-Live

Test cards, validation, and production deployment guidance.

Best Practices

Security, integration patterns, and troubleshooting guidance.

Error Messages and Troubleshooting

Error Message: "Invalid Merchant Identifier"

This error occurs when:

• Your merchant ID doesn't match what's in your APS account Security Settings
• You're sending a live transaction to the test environment (or vice versa)

How to fix:

1. Log into your APS account → Security Settings
2. Copy the exact Merchant Identifier shown there
3. Use the correct environment URLs:
   • Sandbox: URLs with "sb" prefix (e.g., sbpaymentservices.PayFort.com)
   • Production: URLs without "sb" prefix (e.g., paymentservices.PayFort.com)

📖 See: Custom Integration Guide for correct URLs

Error Message: "Signature mismatch"

This means the security signature doesn't match what APS expects.

Common causes:

• Parameters not sorted alphabetically
• Wrong SHA phrase from Security Settings
• Including card details in tokenization signature (don't do this)
• Character encoding issues

How to fix:

1. Check your SHA Request/Response phrases in Security Settings
2. Ensure parameters are sorted A-Z before creating signature
3. For tokenization, exclude sensitive card fields from signature
4. Use UTF-8 encoding for all parameters

Important: For tokenization requests, exclude these fields from signature calculation:

• card_security_code (CVV)
• card_number
• expiry_date
• card_holder_name
• remember_me

📖 See: Signature Guide with step-by-step instructions

Error Message: "token name doesn't exist"

This error has different causes depending on where it occurs:

For Regular Payments:

• Token has expired (tokens have limited lifetime)
• Token wasn't saved properly for future use
• You're trying to use a test token in production
• You're using a token created on account x in account y.

How to fix:

• Generate fresh tokens for each payment session
• Ensure environment consistency (test with test, live with live)
• For saved cards, verify token was stored correctly
• Make sure you process the transaction with the token on the same account you created the token in

📖 See: Save Card Service for token management

Error Message: "Invalid Access Code"

This happens when:

• Wrong access code from Security Settings
• Extra spaces in the access code
• Using sandbox access code in production (or vice versa)

How to fix:

• Copy exact access code from APS dashboard
• Check for extra spaces at beginning or end
• Verify you're using the right environment's access code

Error Message: "Operation Amount Exceeds Authorized Amount"

This happens when:

• Trying to capture more than the authorized amount
• Trying to refund more than was captured
• Multiple partial captures/refunds exceed the original amount

How to fix:

• Use Check Status API to verify available amounts
• Check your capture/refund amounts
• Ensure you're not exceeding the original transaction amount

Error Message: "Transaction Declined"

This means:

• The card issuer declined the transaction
• Could be due to insufficient funds, card restrictions, or security measures

How to fix:

• Ask customer to contact their bank
• Try a different payment method
• Check if the card supports online transactions
• Verify the card details are correct

Error Message: "Card Expired"

This happens when:

• The payment card expiry date has passed
• Wrong expiry date format was used

How to fix:

• Customer needs to update card details with new expiry date
• Verify expiry date format is correct (MM/YY)
• Check if customer has a renewed card

Error Message: "Invalid CVV"

This happens when:

• Wrong security code entered
• CVV format is incorrect

How to fix:

• Customer should re-enter the 3-digit code from back of card
• For American Express, use 4-digit code from front of card
• Verify CVV field accepts the correct number of digits

Integration and Payment Operations

The basic payment flow:

1. Tokenize the card details (converts sensitive card info to a secure token)
2. Process Payment using the token instead of card details
3. Handle Response (success, failure, or 3D Secure redirect)

Key points:

• Tokens keep card details secure
• Always validate responses
• Handle 3D Secure redirects when required

📖 See: Custom Integration Guide for complete flow

You have four options:

1. Direct Response - Get immediate response after payment
2. Webhooks - APS sends updates to your server automatically
3. Check Status API - Query payment status anytime
4. Reports - View transaction details through APS dashboard reports

📖 See: Check Status Guide, Webhooks Guide, and Reporting Guide

PURCHASE:

• Takes money immediately (authorize + capture in one step)
• Use for: Regular online purchases, digital goods
• Cannot be voided (only refunded)

AUTHORIZATION:

• Holds money temporarily without taking it
• Use for: Pre-orders, hotel bookings, variable amounts
• Can be captured later or voided (cancelled)

Choose based on your business needs:

• Immediate payment = PURCHASE
• Hold first, charge later = AUTHORIZATION

📖 See: Custom Integration Guide for implementation details

Three ways to get payment results:

1. Return URL - Customer redirected back to your site
2. Direct Feedback - Immediate response to your server
3. Notification URL - Webhook for status updates

Best practice: Use multiple methods for reliability

• Return URL for customer experience
• Webhooks for backend processing
• Check Status API as backup

📖 See: Webhooks Guide for setup instructions

Apple Pay Integration

This error is usually about certificates:

Common causes:

• Payment Processing Certificate not uploaded to your APS account
• Using wrong certificate (sandbox vs production)
• Certificate expired or invalid

How to fix:

1. Get certificate from Apple Developer portal
2. Upload to APS account under Apple Pay Settings
3. Verify certificate shows as "Active"
4. Match environments (sandbox cert = sandbox account)

📖 See: Apple Pay Guide for certificate setup

Apple Pay has specific requirements:

Check these:

• Using Apple device (iPhone, iPad, Mac)
• Safari browser (required for web)
• HTTPS website (mandatory)
• Apple Pay supported in your country
• Customer has cards in Apple Wallet

How to fix:

• Test on actual Apple devices
• Ensure your site uses HTTPS
• Check Apple Pay availability in your region

📖 See: Apple Pay Guide for requirements

For testing you need:

1. Sandbox Tester Account from Apple Developer portal
2. Test Cards added to Apple Wallet
3. Sandbox APS Account with test certificate

Steps:

1. Create sandbox tester in Apple Developer portal
2. Sign into device with tester account
3. Add test cards to Apple Wallet
4. Use sandbox APS environment for testing

📖 See: Test Cards Guide for test card numbers

Services and Features

Tokenization converts card details into secure tokens for future use.

How it works:

1. Customer enters card details for first payment
2. APS creates a secure token
3. You save the token (not card details)
4. Use token for future payments

Benefits:

• Enhanced security (no card data stored)
• Faster checkout for returning customers
• PCI compliance simplified

📖 See: Save Card Guide for implementation

Installments let customers pay in monthly installments.

Requirements:

• Only works with Credit Cards (not debit cards like MADA/MEEZA)
• Must use PURCHASE command (not AUTHORIZATION)
• Need to be activated by APS support

Types:

• Hosted: APS shows installment options
• Custom: You display options and collect choice

Contact: merchantsupport-ps@amazon.com to activate

📖 See: Installments Guide

3D Secure adds extra security by redirecting customers to their bank.

The flow:

1. Submit payment request
2. If 3DS required, APS returns 3ds_url
3. Redirect customer to 3ds_url
4. Customer completes bank authentication
5. Customer returns to your site with result

Response codes:

• "20064" = 3D Secure check requested
• Redirect customer to the provided URL

📖 See: 3D Secure Guide for implementation

COF lets you store customer payment details for subscriptions.

Two types:

• Scheduled: Fixed amounts at regular intervals
• Unscheduled: Variable amounts when needed

Use cases:

• Subscription services
• Utility bill payments
• Top-up services

Benefits:

• Better customer experience
• Higher success rates
• Automated billing

📖 See: Save Card Guide for COF setup

Mobile SDK Integration

SDK tokens are required for mobile app payments.

Why needed:

• Keeps your security credentials safe
• Prevents reverse engineering
• Required for each payment session

Process:

1. Your mobile app requests token from your server
2. Your server generates token using APS API
3. Server returns token to mobile app
4. App uses token for payment

Important: Generate new token for each payment (mandatory)

📖 See: Mobile Integration Guide

Direct Pay allows secure payments using saved card tokens in mobile apps.

Benefits:

• Faster checkout (no card entry needed)
• Uses previously saved cards
• Enhanced security with tokenization

Requirements:

• Customer must have saved cards (tokens)
• Valid SDK token for the session
• Proper mobile SDK integration

📖 See: Mobile Integration Guide for setup

Customization options vary by platform:

Native Mobile SDK (iOS/Android):

• ✅ Full customization available
• Can modify layouts, colors, text
• Must keep required elements with IDs

React Native SDK:

• ✅ Multiple customization options
• Can match your app's branding

Flutter SDK:

• ❌ Limited to standard checkout only
• No customization allowed

📖 See: Mobile Integration Guide for customization details

Error Message: "Technical Problem"

Common causes:

• Wrong credentials or environment mismatch
• Expired SDK token
• Network connectivity issues

How to fix:

• Generate fresh SDK token for each payment
• Verify environment consistency (sandbox vs production)
• Check network connection
• Ensure credentials are correct for the environment

Error Message: "token name doesn't exist"

For Mobile SDK, this happens when:

• Using wrong environment (sandbox token in production)
• Reusing old SDK tokens (must generate new for each payment)
• Incorrect device ID
• Token expired or invalid

How to fix:

• Generate fresh SDK tokens for each payment session
• Ensure environment consistency (test with test, live with live)
• Verify device ID is correct
• Check token expiration and validity

📖 See: Mobile Integration Guide for token management

Technical Requirements

Yes, customer IP is mandatory for Merchant Page integration.

Why needed:

• Fraud prevention and detection
• Risk assessment
• Compliance requirements

What to send:

• Customer's actual IP address
• Supports both IPv4 and IPv6
• Don't send server IP - must be customer's IP

How to get: Your web server can detect customer IP from request headers

📖 See: Custom Integration Guide for implementation

TLS 1.2 or higher is required for all API calls.

Why important:

• Security compliance
• Data protection
• Industry standards

What to check:

• Your server supports TLS 1.2+
• API calls use secure connections
• No older TLS versions (1.0, 1.1)

Note: Most modern systems support this by default

For tokenization requests: NO - exclude card details from signature.

Exclude these fields:

• card_security_code (CVV)
• card_number
• expiry_date
• card_holder_name
• remember_me

Why: Security best practice to keep sensitive data separate

For other requests: Include all parameters in signature

📖 See: Signature Guide with examples

Device fingerprinting creates a unique ID for each customer's device.

Purpose:

• Advanced fraud detection
• Risk assessment
• Enhanced security

How it works:

• JavaScript collects device information
• Creates unique fingerprint
• Sent with payment request

When needed: For Advanced Fraud Rules (if enabled)

📖 See: Fraud Tools Guide for implementation

Testing and Go-Live

Use these test cards in sandbox environment:

International Cards:

• Visa: 4005550000000001
• Mastercard: 5123456789012346
• American Express: 345678901234564 (CVV: 1234)

Local Cards:

• MADA: 4464040000000007
• MEEZA: 5078030000000003

All test cards:

• Expiry: Any future date (e.g., 12/25)
• CVV: 123 (except AMEX: 1234)

📖 See: Test Cards Guide for complete list

📖 See: Go-Live Guide for detailed checklist

📖 See: Error Codes Guide for complete reference

BIN (Bank Identification Number) discounts let you offer special rates for specific cards. You can implement it only if you're integration Custom Integration

How it works:

1. Customer enters card details
2. You get card BIN from tokenization response
3. Check if BIN qualifies for discount
4. Apply discount to payment amount
5. Process payment with discounted amount

Note: You need to maintain your own BIN discount rules and logic

Direct Transaction Feedback:

• Immediate response when transaction is processed
• Synchronous - happens right away
• Good for immediate status updates

Notification Webhooks:

• Sent when transaction status changes
• Asynchronous - happens later
• Good for backend processing and updates

Best Practice: Use both for complete coverage

• Direct response for immediate user feedback
• Webhooks for reliable backend processing

📖 See: Webhooks Guide for setup

Best Practices and Common Integration Patterns

Security Best Practices

Never expose credentials in client-side code:

• Store access codes and SHA phrases on your server only
• Use environment variables for credential storage
• Never commit credentials to version control
• Rotate credentials periodically

For mobile apps:

• Generate SDK tokens on your server
• Pass tokens to mobile app (not credentials)
• Generate fresh tokens for each payment session

📖 See: Security Best Practices

Always validate user input:

• Check amount is positive and within limits
• Validate email format and phone numbers
• Sanitize all text inputs
• Verify currency codes are supported

Server-side validation:

• Don't rely on client-side validation alone
• Validate all parameters before API calls
• Check business rules (minimum amounts, etc.)
• Log validation failures for monitoring

Implement comprehensive error handling:

• Always check response codes before processing
• Display user-friendly error messages
• Log detailed errors for debugging
• Implement retry logic for network failures

User experience:

• Don't show technical error messages to customers
• Provide clear next steps for common errors
• Offer alternative payment methods when possible
• Keep customers informed during processing

Integration Patterns

Use Hosted Checkout when:

• You want faster implementation
• PCI compliance is a concern
• You need minimal customization
• You want APS to handle payment forms

Use Custom Integration when:

• You need full control over user experience
• You want custom payment flows
• You're building mobile apps
• You need advanced features like tokenization

📖 See: Hosted Checkout vs Custom Integration

Webhook best practices:

• Always verify webhook signatures
• Implement idempotency (handle duplicate webhooks)
• Respond with HTTP 200 for successful processing
• Process webhooks asynchronously when possible

Error handling:

• APS will retry failed webhooks
• Implement exponential backoff for retries
• Log all webhook events for debugging
• Have fallback using Check Status API

📖 See: Webhooks Guide

Environment separation:

• Use different credentials for each environment
• Separate databases for test and live data
• Use environment variables for configuration
• Never mix test and production data

Testing strategy:

• Test all scenarios in sandbox first
• Use test cards for sandbox testing
• Validate webhooks in both environments
• Test error scenarios and edge cases

📖 See: Go-Live Guide

Troubleshooting Tips

Systematic debugging approach:

1. Check the exact error message and response code
2. Verify all required parameters are present
3. Validate signature calculation
4. Check environment consistency (sandbox vs production)
5. Review API logs for detailed error information

Common checks:

• Verify merchant credentials are correct
• Ensure customer IP is real customer IP (not server IP)
• Check amount format (multiply by 100 for most currencies)
• Validate all required fields are populated

Comprehensive testing approach:

• Test successful payments with different card types
• Test declined transactions and error scenarios
• Test 3D Secure flows end-to-end
• Test webhook delivery and processing
• Test refunds, voids, and captures

Edge cases to test:

• Network timeouts and retries
• Duplicate transaction handling
• Invalid input validation
• Currency and amount edge cases
• Mobile device compatibility

Key metrics to monitor:

• Payment success/failure rates
• API response times and timeouts
• Webhook delivery success rates
• Error code frequency and patterns
• Customer conversion rates

Set up alerts for:

• Sudden increase in payment failures
• API response time degradation
• Missing webhook deliveries
• Unusual error patterns
• Security-related events