Skip to main content

Recurring Payments API

Copy page

Copy page as Markdown for LLMs

Anthropic

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

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   Alpha Max: 20 Required

Transaction type to be executed. Only PURCHASE is supported for recurring payments.
Values: PURCHASE
Example. PURCHASE
access_code   Alphanumeric Max: 20 Required

Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings.
Example. zx0IPmPy5jp1vAz8
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. REC-20241209-001
amount   Numeric Max: 10 Required

Payment amount in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer.
Example. 15000
currency   Alpha Max: 3 Required

Three-letter ISO 4217 currency code for the payment amount.
Example. AED
eci   Alpha Max: 16 Required

E-commerce indicator for recurring transaction type classification.
Values: RECURRING
Example. RECURRING
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. john.doe@example.com
token_name   Alphanumeric Max: 100 Required

Previously generated payment token from initial transaction with tokenization enabled.
Special characters: _ - . @
Example. Op9VmpKj8Nm2Qx4
signature   Alphanumeric Max: 200 Required

SHA-256 hash signature for request authentication and integrity validation.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0
agreement_id   Alphanumeric Max: 15 Required

Unique identifier for recurring payment agreement from the original successful payment transaction.
Example. AGR202412090001
payment_option   Alpha Max: 10 Optional

Restrict payment to specific method. Values: VISA, MASTERCARD, AMEX, MADA, etc.
Example. VISA
order_description   Alphanumeric Max: 150 Optional

Human-readable description of the order or service being paid for.
Special characters: ' / . _ - # : $ Space
Example. Premium Subscription - Monthly Billing
statement_descriptor   Alphanumeric Max: 50 Optional

Custom descriptor that appears on customer's bank statement.
Special characters: -
Example. MYSTORE SUBSCRIPTION
customer_name   Alpha Max: 40 Optional

Full name of the customer making the payment.
Special characters: _ \ / - . ' Space
Example. John Doe
phone_number   Alphanumeric Max: 19 Optional

Customer phone number in international format for verification and notifications.
Special characters: + - ( ) Space
Example. +971501234567
settlement_reference   Alphanumeric 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   Alpha Max: 20

Transaction type executed.
Values: PURCHASE
Example. PURCHASE
access_code   Alphanumeric Max: 20

Merchant access code used in the request.
Example. zx0IPmPy5jp1vAz8
merchant_identifier   Alphanumeric Max: 20

Merchant identifier used in the request.
Example. CycHZxVj
merchant_reference   Alphanumeric Max: 40

Unique order reference from the request.
Example. REC-20241209-001
amount   Numeric Max: 10

Transaction amount processed.
Example. 15000
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.
Example. john.doe@example.com
eci   Alpha Max: 16

E-commerce indicator from the request.
Example. RECURRING
token_name   Alphanumeric Max: 100

Payment token used for the recurring transaction.
Example. Op9VmpKj8Nm2Qx4
signature   Alphanumeric Max: 200

Response signature for verification.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a8b9c0d1e2f3a4b5c6d7e8f9a0
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
order_description   Alphanumeric Max: 150

Order description from the request.
Example. Premium Subscription - Monthly Billing
customer_name   Alpha Max: 40

Customer name from the request.
Example. John Doe
expiry_date   Numeric Max: 4

Masked card expiry date (MMYY format).
Example. 2512
card_number   Numeric Max: 16

Masked card number with only first 6 and last 4 digits visible.
Example. 424242*****4242*
authorization_code   Alphanumeric Max: 100

Authorization code from payment processor.
Example. AUTH789456123
response_message   Alphanumeric Max: 150

Human-readable response description in requested language.
Example. Success
response_code   Numeric Max: 5

Numeric response code indicating payment result.
Example. 14000
status   Numeric Max: 2

Two-digit status code indicating payment state.
Example. 20
phone_number   Alphanumeric Max: 19

Customer phone number from the request.
Example. +971501234567
settlement_reference   Alphanumeric Max: 22

Settlement reference from the request.
Example. SETTLE-20241209-001
agreement_id   Alphanumeric 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"
}
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

Was this page helpful?

Thanks for your feedback!