Installment Service | Global Payments

To use our Installment Service, you first need to get it enabled on your account. To do this, contact your Global Payments account manager.

info

For more information on our Installment Service, see our Overview.

Retrieve installment plans

Installment Service endpoints:

Sandbox: https://api.sandbox.globalpay-ecommerce.com/installments/plans/match
Production: https://api.globalpay-ecommerce.com/installments/plans/match

info

Here, we use the GetEligiblePlans request to retrieve the eligible plans that match the Issuer’s criteria for the transaction.

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" 
   },  
  "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 [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
partner	string	enum	M		Allowed values: GPECOM
provider	string	enum	M		Installment provider to be used. Allowed values: VIS
merchant_id	string	alpha- numeric	M	1-50	Your Client ID assigned by Global Payments. Allowed characters: [a-zA-Z0-9.]
account_id	string	alpha- numeric	M	1-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
card*
*Should only send one “number" OR "payer_reference & payment_method_reference(Optional)" OR "token"
number	string	numeric	M	12-19	The full Primary Account Number (PAN) of the card. Allowed characters:[0-9]
payer_ reference	string	alpha-numeric	M	1-50	A unique reference for this customer in Card Storage, known as the Payer. Allowed characters: [a-zA-Z0-9_-.]
payer_method_ reference	string	alpha-numeric	O	1-50	A unique reference for this card in Card Storage, known as the Payment Method. Allowed characters: [a-zA-Z0-9_-.]
token	string	alpha-numeric	M	1-56	A unique reference for this card in Card Storage, known as the token and begins with the three letters “PMT_” Allowed characters: [a-zA-Z0-9_-]
amount	integer		M	1-11	The amount should be in the smallest unit of the required currency. Example: 2000 = €20.00
currency	string	ISO 4217	M	3	The processing currency of the transaction. See the list of Currency Codes.
channel	string	enum	O		Specify how a transaction is to be processed. Allowed values: ECOM – Ecommerce (default) CARD_PRESENT – Card Present Note: If not present, request will be sent with default value.
request_ timestamp	string	UTC time zone	O		Only required for direct merchant authentication. Example: 2023-01-01T12:00:00.000Z
filter
enabled	boolean		O		Used to retrieve two installment plans only. Allowed values: TRUE - Retrieves two plans (default). FALSE - Retrieves all available plans. Note: If not present, request will be sent with default value.
max_term_ months_ merchant_ funded	integer	<int32>	O	1-32	Used to retrieve installment plans with specific tenure. Applicable to merchant-funded plans only. Example: max_term_months_merchant_funded = 12 — Means that only plans with tenure ≤ 12 months will be retrieved. Merchant-funded plans with tenure > 12 months will not be returned. Default: 1000 Note: If not present, request will be sent with default value.
plan_type	string	enum	O		Used to filter out installment plans based on plan type. Allowed values: MERCHANT_FUNDED (default) CONSUMER_FUNDED ANY (merchant & consumer funded) Note: If not present, request will be sent with default value.
amount_ threshold	integer	<int32>	O	1-11	Used to determine whether to return the longest or shortest tenure/duration plans depending on the amount sent. The amount should be sent in the smallest unit of the required currency. Example: 2000 = €20.00 Ex value sent 50000 will mean that: For transactions with an amount less or equal than €500.00, the plans with the shortest tenure will be displayed first. For transactions with an amount greater than €500.00, the plans with the longest tenure will be displayed first. Note: If not present, request will be sent with default value: plans with the longest tenure.

Sample response

