Installments 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 Installments service enables customers to split their payments into manageable monthly installments through partnerships between Amazon Payment Services and issuing banks. Merchants receive the full transaction amount immediately while banks handle installment collection from customers.

Read more about installments in our installments guide.

Installments Integration Options

Choose the integration method that best fits your business requirements and technical capabilities:

Easy Installments

Automatic installment display in hosted checkout when eligible cards and amounts are detected.

Standalone Installments

Dedicated installments page where customers select their preferred installment plan.

Custom Installments

Full control over installment selection process with custom UI and advanced features.

Easy Installments

Easy installments require no additional development effort - simply use the standard hosted checkout request. Installment options will automatically appear in the payment form when all eligibility criteria are met.

Use the standard hosted checkout request with no additional parameters. The installment options will be displayed automatically when:

Service Active: Installment service must be activated on your merchant account
Card Eligible: Customer's card must be eligible for installments with participating banks
Amount Range: Transaction amount must be within the configured minimum and maximum limits for installments

Additional Response Parameters

When installments are used, the following parameter is added to the standard hosted checkout response:

Parameter
number_of_installments `Integer` `Max: 2` Number of installments selected by customer (if installments were used). Example. 3

Easy Installments Request
<!-- HTTPS POST form submitted directly to APS from frontend -->

<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="installments_form">
    
    <!-- Required Transaction Parameters -->
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="INST-ORDER-2024-1725887587">
    
    <!-- Amount: AED 1,500.00 (150000 fils) - Eligible for installments -->
    <input type="hidden" name="amount" value="150000">
    <input type="hidden" name="currency" value="AED">
    <input type="hidden" name="language" value="en">
    
    <!-- Customer Information -->
    <input type="hidden" name="customer_email" value="customer@example.com">
    <input type="hidden" name="customer_ip" value="192.168.1.100">
    
    <!-- Order Details -->
    <input type="hidden" name="order_description" value="Electronics Purchase - Laptop">
    
    <!-- Post-payment redirect URL -->
    <input type="hidden" name="return_url" value="https://www.mystore.com/payment/callback">
    
    <input type="hidden" name="signature" value="a1b2c3d4e5f6789012345678901234567890abcdef123456789012345678901234">
    
    <!-- Submit button -->
    <button type="submit">Pay with Installments Available</button>
    
</form>

Sample Response
command=PURCHASE
access_code=zx0IPmPy5jp1vAz8Kpg7
merchant_identifier=CycHZxVj
merchant_reference=INST-ORDER-2024-1725887587
amount=150000
currency=AED
language=en
response_code=14000
response_message=Success
status=20
fort_id=149295435400084008
payment_option=VISA
authorization_code=P1000000000000372136
customer_email=customer@example.com
number_of_installments=6
signature=b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2

Standalone Installments

Redirect customers to a dedicated installments page where they can select their preferred installment plan before completing the payment. Use the standard hosted checkout request with one additional parameter. This is the same implementation as hosted checkout with just the installments parameter added.

Request Parameters

Include all standard hosted checkout parameters plus the installments parameter:

Parameter
installments `String` `Max: 10` `Required` Specify standalone installments mode to redirect customer to dedicated installments page. Value: `STANDALONE` Example. STANDALONE

Response Parameters

In addition to standard hosted checkout response parameters:

Parameter
installments `String` `Max: 10` Installments service type used. Value: `STANDALONE` Example. STANDALONE
number_of_installments `Integer` `Max: 2` Number of installments selected by customer on the installments page. Example. 3

Standalone Installments Request
<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="standalone_form">
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="language" value="en">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
    <input type="hidden" name="signature" value="2c283da0c3447c84b3c29a4396f4074c56b893">
    <input type="hidden" name="return_url" value="https://example.com">
    <input type="hidden" name="installments" value="STANDALONE">
    <input type="hidden" name="merchant_reference" value="STANDALONE-ORDER-001">
    <input type="hidden" name="customer_email" value="customer@example.com">
    <input type="hidden" name="amount" value="200000">
    <input type="hidden" name="currency" value="AED">
    <button type="submit">Pay with Standalone Installments</button>
</form>

Custom Installments

Custom installments provides complete control over the installment selection process, allowing you to build a tailored user experience with your own UI components.

The custom installments integration follows a 3-step process:

Get Installments Plans - Retrieve available installment plans
Tokenization - Generate secure payment tokens (same as custom integration)
Purchase Operations - Process the installment payment using the token

1. Get Installments Plans

