Apple Pay 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

Amazon Payment Services fully supports Apple Pay integration, enabling merchants to offer customers a seamless payment experience through their Apple devices. Apple Pay supports major payment networks including American Express, Mastercard, Visa, and local payment methods such as mada.

Prerequisites

Before integrating Apple Pay, complete the following setup steps:

Apple Developer Account: Ensure you have an active Apple Developer Program membership
Apple Pay Setup: Complete the Apple Pay merchant setup at Apple Pay Developer Portal
Certificates: Generate and configure the required certificates:
- Merchant Identity Certificate
- Payment Processing Certificate
APS Configuration: Upload your Payment Processing certificate in your Amazon Payment Services dashboard under "Apple Pay Settings"

Apple Pay Integration Options

Choose the integration method that best fits your business requirements and technical capabilities:

Web Integration

Accept Apple Pay payments directly on your website using Apple Pay JS and Amazon Payment Services API for Safari users.

SDK Integration

Native iOS SDK integration for mobile applications with seamless Apple Pay functionality and user experience.

Web Integration

Web integration allows you to accept Apple Pay payments directly on your website using Apple Pay JS and Amazon Payment Services API. This integration provides a seamless checkout experience for customers using Safari on supported Apple devices.

API Endpoints

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

Request Format

Method: POST
Content-Type: application/json
Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
digital_wallet `String` `Max: 100` `Required` Specifies the digital wallet type for Apple Pay transactions. This parameter identifies the payment method as Apple Pay to Amazon Payment Services. Value: `APPLE_PAY` Example. APPLE_PAY
command `String` `Max: 20` `Required` Defines the transaction type to be executed. Use AUTHORIZATION to hold funds without capturing them immediately (useful for order verification), or PURCHASE to authorize and capture funds in a single step. 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
apple_data `String` `Max: 500` `Required` Base64-encoded encrypted payment data from Apple Pay containing the tokenized payment information. This data is encrypted using your merchant certificate and contains sensitive payment details that only APS can decrypt. Example. nIje+wQGTVVBgFqBxJoTk8Maig4D...
apple_signature `String` `Max: 3000` `Required` Base64-encoded digital signature created by Apple to verify the authenticity and integrity of the payment data. Contains the signing certificate chain and cryptographic signature using Apple's private key. Example. MIAGCSqGSIb3DQEHAqCAMIACAQEx...
apple_header `Object` `Required` JSON object containing cryptographic metadata required to decrypt and verify the Apple Pay payment data. Includes transaction ID, ephemeral public key, and public key hash for secure processing. Example. {"apple_transactionId": "ee0c2da...", "apple_ephemeralPublicKey": "MFkwEw...", "apple_publicKeyHash": "YWEPi8j..."}
apple_transactionId `String` `Max: 100` `Required` Hexadecimal string representing the unique transaction identifier generated by the Apple device. This ID is used for transaction tracking and duplicate detection within Apple's payment system. Example. ee0c2dafa3a5a96f489226e2be7d7b46
apple_ephemeralPublicKey `String` `Max: 200` `Required` Base64-encoded ephemeral public key generated by Apple for this specific transaction. Used in the ECDH key agreement process to derive the shared secret for decrypting payment data. Example. MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
apple_publicKeyHash `String` `Max: 100` `Required` Base64-encoded SHA-256 hash of your merchant certificate's public key. Apple uses this to identify which certificate was used to encrypt the payment data, ensuring proper decryption. Example. YWEPi8j+nYJHD5C04PdGEFHam6mlIexZ8moIWNn6Pbo=
apple_paymentMethod `Object` `Required` JSON object describing the payment method selected by the customer in Apple Pay. Contains the card network, type (credit/debit), and display name shown to the user during payment authorization. Example. {"apple_displayName": "Visa •••• 0492", "apple_network": "Visa", "apple_type": "debit"}
apple_displayName `String` `Max: 50` `Required` User-friendly payment method description shown in Apple Pay interface. Typically includes card brand and last 4 digits (e.g., "Visa •••• 1234") to help users identify their selected payment method. Example. Visa •••• 0492
apple_network `String` `Max: 20` `Required` Payment network brand identifier for the card used in the transaction. Must match one of the supported networks configured in your Apple Pay merchant settings. Values: `Visa`, `MasterCard`, `AmEx`, `Mada`, `Discover`, `JCB` Example. Visa
apple_type `String` `Max: 20` `Required` Classification of the payment card type as determined by the issuing bank. This information helps with transaction routing and processing rules specific to each card type. Values: `credit`, `debit`, `prepaid`, `store` Example. credit
customer_ip `String` `Max: 45` `Required` 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
signature `String` `Max: 200` `Required` SHA-256 HMAC signature calculated using your secret key and request parameters for authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
apple_applicationData `String` `Max: 200` `Optional` Base64-encoded SHA-256 hash of the applicationData property from your original PKPaymentRequest. Required only if you included applicationData in your Apple Pay request. Used for additional transaction verification and integrity checking. Example. a1b2c3d4e5f6789012345678901234567890abcd
eci `String` `Max: 16` `Optional` Electronic Commerce Indicator classifying the transaction channel. ECOMMERCE for online transactions 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. Use clear, concise descriptions that help identify the transaction. 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 to help customers identify the charge. Avoid special characters. Example. TECHSTORE ONLINE
customer_name `String` `Max: 40` `Optional` Customer's full name as provided during checkout. Used for transaction records, fraud prevention, and customer service. Should match the name on the payment method when possible. Example. Sarah Johnson
phone_number `String` `Max: 19` `Optional` Customer's phone number in international format (country code + number). Used for transaction verification, fraud prevention, and customer communication. Include country code without + symbol. Example. 971501234567
recurring_mode `String` `Max: 20` `Optional` Indicates this transaction is part of a recurring payment setup. Use UNSCHEDULED for merchant-initiated transactions or subscription renewals. Required for storing payment credentials for future use. Values: `UNSCHEDULED` Example. UNSCHEDULED
merchant_extra `String` `Max: 999` `Optional` Custom field for storing additional transaction metadata. This data is returned in responses and webhook notifications. Use for internal tracking, customer IDs, or integration-specific information. Example. customer_id:12345,campaign:summer2024
merchant_extra1 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data such as product categories, sales channels, or internal reference codes. Useful for reporting and analytics. Example. product_category:electronics
merchant_extra2 `String` `Max: 250` `Optional` Additional custom field for storing order-specific information like shipping methods, promotional codes, or customer segments for business intelligence. Example. shipping_method:express
merchant_extra3 `String` `Max: 250` `Optional` Additional custom field for integration-specific data such as affiliate IDs, marketing campaign codes, or third-party system references. Example. affiliate_id:partner123
merchant_extra4 `String` `Max: 250` `Optional` Additional custom field for business-specific metadata like sales representative IDs, store locations, or customer service ticket numbers. Example. store_location:dubai_mall
merchant_extra5 `String` `Max: 250` `Optional` Additional custom field for extended transaction context such as subscription plan details, loyalty program information, or custom business logic parameters. Example. subscription_plan:premium_annual

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.

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

