PCI Custom Integration 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

PCI custom integration allows PCI-compliant merchants to collect customer credit card details directly on their checkout page and process payments through Amazon Payment Services trusted channel.

This integrations required Amazon Payment Services InfoSec to validate the certificate and confirm the merchant is eligible to collect card details.

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

All PCI integration requests must be processed on PCI-compliant servers. Card data must be handled according to PCI DSS requirements.

Request Parameters

Parameter
command   String Max: 20 Required Command specifies the transaction type to be executed. Use AUTHORIZATION for auth-only transactions that require separate capture, or PURCHASE for immediate payment capture and settlement. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz
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 Merchant's unique order reference number that must be unique per transaction. Supports alphanumeric characters, hyphens, underscores, and periods for order tracking and reconciliation. Example. XYZ9239-yu898
amount   Integer Max: 10 Required Transaction amount in the smallest currency unit (e.g., fils for AED, cents for USD). Each currency has predefined decimal points that must be considered when sending the amount. Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code specifying the transaction currency. Determines the decimal precision and processing rules for the payment amount. Example. AED
language   String Max: 2 Required Language code for checkout page and response messages. Affects the display language of payment forms and error messages returned by the system. Values: en, ar Example. en
customer_email   String Max: 254 Required Customer's email address for payment notifications and receipt delivery. Must be a valid email format and supports standard email special characters. Example. customer@domain.com
eci   String Max: 16 Required E-commerce indicator that classifies the transaction type and processing environment for risk assessment and routing decisions. Values: ECOMMERCE Example. ECOMMERCE
expiry_date   String Max: 4 Required Card expiry date in YYMM format. Must represent a future date to ensure card validity during transaction processing. Example. 2105
card_number   String Max: 19 Required Complete credit card number without spaces or formatting. MEEZA cards require 19 digits, AMEX cards require 15 digits, while other card types require 16 digits. Example. 4005550000000001
card_security_code   String Max: 4 Optional Card security code (CVV/CVC) collected from the merchant's checkout page. Mandatory for ecommerce transactions. AMEX accepts 4 digits, while other card types accept 3 digits. Example. 123
customer_ip   String Max: 45 Required Customer's IP address for fraud prevention and risk assessment. Mandatory when fraud service is active. Supports both IPv4 and IPv6 address formats. Example. 192.178.1.10
signature   String Max: 200 Required SHA-256 hash signature for request authentication and data integrity validation. Calculated using the Secure Hash Algorithm as detailed in the signature documentation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name   String Max: 50 Optional Cardholder name as it appears on the physical card. Supports alphabetic characters, spaces, hyphens, periods, and apostrophes for international name formats. Example. John Smith
token_name   String Max: 100 Optional Previously generated token from the tokenization process for recurring payments or stored card transactions. Supports alphanumeric characters and common special characters. Example. Op9Vmp
payment_option   String Max: 10 Optional Payment method restriction to limit transaction processing to specific card networks or payment types. Values: MASTERCARD, VISA, AMEX, MADA (for Purchase operations and eci Ecommerce only), MEEZA (for Purchase operations and ECOMMERCE eci only) Example. VISA
order_description   String Max: 150 Optional Human-readable description of the order or service being purchased. Supports alphanumeric characters and common special characters for detailed order information. Example. iPhone 6-S
customer_name   String Max: 40 Optional Full name of the customer making the payment. Supports alphabetic characters, spaces, and common name formatting characters for international customers. Example. John Smith
phone_number   String Max: 19 Optional Customer's phone number in international format for verification and notification purposes. Supports numeric characters and common phone formatting symbols. Example. 00962797219966
settlement_reference   String Max: 22 Optional Unique reference value submitted by merchant that is passed to the acquiring bank and displayed in the merchant's acquirer settlement file for reconciliation. Example. XYZ9239-yu898
merchant_extra   String Max: 999 Optional Custom data field sent by merchant that will be received and returned unchanged. Not displayed in reports but useful for internal tracking and integration purposes. Example. JohnSmith
merchant_extra1   String Max: 250 Optional Additional custom data field for merchant-specific information that will be returned unchanged in responses and webhooks. Example. JohnSmith
merchant_extra2   String Max: 250 Optional Additional custom data field for merchant-specific information that will be returned unchanged in responses and webhooks. Example. JohnSmith
merchant_extra3   String Max: 250 Optional Additional custom data field for merchant-specific information that will be returned unchanged in responses and webhooks. Example. JohnSmith
merchant_extra4   String Max: 250 Optional Additional custom data field for merchant-specific information that will be returned unchanged in responses and webhooks. Example. JohnSmith
merchant_extra5   String Max: 250 Optional Additional custom data field for merchant-specific information that will be returned unchanged in responses and webhooks. Example. JohnSmith
return_url   String Max: 400 Optional URL where the customer will be redirected after payment processing completion. Must be a valid HTTPS URL for security compliance. Example. https://www.merchant.com
agreement_id   String Max: 15 Optional Identifier for the agreement with the payer to process recurring payments. Used for subscription billing and installment payment scenarios. Do not use special characters. Example. AGR123456789
recurring_mode   String Max: 20 Optional Indicates whether subsequent payments within the agreement have the same amount, different amounts, or are unscheduled with unknown intervals. Values: UNSCHEDULED, VARIABLE, FIXED Example. UNSCHEDULED
recurring_transactions_count   String Max: 100 Optional Number of merchant-initiated payments within the recurring payment agreement. Required when recurring_mode is set to VARIABLE or FIXED. Example. 12
recurring_expiry_date   String Format: YYYY-MM-DD Optional Date when the merchant needs to end the recurring payment agreement. Must be in YYYY-MM-DD format with numeric values and hyphens. Example. 2024-10-05
recurring_days_between_payments   Integer Optional Number of days between payments as agreed with the payer under the recurring payment agreement. Must be numeric values only. Example. 30

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 transactions.

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