Retrieve available installment plans and issuer details configured for your merchant account. This API provides the foundation for building custom installment selection interfaces.

API Endpoints

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

Request Format

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

Request Parameters

Parameter
query_command `String` `Max: 50` `Required` Query operations command for retrieving installment plans. Value: `GET_INSTALLMENTS_PLANS` Example. GET_INSTALLMENTS_PLANS
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
signature `String` `Max: 200` `Required` SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
amount `Integer` `Max: 10` `Optional` Transaction amount in smallest currency unit. When provided with currency, enables automatic calculation of monthly payment amounts. Example. 10000

Multiply your transaction amount by the currency decimal code per ISO code 3 before sending the amount parameter. For example, if the amount is 500.00 AED, multiply by 100 to send 50000.

| currency String Max: 3 Optional

Three-letter ISO 4217 currency code. Must be provided together with amount parameter.
Example. AED | | language String Max: 2 Optional

Response language for issuer names and messages. Supported values: en (English) or ar (Arabic).
Example. en | | issuer_code String Max: 8 Optional

Filter results by specific card issuer code to get plans for a particular bank.
Example. 12HP34SE |

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

Response Parameters

Parameter
query_command `String` `Max: 50` Query operations command from the request. Value: `GET_INSTALLMENTS_PLANS` Example. GET_INSTALLMENTS_PLANS
access_code `String` `Max: 20` Merchant access code used in the request. Example. zx0IPmPy5jp1vAz
merchant_identifier `String` `Max: 20` Merchant identifier used in the request. Example. CycHZxVj
signature `String` `Max: 200` Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message `String` `Max: 150` Human-readable response description in requested language. Example. Success
response_code `String` `Max: 5` Numeric response code indicating request result. Example. 62000
status `String` `Max: 2` Two-digit status code indicating request state. Example. 62
installment_detail `Object` Container object containing detailed installment plans and issuer information. Example. {issuer_detail: [...]}

Issuer Detail Parameters

Parameter
issuer_code `String` `Max: 8` Unique code identifying the card issuer/bank. Example. fHkigRtu
issuer_name_ar `String` `Max: 50` Bank/issuer name in Arabic language. Example. بنك الامارات دبي الوطني
issuer_name_en `String` `Max: 50` Bank/issuer name in English language. Example. Emirates NBD Egypt
terms_and_condition_ar `String` `Max: 200` URL to Arabic terms and conditions for installment service. Example. https://www.bank.com/terms-ar
terms_and_condition_en `String` `Max: 200` URL to English terms and conditions for installment service. Example. https://www.bank.com/terms-en
country_code `String` `Max: 3` Three-letter ISO country code where the issuer operates. Example. EGY
banking_system `String` `Max: 11` Type of banking system used by the issuer. Values: `Non Islamic`, `Islamic` Example. Non Islamic
formula `String` `Max: 100` Mathematical formula used to calculate installment amounts. Example. (amount +(amount effective rate/100))/period*
plan_details `Array` Array of available installment plans for this issuer. Example. {plan_code: "zAS4XyG2", ...}

Plan Detail Parameters

Parameter
plan_code `String` `Max: 8` Unique code identifying the specific installment plan. Example. zAS4XyG2
currency_code `String` `Max: 3` Currency supported by this installment plan. Example. AED
number_of_installment `Integer` `Max: 2` Number of monthly payments in this plan. Example. 3
fees_type `String` `Max: 10` Type of fees applied to the installment plan. Values: `Fixed`, `Percentage` Example. Percentage
fees_amount `Integer` `Max: 10` Fee amount (fixed amount or percentage based on fees_type). Example. 300
minimum_amount `Integer` `Max: 10` Minimum transaction amount eligible for this plan. Example. 300
maximum_amount `Integer` `Max: 10` Maximum transaction amount eligible for this plan. Example. 33333300
amountPerMonth `Decimal` `Max: 10` Calculated monthly payment amount (only when amount and currency provided in request). Example. 3.00

