External 3D Secure Service API

Copy page

Copy page as Markdown for LLMs

Open in Claude

Ask questions about this page

External 3D Secure integration allows merchants who already have a preferred 3DS verification provider to continue using their existing services while processing payments through Amazon Payment Services. This approach enables you to leverage your current 3DS infrastructure with external Merchant Plug-Ins (MPI) while benefiting from Amazon Payment Services' payment processing capabilities.

External 3DS integration is only available for PCI-certified merchants. You must have valid PCI DSS certification to handle card data directly and use external 3DS services.

API Endpoints

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

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

Request Format

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

When using external 3DS, you must provide the 3DS authentication results from your MPI provider including enrollment status, authentication status, ECI value, and verification token.

Request Parameters

Parameter
command   Alpha Max: 20 Required Transaction type to be executed. AUTHORIZATION for auth-only transactions, PURCHASE for immediate capture. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   Alphanumeric Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Special characters: _ - . Example. XYZ9239-yu898
amount   Numeric Max: 10 Required Payment amount in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer. Example. 10000
currency   Alpha Max: 3 Required Three-letter ISO 4217 currency code for the payment amount. Example. AED
language   Alpha Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
customer_email   Alphanumeric Max: 254 Required Valid customer email address for payment notifications and receipt delivery. Special characters: _ - . @ + Example. customer@domain.com
expiry_date   Numeric Max: 4 Required Card expiry date in YYMM format. Must be a future date. Example. 2105
card_number   Numeric Max: 19 Required Complete credit card number. MEEZA cards: 19 digits, AMEX: 15 digits, Others: 16 digits. Example. 4005550000000001
signature   Alphanumeric Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
3ds_enrolled   Alpha Max: 1 Required Card enrollment status from your external 3DS provider. Values: Y (Enrolled), N (Not Enrolled) Example. Y
3ds_status   Alpha Max: 1 Required 3DS authentication status returned by your external MPI after authentication completion. Values: Y (Authenticated), N (Not Authenticated), U (Unable to Authenticate), A (Attempted) Example. Y
3ds_eci   Numeric Max: 2 Required Electronic Commerce Indicator returned from your external MPI provider. Values: 05 (Authenticated), 06 (Attempted), 07 (Non-3DS) Example. 05
ver_token   Alphanumeric Max: 28 Required Verification token (CAVV/AAV) generated by the issuer during 3DS authentication to prove cardholder authentication. Example. gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
eci   Alpha Max: 16 Optional E-commerce indicator for transaction type classification. Values: ECOMMERCE Example. ECOMMERCE
card_security_code   Numeric Max: 4 Optional Card security code (CVV/CVC). AMEX accepts 4 digits, others accept 3 digits. Example. 123
card_holder_name   Alpha Max: 50 Optional Cardholder name as it appears on the card. Alphabetic characters, spaces, hyphens, periods, and apostrophes allowed. Special characters: ' - . Example. John Smith
token_name   Alphanumeric Max: 100 Optional Previously generated token for returning customers. Enables payments without re-entering card details. Special characters: . @ - _ Example. Op9Vmp
payment_option   Alpha Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, MEEZA. Example. VISA
order_description   Alphanumeric Max: 150 Optional Human-readable description of the order or service being paid for. Special characters: ' / . _ - # : $ **Space** Example. iPhone 6-S
customer_ip   Alphanumeric Max: 45 Optional Customer's IP address for fraud prevention. Supports both IPv4 and IPv6 formats. Mandatory if fraud service is active. Special characters: . : Example. 192.178.1.10
customer_name   Alpha Max: 40 Optional Full name of the customer making the payment. Special characters: _ \ / - . ' **Space** Example. John Smith
phone_number   Numeric Max: 19 Optional Customer phone number in international format for verification and notifications. Special characters: + - ( ) **Space** Example. 00962797219966
settlement_reference   Alphanumeric Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999 Optional Custom data that will be returned in the response and webhook notifications. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250 Optional Additional custom field for merchant-specific data. Special characters: . ; / _ - , ' @ Example. JohnSmith
return_url   Alphanumeric Max: 400 Optional URL where customer will be redirected after payment completion. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com/payment-callback
agreement_id   String Max: 15 Optional Identifier for recurring payment agreements. Used for subscription and installment payments. Do not use special characters. Example. AGR123456789
recurring_expiry_date   Date Format: YYYY-MM-DD Optional End date for recurring payment agreement in ISO date format. Example. 2024-10-05
recurring_days_between_payments   Integer Optional Interval in days between recurring payments as agreed with customer. Example. 30