Response Parameters

Parameter
digital_wallet `String` `Max: 100` Digital wallet type used for the transaction. Value: `APPLE_PAY` Example. APPLE_PAY
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 response. 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 for the transaction. Values: `MASTERCARD`, `VISA`, `MADA`, `AMEX` Example. VISA
eci `String` `Max: 16` E-commerce indicator used for the transaction. Values: `ECOMMERCE` Example. ECOMMERCE
order_description `String` `Max: 150` Order description from the request. Example. iPhone 6-S
statement_descriptor `String` `Max: 50` Statement descriptor from the request. Example. MYSTORE-PURCHASE
customer_ip `String` `Max: 45` Customer IP address from the request. Example. 192.178.1.10
customer_name `String` `Max: 40` Customer name from the request. Example. John Smith
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
phone_number `String` `Max: 19` Customer phone number from the request. Example. 00962797219966
agreement_id `String` `Max: 15` Identifier for recurring payment agreements. Example. AGR123456789
recurring_mode `String` `Max: 20` Recurring payment mode from the request. Example. UNSCHEDULED

Apple Pay Web Sample Request
{
  "digital_wallet": "APPLE_PAY",
  "command": "PURCHASE",
  "access_code": "4yyoUrilpc0Hs7wolpcy",
  "merchant_identifier": "0d60670d",
  "merchant_reference": "AbhiTest-100118",
  "amount": "100",
  "currency": "SAR",
  "language": "en",
  "customer_email": "S00116-3@hef.org.sa",
  "apple_data": "nIje+wQGTVVBgFqBxJoTk8Maig4D...",
  "apple_signature": "MIAGCSqGSIb3DQEHAqCAMIACAQEx...",
  "apple_header": {
    "apple_transactionId": "ee0c2dafa3a5a96f489226e2be7d7b46",
    "apple_ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcD...",
    "apple_publicKeyHash": "YWEPi8j+nYJHD5C04PdGEFHam6mlI..."
  },
  "apple_paymentMethod": {
    "apple_displayName": "Visa 0253",
    "apple_network": "Visa",
    "apple_type": "debit"
  },
  "customer_ip": "192.168.1.100",
  "signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b"
}