Get Installments Plans Request
{
  "query_command": "GET_INSTALLMENTS_PLANS",
  "access_code": "zx0IPmPy5jp1vAz",
  "merchant_identifier": "CycHZxVj",
  "amount": 100000,
  "currency": "AED",
  "language": "en",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

Sample Response
{
  "response_code": "62000",
  "response_message": "Success",
  "signature": "9b02960d319318256efbc17cf57dbc1f7e7fd046e20e49215d0bed32a065c3ae",
  "merchant_identifier": "CycHZxVj",
  "access_code": "zx0IPmPy5jp1vAz",
  "query_command": "GET_INSTALLMENTS_PLANS",
  "installment_detail": {
    "issuer_detail": [
      {
        "issuer_code": "fHkigRtu",
        "issuer_name_ar": "بنك الامارات دبي الوطني",
        "issuer_name_en": "Emirates NBD Egypt",
        "country_code": "EGY",
        "banking_system": "Non Islamic",
        "terms_and_condition_ar": "https://www.bank.com/terms-ar",
        "terms_and_condition_en": "https://www.bank.com/terms-en",
        "formula": "(amount +(amount *effective rate/100))/period",
        "plan_details": [
          {
            "plan_code": "zAS4XyG2",
            "currency_code": "AED",
            "number_of_installment": 3,
            "fees_type": "Percentage",
            "fees_amount": 300,
            "minimum_amount": 300,
            "maximum_amount": 33333300,
            "amountPerMonth": "350.00"
          },
          {
            "plan_code": "bCD5YzH3",
            "currency_code": "AED",
            "number_of_installment": 6,
            "fees_type": "Percentage",
            "fees_amount": 500,
            "minimum_amount": 500,
            "maximum_amount": 50000000,
            "amountPerMonth": "175.00"
          }
        ]
      }
    ]
  },
  "status": "62"
}

2. Tokenization

Generate secure payment tokens for installment transactions. This step uses the exact same tokenization process as custom integration.

3. Purchase Operations

Process installment payments using tokens generated from the tokenization step. This uses the same custom integration purchase request with additional installments parameters.

Additional Parameters

Include all standard custom integration purchase parameters plus the installments parameters:

Parameter
installments `String` `Max: 10` `Required` Specify hosted installments mode for custom integration. Value: `HOSTED` Example. HOSTED
issuer_code `String` `Max: 8` `Required` Code identifying the card issuer selected by customer from installment plans. Example. fHkigRtu
plan_code `String` `Max: 8` `Required` Code identifying the specific installment plan selected by customer. Example. zAS4XyG2

Additional Response Parameters

In addition to standard custom integration purchase response parameters:

Parameter
installments `String` `Max: 10` Installments service type used in the transaction. Value: `HOSTED` Example. HOSTED
plan_code `String` `Max: 8` Code identifying the installment plan used for the transaction. Example. zAS4XyG2
issuer_code `String` `Max: 8` Code identifying the card issuer used for the transaction. Example. fHkigRtu
number_of_installments `Integer` `Max: 2` Number of installments selected for the transaction. Example. 3

Installment Calculation Formulas

Amazon Payment Services calculates monthly installment amounts using the following formulas based on the banking system and fee structure:

Percentage Fees

Interest rate charged as a percentage of the transaction amount.

Rate Flat

Non Islamic Banking: ((amount + ((amount * (fees / 100)) * months))) / months
Islamic Banking: (((months * (fees / 100)) + 1) * amount) / months

Rate Reducing

Uses PMT (Excel function) for declining balance calculations

Fixed Fees

Fixed amount charged in addition to the transaction amount.

Formula: (amount + fees) / months

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

Hosted Checkout URL: https://sbcheckout.payfort.com/FortAPI/paymentPage
Payment API 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 for complete production readiness guidelines.

Response Codes

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

Installments Integration Options​

Easy Installments

Standalone Installments

Custom Installments

Easy Installments​

Additional Response Parameters​

Standalone Installments​

Request Parameters​

Response Parameters​

Custom Installments​

1. Get Installments Plans​

API Endpoints​

Request Format​

Request Parameters​

Response Parameters​

Issuer Detail Parameters​

Plan Detail Parameters​

2. Tokenization​

3. Purchase Operations​

Additional Parameters​

Additional Response Parameters​

Installment Calculation Formulas​

Percentage Fees​

Rate Flat​

Rate Reducing​

Fixed Fees​

Testing The Integration​

Sandbox Testing​

Go-Live Process​

Response Codes​

Installments Integration Options

Easy Installments

Additional Response Parameters

Standalone Installments

Request Parameters

Response Parameters

Custom Installments

1. Get Installments Plans

API Endpoints

Request Format

Request Parameters

Response Parameters

Issuer Detail Parameters

Plan Detail Parameters

2. Tokenization

3. Purchase Operations

Additional Parameters

Additional Response Parameters

Installment Calculation Formulas

Percentage Fees

Rate Flat

Rate Reducing

Fixed Fees

Testing The Integration

Sandbox Testing

Go-Live Process

Response Codes