Response Parameters

Parameter
command   String Max: 20 Command indicating the transaction type that was executed in the payment processing request. Values: AUTHORIZATION, PURCHASE Example. PURCHASE
access_code   String Max: 20 Merchant access code that was used to authenticate the payment request. Example. zx0IPmPy5jp1vAz
merchant_identifier   String Max: 20 Unique merchant identifier that was used to identify the merchant account in the payment request. Example. CycHZxVj
merchant_reference   String Max: 40 Merchant's unique order reference number that was submitted with the payment request for transaction tracking. Example. XYZ9239-yu898
amount   Integer Max: 10 Transaction amount that was processed in the smallest currency unit. Example. 10000
currency   String Max: 3 Three-letter ISO 4217 currency code that was used for the transaction processing. Example. AED
language   String Max: 2 Language code that determines the checkout page and response message language. Values: en, ar Example. en
customer_email   String Max: 254 Customer's email address that was provided in the payment request for notifications and receipts. Example. customer@domain.com
eci   String Max: 16 E-commerce indicator that classifies the transaction type and processing environment used for the payment. Values: ECOMMERCE Example. ECOMMERCE
expiry_date   String Max: 4 Card expiry date in YYMM format that was provided in the payment request. Example. 2105
card_number   String Max: 19 Masked credit card number showing only the first 6 and last 4 digits for security. MEEZA cards show 19 digits, AMEX shows 15 digits, others show 16 digits. Example. 400555*****0001
customer_ip   String Max: 45 Customer's IP address that was captured for fraud prevention and risk assessment. Supports both IPv4 and IPv6 formats. Example. 192.178.1.10
signature   String Max: 200 SHA-256 hash signature for response verification and data integrity validation using the Secure Hash Algorithm. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name   String Max: 50 Cardholder name as it was provided in the payment request. Example. John Smith
token_name   String Max: 100 Token that was generated or used for the transaction, received from the tokenization process. Example. Op9Vmp
fort_id   Integer Max: 20 Unique transaction reference number generated by Amazon Payment Services system for transaction tracking and identification. Example. 149295435400084008
payment_option   String Max: 10 Payment method that was used to process the transaction. Values: MASTERCARD, VISA, AMEX, MADA (for Purchase operations and eci Ecommerce only), MEEZA (for Purchase operations and ECOMMERCE eci only) Example. VISA
order_description   String Max: 150 Description of the order or service that was provided in the payment request. Example. iPhone 6-S
statement_descriptor   String Max: 50 Custom identifier used as description of the order that appears on customer statements. Supports alphanumeric characters and hyphens. Example. MYSTORE-PURCHASE
customer_name   String Max: 40 Customer's name that was provided in the payment request. Example. John Smith
merchant_extra   String Max: 999 Custom data sent by merchant that is received and returned unchanged. Not displayed in reports but useful for internal tracking. Example. JohnSmith
merchant_extra1   String Max: 250 Additional custom data field sent by merchant that is received and returned unchanged. Not displayed in reports. Example. JohnSmith
merchant_extra2   String Max: 250 Additional custom data field sent by merchant that is received and returned unchanged. Not displayed in reports. Example. JohnSmith
merchant_extra3   String Max: 250 Additional custom data field sent by merchant that is received and returned unchanged. Not displayed in reports. Example. JohnSmith
merchant_extra4   String Max: 250 Additional custom data field sent by merchant that is received and returned unchanged. Not displayed in reports. Example. JohnSmith
merchant_extra5   String Max: 250 Additional custom data field sent by merchant that is received and returned unchanged. Not displayed in reports. Example. JohnSmith
authorization_code   String Max: 100 Authorization code returned from the third-party payment processor confirming transaction approval. Example. P1000000000000372136
response_message   String Max: 150 Human-readable message description of the response code that returns according to the request language setting. Example. Success
response_code   String Max: 5 Five-digit response code that carries the system's response value. First 2 digits represent response status, last 3 digits represent response messages. Example. 14000
status   String Max: 2 Two-digit numeric value that indicates the current status of the transaction processing. Example. 20
3ds_url   String Max: 300 URL where the merchant redirects customers whose cards require 3D Secure authentication for transaction completion. Example. https://www.3dsecure.com
phone_number   String Max: 19 Customer's phone number that was provided in the payment request for verification and notifications. Example. 00962797219966
settlement_reference   String Max: 22 Unique value submitted by merchant that is passed to the acquiring bank and displayed in the merchant's acquirer settlement file. Example. XYZ9239-yu898
agreement_id   String Max: 15 Identifier for the agreement with the payer to process recurring payments. Used for subscription and installment scenarios. No special characters allowed. Example. AGR123456789
issuer_country   String Country of the customer's card issuer in the event of successful purchase payments. Available upon request for enhanced transaction insights. Example. US
issuer_name   String Name of the card issuer in the event of successful purchase payments. Available upon request for enhanced transaction insights. Example. Chase Bank