Sample Response
{
    "digital_wallet": "APPLE_PAY",
    "command": "PURCHASE",
    "access_code": "4yyoUrilpc0Hs7wolpcy",
    "merchant_identifier": "0d60670d",
    "merchant_reference": "AbhiTest-100118",
    "amount": "100",
    "currency": "SAR",
    "language": "en",
    "customer_email": "S00116-3@hef.org.sa",
    "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4",
    "fort_id": "149295435400084008",
    "payment_option": "VISA",
    "authorization_code": "P1000000000000372136",
    "response_message": "Success",
     "response_code": "14000",
    "status": "20",
    "card_holder_name": "John Smith",
    "expiry_date": "2512",
    "card_number": "400555*****0001"
}

SDK Integration

SDK integration allows you to accept Apple Pay payments directly in your iOS mobile applications using the Amazon Payment Services iOS SDK. This integration provides native Apple Pay functionality with seamless user experience.

Prerequisites

Before starting Apple Pay SDK integration, ensure you have:

iOS device running iOS 8.1 or later
Mac with Xcode 6.1 or newer
Apple Developer Program membership
Amazon Payment Services iOS Mobile SDK
Apple Pay setup completed (merchant ID, certificates)

API Endpoints

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

Request Format

Method: SDK Method Call
Integration: iOS SDK Integration
Authentication: SDK Token

Request Parameters

