Recurring Payments 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

The recurring payments integration allows merchants to process subscription-based and repeat payments using previously stored payment tokens. This enables automated billing for services like subscriptions, installments, and other recurring charges without requiring customers to re-enter payment 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

Recurring payments require a valid token_name and agreement_id obtained from a previous successful transaction. The token represents the stored payment method and customer agreement.

Request Parameters

Parameter
command   String Max: 20 Required Transaction type to be executed. Only PURCHASE is supported for recurring payments. Values: PURCHASE Example. PURCHASE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8
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. REC-20241209-001
amount   Integer Max: 10 Required Payment amount in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer. Example. 15000
currency   String Max: 3 Required Three-letter ISO 4217 currency code for the payment amount. Example. AED
eci   String Max: 16 Required E-commerce indicator for recurring transaction type classification. Values: RECURRING Example. RECURRING
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. john.doe@example.com
token_name   String Max: 100 Required Previously generated payment token from initial transaction with tokenization enabled. Example. Op9VmpKj8Nm2Qx4
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0
agreement_id   String Max: 15 Required Unique identifier for recurring payment agreement from the original successful payment transaction. Example. AGR202412090001
payment_option   String Max: 10 Optional Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, etc. Example. VISA
order_description   String Max: 150 Optional Human-readable description of the order or service being paid for. Example. Premium Subscription - Monthly Billing
statement_descriptor   String Max: 50 Optional Custom descriptor that appears on customer's bank statement. Example. MYSTORE SUBSCRIPTION
customer_name   String Max: 40 Optional Full name of the customer making the payment. Example. John Doe
phone_number   String Max: 19 Optional Customer phone number in international format for verification and notifications. Example. +971501234567
settlement_reference   String Max: 22 Optional Unique reference passed to acquiring bank for settlement file identification. Example. SETTLE-20241209-001
card_number   String Max: 19 Optional Card number for PCI certified custom integration. Only available for merchants with PCI DSS certification. Note: For PCI certified merchants only Example. 4242424242424242
expiry_date   String Max: 4 Optional Card expiry date in MMYY format for PCI certified custom integration. Note: For PCI certified merchants only Example. 2512
card_security_code   String Max: 4 Optional Card CVV/CVC security code for PCI certified custom integration. Note: For PCI certified merchants only Example. 123
card_holder_name   String Max: 50 Optional Cardholder name as printed on the card for PCI certified custom integration. Note: For PCI certified merchants only Example. John Doe

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 Transaction type executed. Values: PURCHASE Example. PURCHASE
access_code   String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8
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. REC-20241209-001
amount   Integer Max: 10 Transaction amount processed. Example. 15000
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. john.doe@example.com
eci   String Max: 16 E-commerce indicator from the request. Example. RECURRING
token_name   String Max: 100 Payment token used for the recurring transaction. Example. Op9VmpKj8Nm2Qx4
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0
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
order_description   String Max: 150 Order description from the request. Example. Premium Subscription - Monthly Billing
customer_name   String Max: 40 Customer name from the request. Example. John Doe
expiry_date   String Max: 4 Masked card expiry date (MMYY format). Example. 2512
card_number   String Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 424242*****4242*
authorization_code   String Max: 100 Authorization code from payment processor. Example. AUTH789456123
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating payment result. Example. 14000
status   String Max: 2 Two-digit status code indicating payment state. Example. 20
phone_number   String Max: 19 Customer phone number from the request. Example. +971501234567
settlement_reference   String Max: 22 Settlement reference from the request. Example. SETTLE-20241209-001
agreement_id   String Max: 15 Agreement identifier from the request. Example. AGR202412090001

Important Notes

• Please make sure always to handle the response parameters correctly, ensuring that you map and send the proper values between CIT and MIT, in specific for agreement_id, token_name parameter.
• There is no restriction on the number of times you can submit the recurring request, and no specific dates you should adhere to. You can initiate the recurring transaction at any frequency—daily, weekly, or monthly—according to your preference, using your own cron job.
• Merchants integrating PCI custom integration, can send card information (card_number, expiry_date, card_security_code, card_holder_name) directly in recurring requests without token_name.Non-PCI certified merchants must use tokenized payments only.

Response Codes

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

Sample Request

{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "REC-20241209-001",
    "amount": 15000,
    "currency": "AED",
    "language": "en",
    "customer_email": "john.doe@example.com",
    "eci": "RECURRING",
    "token_name": "Op9VmpKj8Nm2Qx4",
    "agreement_id": "AGR202412090001",
    "order_description": "Premium Subscription - Monthly Billing",
    "customer_name": "John Doe",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0"
}

import requests

# Recurring payment request data
recurring_data = {
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "REC-20241209-001",
    "amount": "15000",
    "currency": "AED",
    "language": "en",
    "customer_email": "john.doe@example.com",
    "eci": "RECURRING",
    "token_name": "Op9VmpKj8Nm2Qx4",
    "agreement_id": "AGR202412090001",
    "order_description": "Premium Subscription - Monthly Billing",
    "customer_name": "John Doe",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0"
}

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

result = response.json()

<?php
// Recurring payment request data
$recurringData = [
    'command' => 'PURCHASE',
    'access_code' => 'zx0IPmPy5jp1vAz8',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'REC-20241209-001',
    'amount' => '15000',
    'currency' => 'AED',
    'language' => 'en',
    'customer_email' => 'john.doe@example.com',
    'eci' => 'RECURRING',
    'token_name' => 'Op9VmpKj8Nm2Qx4',
    'agreement_id' => 'AGR202412090001',
    'order_description' => 'Premium Subscription - Monthly Billing',
    'customer_name' => 'John Doe',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0'
];

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

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

$result = json_decode($response, true);
?>

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "REC-20241209-001",
    "amount": "15000",
    "currency": "AED",
    "language": "en",
    "customer_email": "john.doe@example.com",
    "eci": "RECURRING",
    "token_name": "Op9VmpKj8Nm2Qx4",
    "agreement_id": "AGR202412090001",
    "order_description": "Premium Subscription - Monthly Billing",
    "customer_name": "John Doe",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0"
  }'

Sample Response

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "REC-20241209-001",
  "amount": "15000",
  "currency": "AED",
  "language": "en",
  "customer_email": "john.doe@example.com",
  "eci": "RECURRING",
  "token_name": "Op9VmpKj8Nm2Qx4",
  "agreement_id": "AGR202412090001",
  "order_description": "Premium Subscription - Monthly Billing",
  "customer_name": "John Doe",
  "fort_id": "149295435400084008",
  "payment_option": "VISA",
  "authorization_code": "AUTH789456123",
  "response_message": "Success",
    "response_code": "14000",
  "status": "20",
  "card_number": "424242******4242",
  "expiry_date": "2512",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0"
}

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

Go-Live Process

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