{
  "amount": 1000000,
  "currency": "CAD",
  "matched_plans": [
    {
      "name": "plan24CwAPR",
      "type": "ISSUER_DEFAULT",
      "number_of_installments": 24,
      "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

Element/Field	Category	Format	Description
amount	integer		The amount should be in the smallest unit of the required currency. Example: 2000 = €20.00
currency	string	ISO 4217	The processing currency of the transaction. See list of Currency Codes. Example: CAD
matched_plans name	string	1-255	Name of the installment plan.
Matched_plans type	string	enum	Type of the installment plan: ISSUER_PROMOTION BI_LATERAL (not currently supported) ISSUER_DEFAULT MARKET For more information, see Installment Service.
Matched_plans number_of_installments	integer	1-4	Maximum number of installments that can be in the plan acceptance created from this plan.
Matched_plans installment_frequency	string	enum	Supported tenure types for a plan: WEEKLY (not currently supported) BIWEEKLY (not currently supported) MONTHLY BIMONTHLY (not currently supported)
Matched_plans terms_and_conditions url	string		Terms and conditions (T&C) HTTPS URL hosted by the Issuer for displaying to the cardholder for acceptance when initiating a plan acceptance for this plan. Must not invoke an executable script and must point to an HTML page containing T&C text in a displayable manner. When provided during onboarding, the URL is checked for validity. Pattern: ^(http)(s?)\:\/\/[0-9a-zA-Z]([-.\w][0-9a-zA-Z])(:(0-9))(\/?)([a-zA-Z0-9\-\.\?\,\'\/\\\+&%\$#_=]*)?$ Example: http://www.myurl.com
Matched_plans terms_and_conditions version	string	1 - 10	Installment plan terms and conditions (T&Cs) version that is accepted by the customer. The version is auto-incremented every time an update is made to the plan by the Issuer in the Visa Developer Center/Portal UI.
Matched_plans terms_and_conditions text	string	1 - 2000	Text of the terms and conditions for the installment plan.
Matched_plans terms_and_conditions language_code	string	3	ISO 639-2 language code for the terms and conditions text. For more information, see ISO 639-2.
Matched_plans cost_info annual_percentage_rate	Number	1-5	Annual percentage rate (APR) as configured by the Issuer during plan creation. Not used for calculations but used only for display purposes. Interest-fee rate in percentage applied on installment payment. Percentage rate is a non-negative value. The percentage value is represented with two implicit decimals. Example: 13.99%
Matched_plans cost_info fee_info type	String	enum	Fee type(s) with the associated ratePercentage or flatFee. CONSUMER – Fee for Consumer-funded plan. CONSUMER_UPFRONT – Upfront fee that Consumer must pay to Issuer. MERCHANT_FUNDING – Fee for Merchant-funded plan must pay to Issuer. MERCHANT_SERVICE – Service fee charged to the Merchant by Visa.
Matched_plans cost_info fee_info rate_percentage	Number	1-5	(Conditional) Interest fee rate in percentage applied on Installment payment. Percentage rate is a non-negative value. The percentage value is represented with two implicit decimals. Example: 2.5% Should flatFee be provided, then ratePercentage is not required and becomes an optional field.
Matched_plans cost_info fee_info flat_fee	integer	1-15	(Conditional) Flat fee applied on the first installment payment in Issuer currency. The amount is only represented in minor units. Example: in cents for USD currency There are no fractional minor units; they are rounded to a whole number in minor units. The currency field contains the number of minor units (per ISO 4217). Example: “123112” in USD represents the amount, USD 1231.12. Should ratePercentage be provided, then flatFee is not required and becomes an optional field.
Matched_plans cost_info total_plan_cost	integer	1 - 15	(Required) It is calculated as totalFees + (numberOfInstallments * installmentAmount).
Matched_plans cost_info total_fees	integer	1 - 15	(Required) Total fees charged calculated as totalUpfrontFees + totalRecurringFees.
Matched_plans cost_info total_upfront_fees	integer	1 - 15	(Required) Total upfront fees charged to the consumer for this installment plan. This is the amount charged upfront along with the first installment principal only.
Matched_plans cost_info total_recurring_fees	integer	1 - 15	(Required) Total recurring fees for this installment plan. This is calculated as numberOfInstallments * feePerInstallmentPeriod.
Matched_plans cost_info first_installment upfront_fee	integer	1 - 15	(Required) The consumer upfront fee for this installment plan and is included only on the first installment. This fee corresponds to the feeType, CONSUMER_UPFRONT Conditionality – This is available only on the first installment.
Matched_plans cost_info first_installment installment_fee	integer	1 - 15	(Required) The consumer fee for every installment period, including the first one. This fee corresponds to the feeType – CONSUMER
Matched_plans cost_info first_installment amount	integer	1 - 15	The principal amount for this Installment calculated as total_purchase_amount / number_of_installments.
Matched_plans cost_info last_installment installment_fee	integer	1 - 15	(Required) The consumer fee for every installment period, including the last one. This fee corresponds to the feeType – CONSUMER
Matched_plans cost_info last_installment amount	integer	1 - 15	(Required) The principal amount for this Installment calculated as total_purchase_amount / number_of_installments.
Matched_plans cost_info currency	String	ISO 4217	The processing currency of the transaction. See list of Currency Codes. Example: CAD
Matched_plans plan_id	String	36	Allowed characters: [0-9a-fA-F] Example: 7533d4f7-6a10-5557-2e92-132d06157502

Confirm selected plan

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.

Installment Service Confirm Selected Plans endpoints:

Sandbox: https://api.sandbox.globalpay-ecommerce.com/installments/confirmations
Production: https://api.globalpay-ecommerce.com/installments/confirmations

info

<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 [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
provider	string	enum	M		Installment provider to be used. Allowed values: VIS
planid	string	alphanumeric	M	1-50	Plan id value returned in the Get Eligible Plans response.
tcversion	string	alphanumeric	M	1-10	Installment Plan Terms and Conditions Version accepted by the consumer returned in the Get Eligible Plans response.
tclang	string	alphanumeric	M	3	ISO 639-2 language code for the Terms and Conditions text returned in the Get Eligible Plans response.

Error codes

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

Error No.	Integration Type	Description
205	API/HPP	Comms Error - Installment connection error.
508	API	Installment is not allowed for this account.
508	API	Installment is not allowed for this acquirer.
508	API	Installment is not supported for this transaction.
508	API	Can't settle for more than 105% of that which you authorized.
508	API	You may only settle up to 105% of the original amount.
508	API	Can't settle a settled transaction for Installment.
508	API	Invalid data for installment request.
508	API	Can't void a rebate for Installment.
512	API	You may only refund up to 105% of the original amount.

error-codes

Generate hash

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.

In addition to SHA-256, you can also generate your hash using SHA-1. The resulting hash should be placed in the <sha256hash> tag instead of the <sha1hash> tag. For more information, contact our support team at ecomsupport@globalpay.com.

info

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

Check hash

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.

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

Global Payments creates the hash in the same way on our side and sends 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.

Internal Title

API Reference

Show Content Nav