Parameter
digital_wallet `String` `Max: 100` `Required` Specifies the digital wallet type for Apple Pay transactions. Value: `APPLE_PAY` Example. APPLE_PAY
command `String` `Max: 20` `Required` Transaction type to be executed. AUTHORIZATION for auth-only transactions, PURCHASE for immediate capture. Values: `AUTHORIZATION`, `PURCHASE` Example. PURCHASE
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` Payment amount in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer. Example. 10000
currency `String` `Max: 3` `Required` Three-letter ISO 4217 currency code for the payment amount. Example. USD
language `String` `Max: 2` `Required` Response language. Supported values: en (English) or ar (Arabic). Example. en
customer_email `String` `Max: 254` `Required` Valid customer email address for payment notifications and receipt delivery. Example. customer@example.com
sdk_token `String` `Max: 100` `Required` SDK token to enable using the Mobile SDK for secure communication. Example. gr66zzwW9
customer_ip `String` `Max: 45` `Required` Customer's IP address for fraud prevention. Supports both IPv4 and IPv6 formats. Example. 192.178.1.10
payment_option `String` `Max: 10` `Optional` Restrict payment to specific method. Values: `MASTERCARD`, `VISA`, `MADA`, `AMEX` Example. VISA
eci `String` `Max: 16` `Optional` E-commerce indicator for transaction type classification. Values: `ECOMMERCE` Example. ECOMMERCE
order_description `String` `Max: 150` `Optional` Human-readable description of the order or service being paid for. Example. iPhone 6-S
statement_descriptor `String` `Max: 50` `Optional` Custom descriptor that appears on customer's bank statement. Example. MYSTORE-PURCHASE
customer_name `String` `Max: 40` `Optional` Full name of the customer making the payment. Example. John Smith
phone_number `String` `Max: 19` `Optional` Customer phone number in international format for verification and notifications. Example. 00962797219966
token_name `String` `Max: 100` `Optional` Previously saved payment token for returning customers. Example. Op9Vmp
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 data that will be returned in the response and webhook notifications. Example. JohnSmith
merchant_extra1 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra2 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra3 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra4 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra5 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith

Response Parameters

Parameter
digital_wallet `String` `Max: 100` Digital wallet type used for the transaction. Value: `APPLE_PAY` Example. APPLE_PAY
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. USD
language `String` `Max: 2` Language used for the response. Example. en
customer_email `String` `Max: 254` Customer email address used. Example. customer@example.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
sdk_token `String` `Max: 100` SDK token used for the request. Example. gr66zzwW9
payment_option `String` `Max: 10` Payment method used for the transaction. Values: `MASTERCARD`, `VISA`, `MADA`, `AMEX` Example. VISA
eci `String` `Max: 16` E-commerce indicator used for the transaction. Values: `ECOMMERCE` Example. ECOMMERCE
order_description `String` `Max: 150` Order description from the request. Example. iPhone 6-S
statement_descriptor `String` `Max: 50` Statement descriptor from the request. Example. MYSTORE-PURCHASE
customer_ip `String` `Max: 45` Customer IP address from the request. Example. 192.178.1.10
customer_name `String` `Max: 40` Customer name from the request. Example. John Smith
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
phone_number `String` `Max: 19` Customer phone number from the request. Example. 00962797219966
token_name `String` `Max: 100` Generated or used token for the payment. Example. Op9Vmp
settlement_reference `String` `Max: 22` Settlement reference from the request. Example. XYZ9239-yu898

Objective-C SDK Implementation
#pragma mark - PKPaymentAuthorizationViewControllerDelegate

- (void)paymentAuthorizationViewController:(PKPaymentAuthorizationViewController *)controller
                       didAuthorizePayment:(PKPayment *)payment
                                completion:(void (^)(PKPaymentAuthorizationStatus status))completion
{
    BOOL asyncSuccessful = payment.token.paymentData.length != 0;
    
    if(asyncSuccessful) {
        
        PayFortController *payFort = [[PayFortController alloc]initWithEnviroment:(KPayFortEnviroment)_enviromentSegment.selectedSegmentIndex];
        
        NSMutableDictionary *request = [[NSMutableDictionary alloc]init];
        [request setValue:@"10000" forKey:@"amount"];
        [request setValue:@"AUTHORIZATION" forKey:@"command"];
        [request setValue:@"USD" forKey:@"currency"];
        [request setValue:@"email@domain.com" forKey:@"customer_email"];
        [request setValue:@"en" forKey:@"language"];
        [request setValue:@"merchant" forKey:@"merchant_reference"];
        [request setValue:@"gr66zzwW9" forKey:@"sdk_token"];
        [request setValue:@"APPLE_PAY" forKey:@"digital_wallet"];
        
        [payFort callPayFortForApplePayWithRequest:request
                                    applePayPayment:payment
                              currentViewController:self
                                            Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
                                                completion(PKPaymentAuthorizationStatusSuccess);
                                            }
                                             Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
                                                completion(PKPaymentAuthorizationStatusFailure);
                                            }];
    } else {
        completion(PKPaymentAuthorizationStatusFailure);
    }
}

Sample SDK Response
{
    "digital_wallet": "APPLE_PAY",
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": "10000",
    "currency": "USD",
    "language": "en",
    "customer_email": "customer@example.com",
    "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4",
    "fort_id": "149295435400084008",
    "sdk_token": "gr66zzwW9",
    "payment_option": "VISA",
    "authorization_code": "P1000000000000372136",
    "response_message": "Success",
     "response_code": "14000",
    "status": "20",
    "card_holder_name": "John Smith",
    "expiry_date": "2512",
    "card_number": "400555*****0001"
}

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

Web Integration URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
SDK Integration: Configure SDK for sandbox environment
Apple Pay Testing: Use Apple Pay sandbox test cards

Go-Live Process

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

Additional Resources

Apple Pay Developer Guide: Apple Pay Developer Documentation
APS Mobile SDK: Download iOS SDK

Prerequisites​

Apple Pay Integration Options​

Web Integration

SDK Integration

Web Integration​

API Endpoints​

Request Format​

Request Parameters​

Response Parameters​

SDK Integration​

Prerequisites​

API Endpoints​

Request Format​

Request Parameters​

Response Parameters​

Response Codes​

Testing The Integration​

Sandbox Testing​

Go-Live Process​

Additional Resources​

Prerequisites

Apple Pay Integration Options

Web Integration

API Endpoints

Request Format

Request Parameters

Response Parameters

SDK Integration

Prerequisites

API Endpoints

Request Format

Request Parameters

Response Parameters

Response Codes

Testing The Integration

Sandbox Testing

Go-Live Process

Additional Resources