Installment Service

In this API reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on our Installment Service, see our Overview.

The GetEligiblePlans request is used to retrieve the eligible plans that match the card issuer’s criteria for the transaction.

Sample request

curl https://api.sandbox.globalpay-ecommerce.com/installments/plans/match
-H "Content-type: application/json"
-H "Authorization: sha256hash ff90a189d9ba5a23eec8578ddffba350fbd701faaba7428c59b65ca2c83e1bdd" 
-X POST 
-d '{
  "partner": "GPECOM",
  "provider": "VIS",
  "merchant_id": "MerchantId",
  "account_id": "accountId",
  "card": {
    "number": "4263970000005262"
    "number_is_network_token": false
   },  
  "amount": "1000",
  "currency": "CAD",
  "channel": "ECOM",
  "request_timestamp": "2023-01-01T12:00:00.000Z",
  "filter": {
    "enabled": true,
    "max_term_months_merchant_funded": 24,
    "plan_type": "MERCHANT_FUNDED"
    "amount_threshold": 1000
  }
}'

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Sample response

{
  "amount": 1000000,
  "currency": "CAD",
  "matched_plans": [
    {
      "name": "plan24CwAPR",
      "type": "ISSUER_DEFAULT",
      "number_of_installments": 24,
      "funded_by": [
                    "CONSUMER"
                                ],
      "installment_frequency": "MONTHLY",
      "terms_and_conditions": [
        {
          "url": "http://www.myurl.com",
          "version": "25798469",
          "text": "You are selecting a 24-month installment plan. The total purchase amount will be deducted from your available credit limit. As set forth in your terms, your installment fee will be 13.99% APR calculated for 24 months. If you miss an installment payment, the standard rate of purchases will apply to the remaining installment balance.",
          "language_code": "ENG"
        }
      ],
      "cost_info": {
        "annual_percentage_rate": 13.99,
        "fee_info": [
          {
            "type": "CONSUMER",
            "rate_percentage": 5,
            "flat_fee": 0
          }
        ],
        "total_plan_cost": 1130500,
        "total_fees": 130500,
        "total_upfront_fees": 100000,
        "total_recurring_fees": 30500,
        "first_installment": {
          "upfront_fee": 100000,
          "installment_fee": 1270,
          "amount": 41666
        },
        "last_installment": {
          "installment_fee": 1270,
          "amount": 41666
        },
        "currency": "CAD"
      },
      "plan_id": "7533d4f7-6a10-5557-2e92-132d06157502"
    }
  ]
}

Response syntax

Send the plan details in the Authorization request to confirm the selected installment plan by the user. After the cardholder selects an installment plan, the merchant should provide installment plan details in the Auth and Receipt-in requests under the optional XML tag.

For the full Authorization request, see Authorization in the API Reference.

Sample request

<installment>
           <provider>VIS</provider>
           <planid>3fa85f64-5717-4562-b3fc-2c963f66afa6</planid>
           <tcversion>2</tcversion>
           <tclang>eng</tclang>
</installment>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

The following table contains errors that are specific to the Installment Service. For the full list of errors, see Messages & Errors.

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-256 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Build the request hash

1. Using the SHA-256 algorithm, hash a string made up of the request values
   The blueprint of the hash for this request is shown below:
   
   

   "request_timestamp.merchant_id.cardnumber"

   
   Based on the request above, our initial string will be:
   
   

   "2019-04-26T10:16:10.154248.MerchantId.4263970000005262"

   
   
2. Concatenate the hashed string with your Shared Secret
   After step 1, you'll have a string like:
   
   

   f6d5f2950c49e85bee09119d50de7ca76243de9c4f4ca340175b563162868e2e

   
   You'll need to concatenate this with your Shared Secret. For example:
   
   

   "f6d5f2950c49e85bee09119d50de7ca76243de9c4f4ca340175b563162868e2e.Po8lRRT67a"

   
   
3. SHA-256 hash the concatenated string
   Our final string that we add to the request should be a hash using the SHA-256 algorithm of your concatenated string. For example:
   
   

   8f2436777317085a3442286315f69532592222fc4e325b69559559179ce6120c

Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-256 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the response hash

1. Create a SHA-256 hash string made up of response values
   The blueprint of the hash for the response is shown below:
   
   

   "timestamp.merchantid.orderid.result.message.pasref.authcode"

   
   
   

   So, based on the above example, the initial string to check the hash of the response will be:
   
   

   "20200204155942.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.[ test system ] Authorised.14631546336115597.12345"

   
   

2. Concatenate the hashed string with your Shared Secret
   After step 1, you'll have a string like:
   
   

   f4c954b5196e73883edcf1d74e5722ced0914dea852c52a07fbe1b4b04c8ca6b

   
   

   You'll need to concatenate this with your Shared Secret:
   
   

   "f4c954b5196e73883edcf1d74e5722ced0914dea852c52a07fbe1b4b04c8ca6b.Po8lRRT67a"

   
   

3. SHA-256 hash the concatenated string and compare
   Our final string that we add to the request should be a hash using the SHA-256 algorithm of your concatenated string. For example:
   
   

   f18178e6bf4d1bf17269fbd8a244fbd43be60c1d9b868bf00e06307b6d76d9be

   
   
   

   We create the hash in the same way on our side and send it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha256hash element.