All 3DS-related parameters (3ds_enrolled, 3ds_status, 3ds_eci, ver_token) must be obtained from your external 3DS provider and accurately reflect the authentication results. Incorrect values will result in transaction failures.

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.

The merchant_reference must be unique per transaction.

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

Response Parameters

Parameter
command   Alpha Max: 20 Transaction type executed. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   Alphanumeric Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40 Unique order reference from the request. Special characters: _ - . Example. XYZ9239-yu898
amount   Numeric Max: 10 Transaction amount processed. Example. 10000
currency   Alpha Max: 3 Currency code used for the transaction. Example. AED
language   Alpha Max: 2 Language used for the response. Example. en
customer_email   Alphanumeric Max: 254 Customer email address used. Special characters: _ - . @ + Example. customer@domain.com
signature   Alphanumeric Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Numeric Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
payment_option   Alpha Max: 10 Payment method used for the transaction. Example. VISA
authorization_code   Alphanumeric Max: 100 Authorization code from payment processor. Example. P1000000000000372136
response_message   Alphanumeric Max: 150 Human-readable response description in requested language. Example. Success
response_code   Numeric Max: 5 Numeric response code indicating transaction result. Example. 14000
status   Numeric Max: 2 Two-digit status code indicating transaction state. Example. 20
card_holder_name   Alpha Max: 50 Cardholder name from the request. Special characters: ' - . Example. John Smith
expiry_date   Numeric Max: 4 Card expiry date from the request. Example. 2105
card_number   Numeric Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001
token_name   Alphanumeric Max: 100 Token used or generated for the payment. Special characters: . @ - _ Example. Op9Vmp
eci   Alpha Max: 16 E-commerce indicator from the request. Example. ECOMMERCE
order_description   Alphanumeric Max: 150 Order description from the request. Special characters: ' / . _ - # : $ **Space** Example. iPhone 6-S
customer_ip   Alphanumeric Max: 45 Customer IP address from the request. Special characters: . : Example. 192.178.1.10
customer_name   Alpha Max: 40 Customer name from the request. Special characters: _ \ / - . ' **Space** Example. John Smith
phone_number   Numeric Max: 19 Customer phone number from the request. Special characters: + - ( ) **Space** Example. 00962797219966
settlement_reference   Alphanumeric Max: 22 Settlement reference from the request. Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999 Custom merchant data from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250 Additional custom field from the request. Special characters: . ; / _ - , ' @ Example. JohnSmith
return_url   Alphanumeric Max: 400 Return URL from the request. Special characters: $ ! = ? # & - _ / : . Example. https://www.merchant.com/payment-callback
agreement_id   Alphanumeric Max: 15 Agreement identifier from the request. Example. AGR123456789
3ds_url   Alphanumeric Max: 300 3DS authentication URL (if additional authentication required). Example. https://www.3dsecure.com
ds_transaction_id   Alphanumeric Max: 40 Directory server transaction ID from the 3DS authentication process. Example. 8ac7a4a2-7cb1-4c75-92c1-bdd3b6b63ac6
3ds_xid   Alphanumeric Max: 28 Unique transaction identification number for the 3DS transaction. Example. 6kQGHEiZDU0H4+mUWF7zELHAcqM=