Contact integration@payfort.com to activate additional response parameters like issuer_country and issuer_name for enhanced transaction insights and reporting capabilities.

3D Secure Authentication

After submitting a payment request, 3D Secure authentication may be required based on the customer's card and issuing bank requirements. If 3DS is required, you must redirect the customer to the 3DS authentication URL provided in the response, otherwise the transaction will not be completed.

Sample Request

{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "Test-10060",
    "amount": 200000,
    "currency": "AED",
    "language": "en",
    "customer_email": "test@payfort.com",
    "signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
    "card_number": "4005550000000001",
    "expiry_date": "2105",
    "card_security_code": "123",
    "card_holder_name": "John Smith",
    "customer_ip": "192.178.1.10",
    "eci": "ECOMMERCE"
}

import requests
import json

# Request payload
request_data = {
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "Test-10060",
    "amount": "200000",
    "currency": "AED",
    "language": "en",
    "customer_email": "test@payfort.com",
    "customer_ip": "192.178.1.10",
    "eci": "ECOMMERCE",
    "card_number": "4005550000000001",
    "expiry_date": "2105",
    "card_security_code": "123",
    "card_holder_name": "John Smith",
    "signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b"
}

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

print(response.json())

<?php

// Request payload
$requestData = [
    'command' => 'PURCHASE',
    'access_code' => 'zx0IPmPy5jp1vAz',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'Test-10060',
    'amount' => '200000',
    'currency' => 'AED',
    'language' => 'en',
    'customer_email' => 'test@payfort.com',
    'customer_ip' => '192.178.1.10',
    'eci' => 'ECOMMERCE',
    'card_number' => '4005550000000001',
    'expiry_date' => '2105',
    'card_security_code' => '123',
    'card_holder_name' => 'John Smith',
    'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b'
];

// Send 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($requestData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    print_r($result);
} else {
    echo 'HTTP Error: ' . $httpCode;
}
?>

# Payment request using cURL
curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "Test-10060",
    "amount": "200000",
    "currency": "AED",
    "language": "en",
    "customer_email": "test@payfort.com",
    "customer_ip": "192.178.1.10",
    "eci": "ECOMMERCE",
    "card_number": "4005550000000001",
    "expiry_date": "2105",
    "card_security_code": "123",
    "card_holder_name": "John Smith",
    "signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b"
  }'

Sample PCI Response

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "Test-10060",
  "amount": "200000",
  "currency": "AED",
  "language": "en",
  "customer_email": "test@payfort.com",
  "eci": "ECOMMERCE",
  "expiry_date": "2105",
  "card_number": "400555******0001",
  "customer_ip": "192.178.1.10",
  "card_holder_name": "John Smith",
  "fort_id": "149295435400084008",
  "payment_option": "VISA",
  "authorization_code": "P1000000000000372136",
  "response_message": "Success",
    "response_code": "14000",
  "status": "20",
  "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4"
}

Client-side Validation

Download the complete client-side validation library that provides comprehensive validation for all payment form fields including card number validation with Luhn algorithm, expiry date validation, CVV validation, and cardholder name validation.
Click to download the file

Response Codes

The response of the payment transaction will be sent to your return URL and to your configured webhook.
For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Testing The Integration

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
• Test Cards: Use our comprehensive Testing Cards

Go-Live Process

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