Subscription details

If you offer subscription services, the required API request fields vary by the subscription model you choose. Common models include:

No trial period: The consumer is billed the total subscription cost at regular intervals (days, weeks, months, or years) starting from sign-up, with subsequent renewals unless canceled.
Free trial: A predefined trial period during which charges are waived. After the trial, billing begins at the standard subscription rate.
Discount trial offer: A reduced rate for a defined trial period, then the regular price starts afterward.
Discounted trial paid upfront: The entire discounted trial period cost is paid upfront at signup; after the trial, billing proceeds at the standard rate.

Each model has its own data requirements and timing rules for when charges occur. All scenarios below cover the requirements to comply with Mastercard recurring mandate.

Scenarios

No trial period

A consumer initiates the subscription and pays the total amount every X number of days/weeks/months/quarters/years.

- isRecurring set to true
- recurringPaymentsData.recurringInterval.intervalFrequency
- recurringPaymentsData.recurringInterval.interval
- order.amountOfMoney - the amount consumer will be paying.

POST HOSTEDCHECKOUTS REQUEST

{
        "order": {
          "amountOfMoney": {
            "currencyCode": "EUR",
            "amount": 2345
          },
          "customer": {
              "merchantCustomerId":89769876,
            "billingAddress": {
                 
              "countryCode": "NL"
            }
          }
        },
        "hostedCheckoutSpecificInput": {
          "isRecurring": true,
          "recurringPaymentsData": {
              "recurringInterval":{
                  "intervalFrequency": "1",
                  "interval": "weeks"
              }
          },
          "variant": "testVariant",
          "locale": "en_GB"
        }
      }

Free trial

A consumer initiates the subscription and pays the total amount every X number of days/weeks/months/quarters/years.

- isRecurring set to true.
- recurringPaymentsData.recurringInterval.intervalFrequency
- recurringPaymentsData.recurringInterval.interval order.amountOfMoney set to zero.
- recurringPaymentsData.trialInformation.amountOfMoneyAfterTrial - the amount that the cardholder will be paying after the free trial.
- recurringPaymentsData.trialInformation.endDate OR recurringPaymentsData.trialInformation.trialPeriod

TRIAL END DATE REQUEST


    {
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 0
    },
    "customer": {
        "merchantCustomerId":89769876,
      "billingAddress": {
           
        "countryCode": "NL"
      }
    }
  },
  "hostedCheckoutSpecificInput": {
    "isRecurring": true,
    "recurringPaymentsData": {
        "trialInformation":{
        "endDate": "20300201",
        "amountOfMoneyAfterTrial":{
            "currencyCode": "EUR",
            "amount": 1000
        }
    },
        "recurringInterval":{
            "intervalFrequency": "1",
            "interval": "weeks"
        }
    },
    "variant": "testVariant",
    "locale": "en_GB"
  }
}

free-trial-with-end-date-checkout-screen

TRIAL PERIOD REQUEST


    {
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 0
    },
    "customer": {
        "merchantCustomerId":89769876,
      "billingAddress": {
          
        "countryCode": "NL"
      }
    }
  },
  "hostedCheckoutSpecificInput": {
    "isRecurring": true,
    "recurringPaymentsData": {
        "trialInformation":{
        "trialPeriod": {
            "duration":20,
            "interval":"days"
        },
        "amountOfMoneyAfterTrial":{
            "currencyCode": "EUR",
            "amount": 1000
        }
    },
        "recurringInterval":{
            "intervalFrequency": "1",
            "interval": "weeks"
        }
    }, 
    "variant": "testVariant",
    "locale": "en_GB"
  }
}

free-trial-with-trial-period-checkout-screen

Discount trial offer – subscription starts with a discount applied to X period of time.
- hostedCheckoutSpecificInput.isRecurring (set to true)
- hostedCheckoutSpecificInput.recurringPaymentsData.recurringInterval.intervalFrequency
- hostedCheckoutSpecificInput.recurringPaymentsData.recurringInterval.interval
- order.amountOfMoney (should be populated with the discounted amount)
- hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.amountOfMoneyAfterTrial (the amount cardholder will be paying after the discount trial)
- hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.endDate OR hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.trialPeriod
- hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.isRecurring (set to true)
- optional hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.trialPeriodRecurringInterval (to be used only if the billing frequency during the trial period is different from the main subscription period)