Response Codes

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

External 3DS Sample Request

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "amount": 10000,
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@domain.com",
  "expiry_date": "2105",
  "card_number": "4005550000000001",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "3ds_enrolled": "Y",
  "3ds_status": "Y",
  "3ds_eci": "05",
  "ver_token": "gIGCg4SFhoeIiYqLjI2Oj5CRkpM=",
  "card_security_code": "123",
  "customer_ip": "192.178.1.10",
  "order_description": "iPhone 6-S",
  "return_url": "https://www.merchant.com/payment-callback"
}

import requests
import json

# External 3DS payment request
payment_request = {
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": 10000,
    "currency": "AED",
    "language": "en",
    "customer_email": "customer@domain.com",
    "expiry_date": "2105",
    "card_number": "4005550000000001",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    # 3DS parameters from external MPI
    "3ds_enrolled": "Y",
    "3ds_status": "Y", 
    "3ds_eci": "05",
    "ver_token": "gIGCg4SFhoeIiYqLjI2Oj5CRkpM=",
    # Optional parameters
    "card_security_code": "123",
    "customer_ip": "192.178.1.10",
    "order_description": "iPhone 6-S",
    "return_url": "https://www.merchant.com/payment-callback"
}

# Send payment request
response = requests.post(
    "https://sbpaymentservices.PayFort.com/FortAPI/paymentApi",
    json=payment_request,
    headers={'Content-Type': 'application/json'}
)

print(response.json())

<?php
// External 3DS payment request
$payment_request = [
    "command" => "PURCHASE",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier" => "CycHZxVj",
    "merchant_reference" => "XYZ9239-yu898",
    "amount" => 10000,
    "currency" => "AED",
    "language" => "en",
    "customer_email" => "customer@domain.com",
    "expiry_date" => "2105",
    "card_number" => "4005550000000001",
    "signature" => "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    // 3DS parameters from external MPI
    "3ds_enrolled" => "Y",
    "3ds_status" => "Y",
    "3ds_eci" => "05",
    "ver_token" => "gIGCg4SFhoeIiYqLjI2Oj5CRkpM=",
    // Optional parameters
    "card_security_code" => "123",
    "customer_ip" => "192.178.1.10",
    "order_description" => "iPhone 6-S",
    "return_url" => "https://www.merchant.com/payment-callback"
];

// Send payment request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sbpaymentservices.PayFort.com/FortAPI/paymentApi");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payment_request));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

# External 3DS payment request using cURL

curl -X POST https://sbpaymentservices.PayFort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": 10000,
    "currency": "AED",
    "language": "en",
    "customer_email": "customer@domain.com",
    "expiry_date": "2105",
    "card_number": "4005550000000001",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "3ds_enrolled": "Y",
    "3ds_status": "Y",
    "3ds_eci": "05",
    "ver_token": "gIGCg4SFhoeIiYqLjI2Oj5CRkpM=",
    "card_security_code": "123",
    "customer_ip": "192.178.1.10",
    "order_description": "iPhone 6-S",
    "return_url": "https://www.merchant.com/payment-callback"
  }'

Sample Response

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "amount": 10000,
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@domain.com",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "fort_id": "149295435400084008",
  "payment_option": "VISA",
  "authorization_code": "P1000000000000372136",
  "response_message": "Success",
    "response_code": "14000",
  "status": "20",
  "card_holder_name": "John Smith",
  "expiry_date": "2105",
  "card_number": "400555*****0001",
  "customer_ip": "192.178.1.10",
  "order_description": "iPhone 6-S",
  "return_url": "https://www.merchant.com/payment-callback"
}

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
• Test Cards: Use our comprehensive Testing Cards
• 3DS Testing: Coordinate with your external MPI provider for 3DS test scenarios

Go-Live Process

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

For more information on external 3DS service implementation and best practices, see our external 3DS guide.