BNPL and Flexible Installments
Overview of installment plans
info
You must create a purchase credit plan before creating an installment credit plan.
Installment credit plans let you offer your account holders the ability to spread their payments on a transaction over a set number of installments. They are post-purchase Buy Now Pay Later offerings that let account holders convert a cleared transaction from their regular revolving credit plan into a fixed installment plan.
As such, Highnote installment credit plans are attached to an existing credit card product and require that you first create a standard PURCHASE credit plan before creating an INSTALLMENT credit plan.
To begin offering BNPL installment payment plans on your card product,
- Create and and activate a purchase credit plan.
- Create and activate an installment credit plan with a fee schedule.
- Per eligible and cleared transaction, create and activate an installment agreement.
View installment credit plan templates
Credit plans are created from credit plan templates.
Use the following query to view credit plan templates available for your card product. This query includes an optional filter by balanceType of INSTALLMENT.
GetCardProductWithCreditPlanTemplates
Query
query GetCardProductWithCreditPlanTemplates(
$id: ID!
$filterBy: CreditPlanTemplateFilterInput
) {
node(id: $id) {
... on CardProduct {
__typename
id
creditPlanTemplates(first: 20, filterBy: $filterBy) {
edges {
node {
__typename
id
name
status
planType
balanceType
maximumCreditLimit {
value
currencyCode
}
installmentPolicy {
numberOfPeriodsRange {
minimumInclusive
maximumInclusive
}
principalAmountRange {
minimumInclusive {
value
currencyCode
}
maximumInclusive {
value
currencyCode
}
}
}
createdAt
updatedAt
}
}
}
}
}
}
Variables
{
"id": "CARD_PRODUCT_ID",
"filterBy": {
"balanceType": "INSTALLMENT"
}
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "CardProduct",
"id": "pd_ed7bb4e376964c54a89e870cbbf234e2",
"creditPlanTemplates": {
"edges": [
{
"node": {
"__typename": "CreditPlanTemplate",
"id": "crppt_fd26dcd03f494280aced06860c519c39",
"name": "REVOLVING_STANDARD_INSTALLMENT_ZERO_APR_NO_INTEREST",
"status": "ACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"maximumCreditLimit": {
"value": 10000,
"currencyCode": "USD"
},
"installmentPolicy": {
"numberOfPeriodsRange": {
"minimumInclusive": 2,
"maximumInclusive": 12
},
"principalAmountRange": {
"minimumInclusive": {
"value": 100,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 100000,
"currencyCode": "USD"
}
}
},
"createdAt": "2025-01-01T00:00:00.000Z",
"updatedAt": "2025-01-01T00:00:00.000Z"
}
}
]
}
}
},
"extensions": {
"requestId": "e86cea7c-fbfc-9177-8bf5-b0fa04e51050",
"rateLimit": {
"cost": 123,
"limit": 60060,
"remaining": 59937
}
}
}
Create installment credit plan
info
Once created, you cannot modify a credit plan. This prevents an unauthorized change in terms from occurring on any financial accounts.
From a credit plan template, you can create an installment credit plan and define the minimum and maximum transaction purchase amount allowed on the plan. The allowed transaction amount must fall within the minimum and maximum range defined on the template.
Installment fees are based on a percentage of the transaction purchase amount, or a fixed amount. Optionally, you can attach an installment fee schedule when creating the installment plan, by either
a. providing it as an input to this mutation when creating the plan, or b. attaching it after the plan is created as shown in the Attach a credit plan fee.
Use the following mutation in your Test environment to create an installment credit plan:
CreateCardProductInstallmentCreditPlan
Query
mutation createCardProductInstallmentCreditPlan(
$input: CreateCardProductInstallmentCreditPlanInput!
) {
createCardProductInstallmentCreditPlan(input: $input) {
__typename
... on CreditPlan {
id
name
status
planType
balanceType
riskBasedPricingPolicy {
isRiskBased
}
percentageOfCreditLimit
installmentPolicy {
numberOfPeriods
principalAmountRange {
minimumInclusive {
value
currencyCode
}
maximumInclusive {
value
currencyCode
}
}
}
feeSchedule {
id
feeConfigurations {
feeActivityType
feeChargeRules {
value {
__typename
... on FixedFeeChargeValue {
amount {
value
currencyCode
}
}
... on VariableFeeChargeValue {
basisPoints
}
}
}
}
}
effectiveFromDate
effectiveThroughDate
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "name": "some-installment-credit-plan", "creditPlanTemplateId": "CREDIT_PLAN_TEMPLATE_ID", "productId": "CARD_PRODUCT_ID", "minimumPrincipalAmount": { "value": "10000", "currencyCode": "USD" }, "maximumPrincipalAmount": { "value": "10000000", "currencyCode": "USD" }, "numberOfInstallmentPeriods": "3", "fee": { "scheduleId": "fxsch_1234" } } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"createCardProductInstallmentCreditPlan": {
"__typename": "CreditPlan",
"id": "crppn_552a8e25a77f4eee862a8f4e1703e95a",
"name": "credit-plan-standard-installment-none",
"status": "INACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"riskBasedPricingPolicy": {
"isRiskBased": false
},
"percentageOfCreditLimit": 100,
"installmentPolicy": {
"numberOfPeriods": 6,
"principalAmountRange": {
"minimumInclusive": {
"value": 100,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 100000,
"currencyCode": "USD"
}
}
},
"feeSchedule": {
"id": "fxsch_223a1fa9ff0ef948219f2c6708e6b2a330",
"feeConfigurations": [
{
"feeActivityType": "INSTALLMENT_FEE",
"feeChargeRules": [
{
"value": {
"__typename": "FixedFeeChargeValue",
"amount": {
"value": 1000,
"currencyCode": "USD"
}
}
}
]
}
]
},
"effectiveFromDate": null,
"effectiveThroughDate": null,
"createdAt": "2025-02-26T17:55:57.628Z",
"updatedAt": "2025-02-26T17:55:57.648Z"
}
},
"extensions": {
"requestId": "a5fc9edf-7eb2-963e-9a15-8e8c86ed372e",
"rateLimit": {
"cost": 20,
"limit": 60060,
"remaining": 60040
}
}
}
Create fee schedule for installment credit plan
You can create fees for installment credit plans and assess a percentage of the cleared transaction amount. If you have multiple installment credit plans, they can share the same fee schedule or have different fee schedules.
For more information on creating fees, see the Fees guide.
The Highnote team will configure and activate fee schedules in your Live environment, but you can simulate creating fee schedules in your Test environment using the following mutation:
simulateCreateAndActivateFeeSchedule
Query
mutation simulateCreateAndActivateFeeSchedule(
$input: SimulateCreateAndActivateFeeScheduleInput!
) {
simulateCreateAndActivateFeeSchedule(input: $input) {
__typename
... on UserError {
errors {
errorPath
code
description
}
}
... on FeeSchedule {
__typename
id
feeScheduleAssociatedTo {
__typename
... on CardProduct {
id
}
}
feeConfigurations {
id
feeActivityType
feeChargeRules {
id
name
order
value {
__typename
... on FixedFeeChargeValue {
amount {
value
currencyCode
}
}
}
conditions {
__typename
... on FeeChargeRuleAmountCondition {
id
description
condition {
__typename
... on AmountFeeCondition {
value {
__typename
... on AmountFeeConditionValue {
amount {
value
currencyCode
}
maximumAmount {
value
currencyCode
}
}
}
operator
}
}
aggregatedAt
aggregationDuration
createdAt
updatedAt
}
... on FeeChargeRuleCountCondition {
id
description
condition {
__typename
... on CountFeeCondition {
value {
__typename
... on CountFeeConditionValue {
count
}
}
operator
}
}
aggregatedAt
aggregationDuration
createdAt
updatedAt
}
... on FeeChargeRuleAmountCondition {
id
description
condition {
__typename
... on AmountFeeCondition {
value {
__typename
... on AmountFeeConditionValue {
amount {
value
currencyCode
}
}
}
operator
}
}
aggregatedAt
aggregationDuration
createdAt
updatedAt
}
}
createdAt
updatedAt
}
createdAt
updatedAt
}
activationDate
status
createdAt
updatedAt
}
}
}
Variables
{ "input": { "cardProductId": "CARD_PRODUCT_ID", "feeConfigurations": [ { "feeActivityType": "INSTALLMENT_FEE", "feeAmount": { "feeAmount": { "value": 1000, "currencyCode": "USD" } } } ] } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"simulateCreateAndActivateFeeSchedule": {
"__typename": "FeeSchedule",
"id": "fxsch_223a1fa9ff0ef948219f2c6708e6b2a330",
"feeScheduleAssociatedTo": {
"__typename": "CardProduct",
"id": "pd_ed7bb4e376964c54a89e870cbbf234e2"
},
"feeConfigurations": [
{
"id": "fxcfg_5730dd48b0ef4bc39467d56ee362377b",
"feeActivityType": "INSTALLMENT_FEE",
"feeChargeRules": [
{
"id": "fxcfa_0dd2afa82fac41d88ecf2ce761b787e4",
"name": "Priority_10_CREDIT_INSTALLMENT_FEE",
"order": 10,
"value": {
"__typename": "FixedFeeChargeValue",
"amount": {
"value": 1000,
"currencyCode": "USD"
}
},
"conditions": [
{
"__typename": "FeeChargeRuleCountCondition",
"id": "fxvcd_6559335acc2140c7ad3197dc9061bd8b",
"description": "COUNT GREATER THAN OR EQUAL TO 1 CONDITION SET",
"condition": {
"__typename": "CountFeeCondition",
"value": {
"__typename": "CountFeeConditionValue",
"count": 1
},
"operator": "GREATER_THAN_OR_EQUAL"
},
"aggregatedAt": "ACCOUNT",
"aggregationDuration": "LIFETIME",
"createdAt": "2025-02-26T17:44:02.062Z",
"updatedAt": "2025-02-26T17:44:02.062Z"
}
],
"createdAt": "2025-02-26T17:44:02.063Z",
"updatedAt": "2025-02-26T17:44:02.063Z"
}
],
"createdAt": "2025-02-26T17:44:02.062Z",
"updatedAt": "2025-02-26T17:44:02.062Z"
}
],
"activationDate": "2025-02-26T17:44:01.888Z",
"status": "ACTIVE",
"createdAt": "2025-02-26T17:44:01.937Z",
"updatedAt": "2025-02-26T17:44:02.142Z"
}
},
"extensions": {
"requestId": "562a646f-ef80-9e79-b8b9-9e6ae7a36330",
"rateLimit": {
"cost": 23,
"limit": 60060,
"remaining": 60037
}
}
}
Attach fee schedule to installment credit plan
You can attach the fee schedule to the credit plan if you didn't attach a fee schedule when creating the credit plan. Only installment credit plans can have an attached fee schedule with a feeActivityType set to INSTALLMENT_FEE.
attachFeeToCreditPlan
Query
mutation attachFeeToCreditPlan($input: AttachFeeToCreditPlanInput!) {
attachFeeToCreditPlan(input: $input) {
__typename
... on CreditPlan {
__typename
id
name
status
planType
balanceType
percentageOfCreditLimit
installmentPolicy {
__typename
principalAmountRange {
__typename
minimumInclusive {
__typename
value
}
maximumInclusive {
__typename
value
}
}
numberOfPeriods
}
feeSchedule {
__typename
id
activationDate
createdAt
status
updatedAt
feeScheduleAssociatedTo {
__typename
... on CardProduct {
id
name
usage
vertical
features {
enabled
__typename
}
accounts {
edges {
node {
__typename
id
name
features {
enabled
__typename
}
activeBillingCycleConfiguration {
billingCycleStartDayOfMonth
paymentDueDayOfMonth
billingCycleStartDayOfMonth
}
}
}
}
creditPlans {
edges {
node {
__typename
id
name
status
planType
balanceType
riskBasedPricingPolicy {
__typename
isRiskBased
}
percentageOfCreditLimit
effectiveFromDate
effectiveThroughDate
interestPolicy {
__typename
rateType
accrualType
accrualMethod
assessmentSchedule
defaultApr
scraApr
}
createdAt
updatedAt
}
}
}
creditConfiguration {
__typename
interest {
__typename
includesPurchase
includesFees
}
repayment {
__typename
repaymentWaterfall
}
minimumPayment {
__typename
thresholdAmount {
__typename
value
currencyCode
}
includesFeesCharged
includesPastDueAmount
includesInterestAmount
}
}
}
}
feeConfigurations {
id
__typename
feeChargeRules {
id
name
order
value {
__typename
... on FixedFeeChargeValue {
__typename
amount {
value
}
}
... on VariableFeeChargeValue {
basisPoints
__typename
}
}
__typename
conditions {
... on FeeChargeRuleCountCondition {
__typename
createdAt
id
description
condition {
__typename
operator
value {
__typename
count
maximumCount
}
}
}
... on FeeChargeRuleAmountCondition {
__typename
description
createdAt
condition {
__typename
operator
value {
amount {
value
}
maximumAmount {
value
}
__typename
}
}
}
}
}
}
}
effectiveFromDate
effectiveThroughDate
createdAt
updatedAt
}
... on UserError {
errors {
description
code
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "creditPlanId": "crppn_7d5260aeaaaa4620bd55f59808f6a238", "fee": { "scheduleId": "fxsch_22a3ef6960b5144b9997efe43072c1f9a1" } } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"attachFeeToCreditPlan": {
"__typename": "CreditPlan",
"id": "crppn_5cb6c6b09d164354b5340adde4c20f56",
"name": "credit-plan-standard-installment-none",
"status": "INACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"percentageOfCreditLimit": 100,
"installmentPolicy": {
"__typename": "CreditPlanInstallmentPolicy",
"principalAmountRange": {
"__typename": "AmountRange",
"minimumInclusive": {
"__typename": "Amount",
"value": 100
},
"maximumInclusive": {
"__typename": "Amount",
"value": 100000
}
},
"numberOfPeriods": 6
},
"feeSchedule": {
"__typename": "FeeSchedule",
"id": "fxsch_223a1fa9ff0ef948219f2c6708e6b2a330",
"activationDate": "2025-02-26T17:44:01.888Z",
"createdAt": "2025-02-26T17:44:01.937Z",
"status": "ACTIVE",
"updatedAt": "2025-02-26T17:44:02.142Z",
"feeScheduleAssociatedTo": null,
"feeConfigurations": [
{
"id": "fxcfg_5730dd48b0ef4bc39467d56ee362377b",
"__typename": "FeeConfiguration",
"feeChargeRules": [
{
"id": "fxcfa_0dd2afa82fac41d88ecf2ce761b787e4",
"name": "Priority_10_CREDIT_INSTALLMENT_FEE",
"order": 10,
"value": {
"__typename": "FixedFeeChargeValue",
"amount": {
"value": 1000
}
},
"__typename": "FeeChargeRule",
"conditions": [
{
"__typename": "FeeChargeRuleCountCondition",
"createdAt": "2025-02-26T17:44:02.062Z",
"id": "fxvcd_6559335acc2140c7ad3197dc9061bd8b",
"description": "COUNT GREATER THAN OR EQUAL TO 1 CONDITION SET",
"condition": {
"__typename": "CountFeeCondition",
"operator": "GREATER_THAN_OR_EQUAL",
"value": {
"__typename": "CountFeeConditionValue",
"count": 1,
"maximumCount": null
}
}
}
]
}
]
}
]
},
"effectiveFromDate": null,
"effectiveThroughDate": null,
"createdAt": "2025-02-26T17:58:06.954Z",
"updatedAt": "2025-02-26T17:58:06.954Z"
}
},
"extensions": {
"requestId": "8401f11f-1b5a-917d-93bb-7674c1c70313",
"rateLimit": {
"cost": 75,
"limit": 60060,
"remaining": 59962
}
}
}
Activate installment credit plan
Note
You cannot have two active standard purchase credit plans at the same time.
After creating a credit plan for your card product, you must activate it for the rates and terms to apply to new financial accounts. When activating, you can optionally set an effective start and end date. If no values are provided for start and end date, the plan will be effective upon activation and utilized until a new credit plan with the same balance type is activated on your card product.
You can have multiple, active installment credit plans on your card product; but you cannot have two active standard purchase credit plans at the same time. A new credit plan can be activated and applied to newly issued financial accounts. If you have multiple credit plans, the account holder’s application date determines which credit plan to apply to the issued financial account based on the credit plan’s effective dates.
Use the following mutation to activate a credit plan in your Test environment:
ActivateCardProductCreditPlan
Query
mutation ActivateCardProductCreditPlan(
$input: ActivateCardProductCreditPlanInput!
) {
activateCardProductCreditPlan(input: $input) {
__typename
... on CreditPlan {
id
name
status
planType
balanceType
riskBasedPricingPolicy {
isRiskBased
}
percentageOfCreditLimit
installmentPolicy {
numberOfPeriods
principalAmountRange {
minimumInclusive {
value
currencyCode
}
maximumInclusive {
value
currencyCode
}
}
}
feeSchedule {
id
feeConfigurations {
feeActivityType
feeChargeRules {
value {
__typename
... on FixedFeeChargeValue {
amount {
value
currencyCode
}
}
... on VariableFeeChargeValue {
basisPoints
}
}
}
}
}
effectiveFromDate
effectiveThroughDate
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "id": "CREDIT_PLAN_ID", "effectiveFromDate": "2023-10-12", "effectiveThroughDate": "2024-10-12" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"activateCardProductCreditPlan": {
"__typename": "CreditPlan",
"id": "crppn_5cb6c6b09d164354b5340adde4c20f56",
"name": "credit-plan-standard-installment-none",
"status": "ACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"riskBasedPricingPolicy": {
"isRiskBased": false
},
"percentageOfCreditLimit": 100,
"interestPolicy": null,
"installmentPolicy": {
"numberOfPeriods": 6,
"principalAmountRange": {
"minimumInclusive": {
"value": 100,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 100000,
"currencyCode": "USD"
}
}
},
"feeSchedule": {
"id": "fxsch_223a1fa9ff0ef948219f2c6708e6b2a330",
"feeConfigurations": [
{
"feeActivityType": "INSTALLMENT_FEE",
"feeChargeRules": [
{
"value": {
"__typename": "FixedFeeChargeValue",
"amount": {
"value": 1000,
"currencyCode": "USD"
}
}
}
]
}
]
},
"effectiveFromDate": "2024-11-09",
"effectiveThroughDate": "2024-10-12",
"createdAt": "2025-02-26T18:59:36.015Z",
"updatedAt": "2025-02-26T18:59:36.015Z"
}
},
"extensions": {
"requestId": "54d7fc2a-aebb-9620-b61a-d6c2fe953a3f",
"rateLimit": {
"cost": 22,
"limit": 60060,
"remaining": 60038
}
}
}
View card product installment credit plans
GetCardProductWithCreditPlans
Query
query GetCardProductWithCreditPlans(
$id: ID!
$filterBy: CreditPlanFilterInput
) {
node(id: $id) {
... on CardProduct {
__typename
id
creditPlans(first: 20, filterBy: $filterBy) {
edges {
node {
__typename
id
name
status
planType
balanceType
percentageOfCreditLimit
installmentPolicy {
principalAmountRange {
minimumExclusive {
value
currencyCode
}
maximumExclusive {
value
currencyCode
}
}
numberOfPeriods
}
feeSchedule {
id
feeConfigurations {
feeActivityType
feeChargeRules {
value {
__typename
... on FixedFeeChargeValue {
amount {
value
currencyCode
}
}
... on VariableFeeChargeValue {
basisPoints
}
}
}
}
}
effectiveFromDate
effectiveThroughDate
createdAt
updatedAt
}
}
}
}
}
}
Variables
{
"id": "CARD_PRODUCT_ID",
"filterBy": {
"balanceType": "INSTALLMENT",
"status": "ACTIVE"
}
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "CardProduct",
"id": "pd_ed7bb4e376964c54a89e870cbbf234e2",
"creditPlans": {
"edges": [
{
"node": {
"__typename": "CreditPlan",
"id": "crppn_5cb6c6b09d164354b5340adde4c20f56",
"name": "credit-plan-standard-installment-none",
"status": "ACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"percentageOfCreditLimit": 100,
"installmentPolicy": {
"principalAmountRange": {
"minimumExclusive": {
"value": "10000",
"currencyCode": "USD"
},
"maximumExclusive": {
"value": "10000000",
"currencyCode": "USD"
}
},
"numberOfPeriods": 6
},
"feeSchedule": {
"id": "fxsch_223a1fa9ff0ef948219f2c6708e6b2a330",
"feeConfigurations": [
{
"feeActivityType": "INSTALLMENT_FEE",
"feeChargeRules": [
{
"value": {
"__typename": "FixedFeeChargeValue",
"amount": {
"value": 1000,
"currencyCode": "USD"
}
}
}
]
}
]
},
"effectiveFromDate": "2024-11-09",
"effectiveThroughDate": null,
"createdAt": "2025-02-26T18:59:36.015Z",
"updatedAt": "2025-02-26T18:59:36.015Z"
}
},
{
"node": {
"__typename": "CreditPlan",
"id": "crppn_55ba163b3f654a788bdbfd0cde9248f8",
"name": "standard-installment-credit-plan-zero-apr-9-period",
"status": "ACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"percentageOfCreditLimit": 100,
"installmentPolicy": {
"principalAmountRange": {
"minimumExclusive": {
"value": "10000",
"currencyCode": "USD"
},
"maximumExclusive": {
"value": "10000000",
"currencyCode": "USD"
}
},
"numberOfPeriods": 9
},
"feeSchedule": null,
"effectiveFromDate": "2024-11-09",
"effectiveThroughDate": null,
"createdAt": "2025-02-20T04:54:32.673Z",
"updatedAt": "2025-02-20T04:54:32.674Z"
}
}
]
}
}
},
"extensions": {
"requestId": "a3807e5f-3e3f-968d-a657-ca5e662d1c18",
"rateLimit": {
"cost": 183,
"limit": 60060,
"remaining": 59877
}
}
}
Overview of installment agreements
After creating an installment plan, you can begin creating installment agreements per transaction. Installment plans can only be offered on cleared transactions. And you must activate the installment agreement to apply the plan’s payment terms on the transaction.
View installment eligibility for transaction events
You can look up whether a group of transaction events is eligible for installments without our system actually calculating the potential offers.
installmentEligibilityForTransactionEvents
Query
query installmentEligibilityForTransactionEvents(
$input: InstallmentEligibilityForTransactionEventsInput!
) {
installmentEligibilityForTransactionEvents(input: $input) {
__typename
... on InstallmentEligibilityForTransactionEvents {
eligibilityByTransactionEvent {
transactionEvent {
__typename
id
}
eligibility
}
}
... on UserError {
errors {
code
description
}
}
}
}
Variables
{
"input": {
"cardTransactionEventIds": [
"te_1234",
"te_5678"
]
}
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"installmentEligibilityForTransactionEvents": {
"eligibilityByTransactionEvent": [
{
"transactionEvent": {
"__typename": "AuthorizationAndClearEvent",
"id": "te_1234"
},
"eligibility": "ELIGIBLE"
},
{
"transactionEvent": {
"__typename": "ClearingEvent",
"id": "te_5678"
},
"eligibility": "NOT_ELIGIBLE"
}
]
}
}
}
View installment offers by transaction
You can view which installment credit plans qualify for a given transaction. The credit plans will provide details on the payment amount, fees, and total cost based on the plan's settings and transaction amount.
Installment plans can only be offered on cleared transactions and the purchase amount must be within the min and max range defined on the credit plan.
Use the following query to lookup qualifying installment credit plans offers with a cleared transaction event ID.
installmentOffersForTransactionEvent
Query
query installmentOffersForTransactionEvent(
$input: InstallmentOffersForTransactionEventInput!
) {
installmentOffersForTransactionEvent(input: $input) {
__typename
... on InstallmentOffersForTransactionEvent {
transactionEvent {
__typename
id
approvedAmount {
value
currencyCode
}
createdAt
}
offers {
creditPlan {
id
installmentPolicy {
__typename
principalAmountRange {
minimumInclusive {
value
currencyCode
}
maximumInclusive {
value
currencyCode
}
}
numberOfPeriods
}
feeSchedule {
id
feeConfigurations {
feeActivityType
feeChargeRules {
value {
__typename
... on FixedFeeChargeValue {
amount {
value
currencyCode
}
}
... on VariableFeeChargeValue {
basisPoints
}
}
}
}
}
}
details {
totalCost {
value
currencyCode
}
totalPrincipal {
value
currencyCode
}
totalFees {
value
currencyCode
}
principalDuePerPeriod {
value
currencyCode
}
feesChargedPerPeriod {
value
currencyCode
}
}
}
}
... on UserError {
errors {
code
description
}
}
}
}
Variables
{
"input": {
"cardTransactionEventId": "te_23wpgf4xk41aa5k3971ak93eseb1sb6mt3"
}
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"installmentOffersForTransactionEvent": {
"__typename": "InstallmentOffersForTransactionEvent",
"transactionEvent": {
"__typename": "ClearingEvent",
"id": "te_23iuh1n577ivu5sf5i4swrdhnbd1saau14",
"approvedAmount": {
"value": 40000,
"currencyCode": "USD"
},
"createdAt": "2024-11-01T16:39:46.442Z"
},
"offers": [
{
"creditPlan": {
"id": "crppn_0ce389daf2af4ebeacbd0764c2ce9140",
"installmentPolicy": {
"__typename": "CreditPlanInstallmentPolicy",
"principalAmountRange": {
"minimumInclusive": {
"value": 10000,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 50000,
"currencyCode": "USD"
}
},
"numberOfPeriods": 9
},
"feeSchedule": null
},
"details": {
"totalCost": {
"value": 40000,
"currencyCode": "USD"
},
"totalPrincipal": {
"value": 40000,
"currencyCode": "USD"
},
"totalFees": {
"value": 0,
"currencyCode": "USD"
},
"principalDuePerPeriod": {
"value": 4445,
"currencyCode": "USD"
},
"feesChargedPerPeriod": {
"value": 0,
"currencyCode": "USD"
}
}
},
{
"creditPlan": {
"id": "crppn_e1f3d99a1164470faabcba810cc9f62b",
"installmentPolicy": {
"__typename": "CreditPlanInstallmentPolicy",
"principalAmountRange": {
"minimumInclusive": {
"value": 10000,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 1000000,
"currencyCode": "USD"
}
},
"numberOfPeriods": 6
},
"feeSchedule": null
},
"details": {
"totalCost": {
"value": 40000,
"currencyCode": "USD"
},
"totalPrincipal": {
"value": 40000,
"currencyCode": "USD"
},
"totalFees": {
"value": 0,
"currencyCode": "USD"
},
"principalDuePerPeriod": {
"value": 6667,
"currencyCode": "USD"
},
"feesChargedPerPeriod": {
"value": 0,
"currencyCode": "USD"
}
}
},
{
"creditPlan": {
"id": "crppn_537b57a18170434c9bbda3dd9353f07f",
"installmentPolicy": {
"__typename": "CreditPlanInstallmentPolicy",
"principalAmountRange": {
"minimumInclusive": {
"value": 10000,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 2000000,
"currencyCode": "USD"
}
},
"numberOfPeriods": 3
},
"feeSchedule": null
},
"details": {
"totalCost": {
"value": 40000,
"currencyCode": "USD"
},
"totalPrincipal": {
"value": 40000,
"currencyCode": "USD"
},
"totalFees": {
"value": 0,
"currencyCode": "USD"
},
"principalDuePerPeriod": {
"value": 13334,
"currencyCode": "USD"
},
"feesChargedPerPeriod": {
"value": 0,
"currencyCode": "USD"
}
}
}
]
}
},
"extensions": {
"requestId": "105e4525-249c-964d-8216-20a5b801e098",
"rateLimit": {
"cost": 20,
"limit": 60060,
"remaining": 60040
}
}
}
Activate installment agreement for transaction
Once you or your account holder has selected an installment plan, you can activate an agreement to apply the installment plan payment terms on the transaction.
Use the following mutation to create an installment agreement for a cleared transaction event:
activateInstallmentAgreementForTransactionEvent
Query
mutation activateInstallmentAgreementForTransactionEvent(
$input: ActivateInstallmentAgreementForTransactionEventInput!
) {
activateInstallmentAgreementForTransactionEvent(input: $input) {
__typename
... on InstallmentAgreement {
id
status
agreement {
creditPlan {
id
installmentPolicy {
principalAmountRange {
minimumInclusive {
value
currencyCode
}
maximumInclusive {
value
currencyCode
}
}
numberOfPeriods
}
}
details {
totalCost {
value
currencyCode
}
totalPrincipal {
value
currencyCode
}
totalFees {
value
currencyCode
}
principalDuePerPeriod {
value
currencyCode
}
feesChargedPerPeriod {
value
currencyCode
}
}
}
transactionEvent {
id
}
snapshot {
asOf
installmentPaymentsCompleted {
principalBalancePaid {
value
currencyCode
}
feesPaid {
value
currencyCode
}
numberOfInstallmentsCompleted
}
installmentPaymentsRemaining {
principalBalanceRemaining {
value
currencyCode
}
estimatedFeesRemaining {
value
currencyCode
}
numberOfInstallmentsRemaining
}
}
installmentAgreementPeriodStart
createdAt
updatedAt
}
... on UserError {
errors {
description
code
}
}
}
}
Variables
{ "input": { "creditPlanId": "crppn_1234", "cardTransactionEventId": "te_1234" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"activateInstallmentAgreementForTransactionEvent": {
"__typename": "InstallmentAgreement",
"id": "crins_89800bdcb5354fc891d5e4bb666c57d5",
"status": "OPEN",
"agreement": {
"creditPlan": {
"id": "crppn_537b57a18170434c9bbda3dd9353f07f",
"installmentPolicy": {
"principalAmountRange": {
"minimumInclusive": {
"value": 10000,
"currencyCode": "USD"
},
"maximumInclusive": {
"value": 2000000,
"currencyCode": "USD"
}
},
"numberOfPeriods": 3
}
},
"details": {
"totalCost": {
"value": 0,
"currencyCode": "USD"
},
"totalPrincipal": {
"value": 40000,
"currencyCode": "USD"
},
"totalFees": {
"value": 0,
"currencyCode": "USD"
},
"principalDuePerPeriod": {
"value": 13334,
"currencyCode": "USD"
},
"feesChargedPerPeriod": {
"value": 0,
"currencyCode": "USD"
}
}
},
"transactionEvent": {
"id": "te_23iuh1n577ivu5sf5i4swrdhnbd1saau14"
},
"snapshot": {
"asOf": "2025-02-26T19:17:43.659Z",
"installmentPaymentsCompleted": {
"principalBalancePaid": {
"value": 0,
"currencyCode": "USD"
},
"feesPaid": {
"value": 0,
"currencyCode": "USD"
},
"numberOfInstallmentsCompleted": null
},
"installmentPaymentsRemaining": {
"principalBalanceRemaining": {
"value": 40000,
"currencyCode": "USD"
},
"estimatedFeesRemaining": {
"value": 0,
"currencyCode": "USD"
},
"numberOfInstallmentsRemaining": 3
}
},
"installmentAgreementPeriodStart": "2025-02-26T19:17:43.536Z",
"createdAt": "2025-02-26T19:17:43.536Z",
"updatedAt": "2025-02-26T19:17:43.659Z"
}
},
"extensions": {
"requestId": "66fb12da-1d1c-9c5a-bb35-845e254c02a0",
"rateLimit": {
"cost": 30,
"limit": 60060,
"remaining": 60028
}
}
}
View installment agreement by financial account
You can view a paginated list of installment agreements related to a financial account using the following query:
GetFinancialAccountWithInstallmentAgreements
Query
query GetFinancialAccountWithInstallmentAgreements(
$id: ID!
$filterBy: InstallmentAgreementFilterInput
) {
node(id: $id) {
... on FinancialAccount {
__typename
id
installmentAgreements(first: 20, filterBy: $filterBy) {
__typename
pageInfo {
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
__typename
... on InstallmentAgreement {
id
installmentAgreementPeriodStart
status
agreement {
creditPlan {
__typename
id
}
details {
principalDuePerPeriod {
value
currencyCode
}
}
}
snapshot {
__typename
asOf
installmentPaymentsCompleted {
principalBalancePaid {
value
currencyCode
}
feesPaid {
value
currencyCode
}
numberOfInstallmentsCompleted
}
installmentPaymentsRemaining {
principalBalanceRemaining {
value
currencyCode
}
estimatedFeesRemaining {
value
currencyCode
}
numberOfInstallmentsRemaining
}
}
transactionEvent {
__typename
... on ClearingEvent {
approvedAmount {
value
currencyCode
}
}
}
statusHistory {
__typename
newStatus
previousStatus
}
createdAt
updatedAt
}
}
}
}
}
}
}
Variables
{
"id": "FINANCIAL_ACCOUNT_ID",
"filterBy": {
"installmentAgreementStatus": "OPEN",
"transactionEventIds": [
"te_123",
"te_456"
]
}
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "FinancialAccount",
"id": "ac_c02278b93bec40dc44c8bca1480ebf48f347",
"installmentAgreements": {
"__typename": "InstallmentAgreementConnection",
"pageInfo": {
"hasNextPage": false,
"hasPreviousPage": false
},
"edges": [
{
"cursor": "dD0yMDI1LTAyLTIwVDA0JTNBNTclM0E0OS45NDMwMDAwMDBaJmk9Y3JpbnNfNjMyNmQyZDFkZjVhNGE3MGI4MzIwMmZkMmYwMzQzN2Y",
"node": {
"__typename": "InstallmentAgreement",
"id": "crins_6326d2d1df5a4a70b83202fd2f03437f",
"installmentAgreementPeriodStart": "2025-02-20T04:57:49.943Z",
"status": "OPEN",
"agreement": {
"creditPlan": {
"__typename": "CreditPlan",
"id": "crppn_55ba163b3f654a788bdbfd0cde9248f8"
},
"details": {
"principalDuePerPeriod": {
"value": 112,
"currencyCode": "USD"
}
}
},
"snapshot": {
"__typename": "InstallmentAgreementSnapshot",
"asOf": "2025-02-20T04:57:49.977Z",
"installmentPaymentsCompleted": {
"principalBalancePaid": {
"value": 0,
"currencyCode": "USD"
},
"feesPaid": {
"value": 0,
"currencyCode": "USD"
},
"numberOfInstallmentsCompleted": null
},
"installmentPaymentsRemaining": {
"principalBalanceRemaining": {
"value": 1000,
"currencyCode": "USD"
},
"estimatedFeesRemaining": {
"value": 0,
"currencyCode": "USD"
},
"numberOfInstallmentsRemaining": 9
}
},
"transactionEvent": {
"__typename": "ClearingEvent",
"id": "te_123",
"approvedAmount": {
"value": 1000,
"currencyCode": "USD"
}
},
"statusHistory": null,
"createdAt": "2025-02-20T04:57:49.943Z",
"updatedAt": "2025-02-20T04:57:49.977Z"
}
}
]
}
}
},
"extensions": {
"requestId": "eb41af15-bb67-9f7c-a4d1-11652e686f99",
"rateLimit": {
"cost": 283,
"limit": 60060,
"remaining": 59777
}
}
}
View installment agreement
Use the following query to view an installment agreement. The snapshot field includes a rollup of payments made and remaining, broken out by principal and fees.
nodeInstallmentAgreement
Query
query nodeInstallmentAgreement($id: ID!) {
node(id: $id) {
__typename
... on InstallmentAgreement {
id
installmentAgreementPeriodStart
status
agreement {
creditPlan {
__typename
id
name
status
planType
balanceType
riskBasedPricingPolicy {
isRiskBased
}
percentageOfCreditLimit
effectiveFromDate
effectiveThroughDate
feeSchedule {
id
feeConfigurations {
feeActivityType
feeChargeRules {
value {
__typename
... on FixedFeeChargeValue {
amount {
value
currencyCode
}
}
... on VariableFeeChargeValue {
basisPoints
}
}
}
}
}
createdAt
updatedAt
}
details {
principalDuePerPeriod {
value
currencyCode
}
feesChargedPerPeriod {
value
currencyCode
}
totalCost {
value
currencyCode
}
totalFees {
value
currencyCode
}
totalPrincipal {
value
currencyCode
}
}
}
snapshot {
asOf
installmentPaymentsCompleted {
principalBalancePaid {
value
currencyCode
}
feesPaid {
value
currencyCode
}
numberOfInstallmentsCompleted
}
installmentPaymentsRemaining {
principalBalanceRemaining {
value
currencyCode
}
estimatedFeesRemaining {
value
currencyCode
}
numberOfInstallmentsRemaining
}
__typename
}
transactionEvent {
__typename
... on ClearingEvent {
id
approvedAmount {
value
currencyCode
}
}
}
createdAt
updatedAt
}
}
}
Variables
{
"id": "INSTALLMENT_AGREEMENT_ID"
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "InstallmentAgreement",
"id": "crins_6326d2d1df5a4a70b83202fd2f03437f",
"installmentAgreementPeriodStart": "2025-02-20T04:57:49.943Z",
"status": "OPEN",
"agreement": {
"creditPlan": {
"__typename": "CreditPlan",
"id": "crppn_55ba163b3f654a788bdbfd0cde9248f8",
"name": "standard-installment-credit-plan-zero-apr-9-period",
"status": "ACTIVE",
"planType": "STANDARD",
"balanceType": "INSTALLMENT",
"riskBasedPricingPolicy": {
"isRiskBased": false
},
"percentageOfCreditLimit": 100,
"effectiveFromDate": "2024-11-09",
"effectiveThroughDate": null,
"feeSchedule": null,
"createdAt": "2025-02-20T04:54:32.673Z",
"updatedAt": "2025-02-20T04:54:32.674Z"
},
"details": {
"principalDuePerPeriod": {
"value": 112,
"currencyCode": "USD"
},
"feesChargedPerPeriod": {
"value": 0,
"currencyCode": "USD"
},
"totalCost": {
"value": 1000,
"currencyCode": "USD"
},
"totalFees": {
"value": 0,
"currencyCode": "USD"
},
"totalPrincipal": {
"value": 1000,
"currencyCode": "USD"
}
}
},
"snapshot": {
"asOf": "2025-02-20T04:57:49.977Z",
"installmentPaymentsCompleted": {
"principalBalancePaid": {
"value": 0,
"currencyCode": "USD"
},
"feesPaid": {
"value": 0,
"currencyCode": "USD"
},
"numberOfInstallmentsCompleted": null
},
"installmentPaymentsRemaining": {
"principalBalanceRemaining": {
"value": 1000,
"currencyCode": "USD"
},
"estimatedFeesRemaining": {
"value": 0,
"currencyCode": "USD"
},
"numberOfInstallmentsRemaining": 9
},
"__typename": "InstallmentAgreementSnapshot"
},
"transactionEvent": {
"__typename": "ClearingEvent",
"id": "te_232p8f8g5w3ej84ent33h8bweui1sb6ohk",
"approvedAmount": {
"value": 1000,
"currencyCode": "USD"
}
},
"createdAt": "2025-02-20T04:57:49.943Z",
"updatedAt": "2025-02-20T04:57:49.977Z"
}
},
"extensions": {
"requestId": "14f78d79-c715-99e4-a70c-8eba714a53ef",
"rateLimit": {
"cost": 24,
"limit": 60060,
"remaining": 60036
}
}
}