Custom Payment Plans
Custom payment plans are based on a template-instance system, where you can create instances of one of 5 payment plan templates by specifying the number of installments and the deferral period (where applicable).
- Pay in installments, interest free
- Pay in installments after a deferral period, with interest
- Pay in installments, with interest
- Pay in full after a deferral period
- Pay in installments after a deferral period, interest free
For example, you may create the following payment plans:
- End of Financial Year Offer - no interest, no payments for six months (an instance of template 5)
- Easy Repayment - fixed payments for three months, interest free (an instance of template 1)
- Christmas offer - buy now, pay in full in six months (an instance of template 4)
Custom payment plans are currently offered by:
- Banamex
- BBVA Bancomer
- First Data Brazil
- First Data Argentina
Payment plan inquiry
You can request the gateway for a list of valid plans for a transaction using the Payment Options Inquiry
operation. The following details about the supported payment plans are returned:
paymentTypes.card.paymentPlans[n].startDate
:The start date for the payment plan.paymentTypes.card.paymentPlans[n].endDate
:The end date for the payment plan.paymentTypes.card.paymentPlans[n].numberOfPayments[n]
: The number of monthly installments payable by the payer (if applicable to the plan type).paymentTypes.card.paymentPlans[n].numberOfDeferrals[n]
: The number of months up to which payment can be deferred (if applicable to the plan type).paymentTypes.card.paymentPlans[n].minimumOrderAmounts[n].amount
: The minimum order amount for the payment plan in the supported currency. The configured payment plans will be offered only if the total order amount is greater than or equal to this minimum order amount.paymentTypes.card.paymentPlans[n].minimumOrderAmounts[n].currency
: The currency for the minimum order amount.paymentTypes.card.paymentPlans[n].payerInterest
: Indicates if the payer is charged interest on the payment plan.paymentTypes.card.paymentPlans[n].planId
: A system-generated unique identifier for the payment plan. The plan identifier is unique across all payment plan types that you may have configured.paymentTypes.card.paymentPlans[n].planName
: A merchant-supplied identifier for the payment plan. For example, End Of Financial Year Offer.paymentTypes.card.paymentPlans[n].planTemplate
: The payment plan template used to generate the payment plan instance. For example, Pay in installments, interest free.
Generally there is a maximum of 99 installments and/or deferral months. However, your payment service provider can configure the maximum limit for each template as part of the merchant configuration.
From the version 70 onwards, for the payment plan ID generated by the system, the available payment plan offers are returned. A list of payment plan offers is returned based on the currency and minimum order amount.
Each payment plan offer will have a unique offer ID:
paymentPlanProduct.{paymentPlanProductId}
paymentPlanProduct.{paymentPlanProductId}.name
paymentPlanProduct.{paymentPlanProductId}.logoUrl
paymentTypes.card.paymentPlanOffer.{id}
paymentTypes.card.paymentPlanOffer{id}.paymentPlanProductId
paymentTypes.card.paymentPlanOffer.{id}.currency
paymentTypes.card.paymentPlanOffer.{id}.numberofPayments
paymentTypes.card.paymentPlanOffer.{id}.subsequentPaymentAmount
paymentTypes.card.paymentPlanOffer.{id}.firstPaymentAmount
paymentTypes.card.paymentPlanOffer{id}.minimumOrderAmount
paymentTypes.card.paymentPlanOffer.{id}.deferralPeriod
paymentTypes.card.paymentPlanOffer.{id}.interest.charged
paymentTypes.card.paymentPlanOffer.{id}.startDate
paymentTypes.card.paymentPlanOffer.{id}.endDate
paymentTypes.card.paymentPlanOffer.{id}.planTemplate
Payment Options Inquiry API Reference [REST][NVP]
Request a payment plan
To request a payment plan for a transaction, provide the following fields in an Authorize
/Pay
or Update Session
request:
paymentPlan.numberOfDeferrals
paymentPlan.numberOfPayments
paymentPlan.planId
The gateway processes a payment plan only if the following conditions are met:
- The current date is greater than or equal to the start date.
- The current date is less than or equal to the end date.
- The order amount exceeds the minimum order amount defined on the payment plan.
- The order currency is supported on the payment plan.
- The card type is supported on the payment plan.
From the version 70 onwards, provide only the paymentPlan.offerId
field in the Authorize/Pay or Update Session request with the offer ID provided in the Payment Options Inquiry response.
Payment Plans API Reference [REST][NVP]
Payment plan constraints
You can limit the payment plan identifiers and deferral/installment months for a specific transaction using the payment plan constraint fields:
constraints.paymentPlans.numberOfDeferrals
: The allowable number of deferral months for the payment plan.constraints.paymentPlans.numberOfPayments
: The allowable number of installments for the payment plan.constraints.paymentPlans.supported[n]
: Provide identifiers for the payment plans supported on this transaction. If you do not wish to offer any payment plans, pass it as empty.
From the version 70 onwards,
constraints.paymentPlans.deferralPeriod
: The allowable number of deferral months for the payment plan.constraints.paymentPlans.numberOfPayments
: The allowable number of installments for the payment plan.constraints.paymentPlans.supported[n]
: Provide identifiers for the payment plans supported on this transaction. If you do not wish to offer any payment plans, pass it as empty.