External 3D Secure Service 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
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
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 String Max: 20 Required Transaction type to be executed. AUTHORIZATION for auth-only transactions, PURCHASE for immediate capture. Values: AUTHORIZATION , PURCHASE Example. PURCHASE |
access_code String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration 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 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. AED |
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@domain.com |
expiry_date String Max: 4 Required Card expiry date in YYMM format. Must be a future date. Example. 2105 |
card_number String Max: 19 Required Complete credit card number. MEEZA cards: 19 digits, AMEX: 15 digits, Others: 16 digits. Example. 4005550000000001 |
signature String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
3ds_enrolled String Max: 1 Required Card enrollment status from your external 3DS provider. Values: Y (Enrolled), N (Not Enrolled)Example. Y |
3ds_status String 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 String Max: 2 Required Electronic Commerce Indicator returned from your external MPI provider. Values: 05 (Authenticated), 06 (Attempted), 07 (Non-3DS)Example. 05 |
ver_token String Max: 28 Required Verification token (CAVV/AAV) generated by the issuer during 3DS authentication to prove cardholder authentication. Example. gIGCg4SFhoeIiYqLjI2Oj5CRkpM= |
eci String Max: 16 Optional E-commerce indicator for transaction type classification. Values: ECOMMERCE Example. ECOMMERCE |
card_security_code String Max: 4 Optional Card security code (CVV/CVC). AMEX accepts 4 digits, others accept 3 digits. Example. 123 |
card_holder_name String Max: 50 Optional Cardholder name as it appears on the card. Alphabetic characters, spaces, hyphens, periods, and apostrophes allowed. Example. John Smith |
token_name String Max: 100 Optional Previously generated token for returning customers. Enables payments without re-entering card details. Example. Op9Vmp |
payment_option String Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, MEEZA. Example. VISA |
order_description String Max: 150 Optional Human-readable description of the order or service being paid for. Example. iPhone 6-S |
customer_ip String Max: 45 Optional Customer's IP address for fraud prevention. Supports both IPv4 and IPv6 formats. Mandatory if fraud service is active. Example. 192.178.1.10 |
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 |
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 |
return_url String Max: 400 Optional URL where customer will be redirected after payment completion. 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 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. customer@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. Example. VISA |
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 String Max: 5 Numeric response code indicating transaction result. Example. 14000 |
status String Max: 2 Two-digit status code indicating transaction state. Example. 20 |
card_holder_name String Max: 50 Cardholder name from the request. Example. John Smith |
expiry_date String Max: 4 Card expiry date from the request. Example. 2105 |
card_number String Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001 |
token_name String Max: 100 Token used or generated for the payment. Example. Op9Vmp |
eci String Max: 16 E-commerce indicator from the request. Example. ECOMMERCE |
order_description String Max: 150 Order description from the request. Example. iPhone 6-S |
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 |
phone_number String Max: 19 Customer phone number from the request. Example. 00962797219966 |
settlement_reference String Max: 22 Settlement reference from the request. Example. XYZ9239-yu898 |
merchant_extra String Max: 999 Custom merchant data from the request. Example. JohnSmith |
merchant_extra1 String Max: 250 Additional custom field from the request. Example. JohnSmith |
merchant_extra2 String Max: 250 Additional custom field from the request. Example. JohnSmith |
merchant_extra3 String Max: 250 Additional custom field from the request. Example. JohnSmith |
merchant_extra4 String Max: 250 Additional custom field from the request. Example. JohnSmith |
merchant_extra5 String Max: 250 Additional custom field from the request. Example. JohnSmith |
return_url String Max: 400 Return URL from the request. Example. https://www.merchant.com/payment-callback |
agreement_id String Max: 15 Agreement identifier from the request. Example. AGR123456789 |
3ds_url String Max: 300 3DS authentication URL (if additional authentication required). Example. https://www.3dsecure.com |
ds_transaction_id String Max: 40 Directory server transaction ID from the 3DS authentication process. Example. 8ac7a4a2-7cb1-4c75-92c1-bdd3b6b63ac6 |
3ds_xid String 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.
{
"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"
}
{
"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.