TRIAL PERIOD REQUEST


    {
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 500
    },
    "customer": {
        "merchantCustomerId":89769876,
      "billingAddress": {
          
        "countryCode": "NL"
      }
    }
  },
  "hostedCheckoutSpecificInput": {
    "isRecurring": true,
    "recurringPaymentsData": {
        "trialInformation":{
        "isRecurring": true,
        "trialPeriod": {
            "duration":2,
            "interval":"weeks"
        },
        "amountOfMoneyAfterTrial":{
            "currencyCode": "EUR",
            "amount": 1000
        }
    },
        "recurringInterval":{
            "intervalFrequency": "1",
            "interval": "weeks"
        }
    }, 
    "variant": "testVariant",
    "locale": "en_GB"
  }
}

discount-trial-offer-with-trial-period-checkout-page

TRIAL END DATE REQUEST


    {
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 500
    },
    "customer": {
        "merchantCustomerId":89769876,
      "billingAddress": {
          
        "countryCode": "NL"
      }
    }
  },
  "hostedCheckoutSpecificInput": {
    "isRecurring": true,
    "recurringPaymentsData": {
        "trialInformation":{
        "isRecurring": true,
        "endDate": "20300201", 
        "amountOfMoneyAfterTrial":{
            "currencyCode": "EUR",
            "amount": 1000
        }
    },
        "recurringInterval":{
            "intervalFrequency": "1",
            "interval": "weeks"
        }
    }, 
    "variant": "testVariant",
    "locale": "en_GB"
  }
}

discount-trial-offer-with-trial-end-date-checkout-screen

Discount trial offer, paid fully upfront – a consumer initiates the subscription and pays the discounted price for the trial period upfront.
- hostedCheckoutSpecificInput.isRecurring (set to true)
- hostedCheckoutSpecificInput.recurringPaymentsData.recurringInterval.intervalFrequency
- hostedCheckoutSpecificInput.recurringPaymentsData.recurringInterval.interval
- order.amountOfMoney (the amount to be paid once)
- hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.amountOfMoneyAfterTrial (the amount consumer will be paying after the discount trial)
- hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.endDate OR hostedCheckoutSpecificInput.recurringPaymentsData.trialInformation.trialPeriod (discount period for X amount of days/quarters/months/years OR until X-date)

TRIAL PERIOD REQUEST


    {
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 5000
    },
    "customer": {
        "merchantCustomerId":89769876,
      "billingAddress": {
          
        "countryCode": "NL"
      }
    }
  },
  "hostedCheckoutSpecificInput": {
    "isRecurring": true,
    "recurringPaymentsData": {
        "trialInformation":{
        "isRecurring": false,
        "trialPeriod": {
            "duration": 10,
            "interval": "weeks"
        },
        "amountOfMoneyAfterTrial":{
            "currencyCode": "EUR",
            "amount": 1000
        }
    },
        "recurringInterval":{
            "intervalFrequency": "1",
            "interval": "weeks"
        }
    }, 
    "variant": "testVariant",
    "locale": "en_GB"
  }
}

discount-trial-paid-upfront-with-trial-preiod-checkout-screen

TRIAL END DATE REQUEST


    {
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 5000
    },
    "customer": {
        "merchantCustomerId":89769876,
      "billingAddress": {
          
        "countryCode": "NL"
      }
    }
  },
  "hostedCheckoutSpecificInput": {
    "isRecurring": true,
    "recurringPaymentsData": {
        "trialInformation":{
        "isRecurring": false,
        "endDate": "20300201", 
        "amountOfMoneyAfterTrial":{
            "currencyCode": "EUR",
            "amount": 1000
        }
    },
        "recurringInterval":{
            "intervalFrequency": "1",
            "interval": "weeks"
        }
    }, 
    "variant": "testVariant",
    "locale": "en_GB"
  }
}

discount-trial-paid-upfront-with-trial-end-date-checkout-screen