Skip to main content

Manage recurring programs

Managing a recurring program allows you to control the products or services that your consumer signs up for and how often they will be billed. It is a contract that ties a consumer to a recurring plan in order to bill them at a pre-defined frequency (i.e., billing cycle).

Before you begin

Learn about recurring programs and the features that Managed Recurring Payments API provides to help you customize as per your business requirement.

Create a recurring program

You can create a recurring program by sending a POST request to the /recurringprograms endpoint.

Keep in mind that if recurringPlanDefault = false, you must provide recurringProgramAmount in the request payload.

HTTP method: POST

Endpoint: /recurringprograms

Scenario: Create a recurring program for a new consumer whose consumerProfileId does not exist.

Json
{
    "consumerProfile": {
        "firstName": "John",
        "lastName": "Babbitt",
        "paymentMethodType": {
            "card": {
                "accountNumber": "4559961111111118",
                "cardExpirationMonthYearNumber": "02/2027",
                "firstName": "John",
                "lastName": "Babbitt",
                "billingAddress": {
                    "firstName": "John",
                    "lastName": "Babbitt",
                    "line1": "400 Elton Farm",
                    "line2": "Apt 123",
                    "city": "Springfield",
                    "state": "PA",
                    "postalCode": "19340",
                    "countryCode": "USA"
                }
            }
        }
    },
    "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_001",
    "recurringProgramName": "Your Recurring Program Text Label",
    "recurringProgramDescription": "Your Recurring Program Text Notes",
    "startDate": "2024-04-29T00:00:00.000Z",
    "endDate": "2024-11-29T00:00:00.000Z",
    "recurringProgramAutoRenewable": false,
    "planId": "vcTA8fn8Sl",
    "recurringPlanDefault": true,
    "communicationPreference": {
        "preferredEmail": "john.babbit@email.com",
        "preferredEmailOptin": true
    }
}

Response:

Json
{
    "recurringProgramId": "4e0MSigqux",
    "merchantId": "998482157633",
    "requestId": "11cc0270-7bed-11e9-a188-1763956dd7f6",
    "consumerProfile": {
        "consumerProfileId": "JPMCW-JCUCH7WW3WGSNGZP",
        "paymentMethodId": "0d63e3fb-1a9f-4a85-8696-03734dbc3451",
        "paymentMethodType": {
            "card": {
                "cardType": "CZ",
                "last4CardNumber": "1118",
                "first6CardNumber": "455996",
                "maskedAccountNumber": "455996XXXXXX1118",
                "originalNetworkTransactionId": "014120692163075",
                "billingAddress": {
                    "firstName": "John",
                    "lastName": "Babbitt",
                    "line1": "400 Elton Farm",
                    "line2": "Apt 123",
                    "city": "Springfield",
                    "state": "PA",
                    "postalCode": "19340",
                    "countryCode": "USA"
                }
            }
        }
    },
    "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_001",
    "recurringProgramName": "Your Recurring Program Text Label",
    "recurringProgramDescription": "Your Recurring Program Text Notes",
    "startDate": "2024-04-29",
    "endDate": "2024-11-29",
    "recurringProgramAutoRenewable": false,
    "planId": "vcTA8fn8Sl",
    "merchantPlanId": "YOUR_PLAN_ID_006",
    "planName": "Bronze Plan",
    "recurringPlanDefault": true,
    "recurringProgramQuantity": 1,
    "recurringProgramAmount": 1100,
    "currencyCode": "USD",
    "recurringProgramStatus": "ACTIVE",
    "communicationPreference": {
        "preferredPhoneOptIn": false,
        "preferredEmail": "john.babbit@email.com",
        "preferredEmailOptin": true
    },
    "paymentMethodTypeVerification": {
        "transactionId": "a6e636d3-e64a-43b5-a1c0-08b0879c3a0d",
        "transactionDate": "2024-04-29T15:47:37.341Z",
        "responseStatus": "SUCCESS",
        "approvalCode": "tst975",
        "hostMessage": "Transaction accepted"
    },
    "initialPaymentDetail": {
        "transactionId": "71eb287c-3655-4ffa-b8f0-c00738a64b2c",
        "transactionDate": "2024-04-29T15:47:37.944Z",
        "amount": 1100,
        "currencyCode": "USD",
        "responseStatus": "SUCCESS",
        "approvalCode": "tst976",
        "hostMessage": "Approved",
        "hostReferenceId": "uied6RE88E2CceLFOlDvd3"
    },
    "billingInformation": {
        "currentBillingCycleStartDate": "2024-04-29",
        "currentBillingCycleEndDate": "2024-05-28",
        "billingCyclesTotalCount": 8,
        "billingCyclesProcessedCount": 1,
        "billingCyclesPaymentSuccessCount": 1,
        "billingCyclesPaymentFailureCount": 0,
        "currencyCode": "USD",
        "pastDueAmount": 0,
        "creditAmount": 0
    }
}
Note

Account verification will be done on the payment method in all scenarios. The recurring program creation will fail if the account verification fails.

Update a recurring program

You can update recurring programs by sending a PATCH request to the /recurringprograms endpoint using the recurringProgramId.

Here's a list of scenarios in which you can update a particular field of a recurring program.

Scenarios for updating a recurring program
Field name Scenario description
startDate You can update the startDate only when the recurringProgramStatus is SCHEDULED.
endDate

You can update the endDate when the recurringProgramStatus is either in SCHEDULED, ACTIVE, or PAUSED.

However, you need to keep in mind that:

  • The end date can’t be less than the current billing cycle start date.
  • If the end date update occurs in the middle of the recently collected billing cycle and autoRenewal is false, then there is a pro-rated credit calculation.
  • The pro-rated credit will be automatically calculated and stored. You can use the stored pro-rated credit to issue a manual refund.
  • If the end date update occurs in the middle of the recently collected billing cycle and autoRenewal is true, then the end date update is not allowed.
  • If the end date update occurs before payment for the next billing cycle is collected, then it’s a case of prorated billing and only the pro-rated amount will be billed instead of the full cycle billing.  
  • If the end date update occurs on the billing cycle start date after the payment for the cycle is collected, then there is a full amount credit calculation.
  • The full credit will be automatically calculated and stored. It can be used to issue manual refunds.
planId You can update the planId only when the recurringProgramStatus is SCHEDULED.
consumerProfileId You can update the consumerProfileId only when the recurringProgramStatus is SCHEDULED.
paymentMethodId You can update the paymentMethodId to a new payment method or any other existing payment method from the consumer profile at anytime during the lifecycle of the recurring program. If it's a new payment method, Managed Recurring Payments will store it automatically in the consumer profile.

Account verification will be done in both scenarios and must be successful for the update to go through.
recurringProgramAmount You can update the program amount only when the recurringProgramstatus is SCHEDULED and the planDefault is set to false.

HTTP method: PATCH

Endpoint: /recurringprograms/{recurring-program-id]

Scenario: Update the recurring program with an existing payment method.

Json
{
    "consumerProfile": {
        "consumerProfileId": "JPMCW-JCUCH7WW3WGSNGZP",
        "paymentMethodType": {
            "card": {
                "accountNumber": "4112344112344113",
                "cardExpirationMonthYearNumber": "02/2027",
                "firstName": "John",
                "lastName": "Babbitt"
            }
        }
    }
}

Response:

Json
{
    "recurringProgramId": "9Yytu0mJGL",
    "merchantId": "998152096534",
    "requestId": "c680d873-8200-453c-98ff-b89f89cf7523",
    "consumerProfile": {
        "consumerProfileId": "JPMCW-JCUCH7WW3WGSNGZP",
        "paymentMethodId": "761bb568-d300-44a5-8a16-14a252104827",
        "paymentMethodType": {
            "card": {
                "cardType": "VI",
                "last4CardNumber": "4113",
                "first6CardNumber": "411234",
                "maskedAccountNumber": "411234XXXXXX4113",
                "originalNetworkTransactionId": "014120692163828"
            }
        }
    },
    "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_002",
    "recurringProgramName": "Your New Recurring Program Text Label",
    "recurringProgramDescription": "Your New Recurring Program Text Notes",
    "startDate": "2024-05-01",
    "endDate": "2025-05-30",
    "recurringProgramAutoRenewable": false,
    "planId": "MIqbKiSqGI",
    "merchantPlanId": "YOUR_PLAN_ID_004",
    "planName": "Every 3 week Plan",
    "recurringPlanDefault": true,
    "recurringProgramQuantity": 1,
    "recurringProgramAmount": 5000,
    "recurringProgramStatus": "SCHEDULED",
    "communicationPreference": {
        "preferredPhoneOptIn": false,
        "preferredEmail": "john.babbit@email.com",
        "preferredEmailOptin": true
    },
    "paymentMethodTypeVerification": {
        "transactionId": "2640931b-4221-43e1-abf2-b2d9b82fcfe1",
        "transactionDate": "2024-04-29T17:03:13.876Z",
        "responseStatus": "SUCCESS",
        "approvalCode": "tst915",
        "hostMessage": "Transaction accepted"
    },
    "billingInformation": {
        "billingCyclesTotalCount": 19,
        "billingCyclesProcessedCount": 0,
        "billingCyclesPaymentSuccessCount": 0,
        "billingCyclesPaymentFailureCount": 0,
        "currencyCode": "USD",
        "pastDueAmount": 0,
        "creditAmount": 0
    }
}

Cancel recurring programs

You can cancel a recurring program that is either in SCHEDULED, ACTIVE, or PAUSED status at anytime during the lifecycle by updating the recurringProgramStatus = CANCELLED. Cancellations are always effective immediately.

Note

Future dated cancellations are not supported.

However, end date adjustments can only be done in the following scenarios:

  • If the cancellation occurs on the cycle end date of the recently billed cycle, then there is no proration or credit calculation.
  • If the cancellation occurs in the middle of the recently collected billing cycle, then there is pro-rated credit calculation. The pro-rated credit will be automatically calculated and stored, and can be used to issue manual refunds.
  • If the cancellation occurs on the cycle start date after the payment for the cycle is collected, then there is a full amount credit calculation. The full credit will be automatically calculated and stored, and can be used to issue manual refunds back to the consumer.

Allowed status transitions

The program status can be updated to move from one to the other. However, this can only be done in certain scenarios. 

The following table that helps you identify the allowed status transitions.

Recurring program status transitions
recurringProgramStatus SCHEDULED ACTIVE CANCELLED EXPIRED PAUSED
SCHEDULED N/A Automatically assigned on the start date Allowed N/A N/A
ACTIVE Not allowed N/A Allowed Automatically assigned on term completion Allowed
CANCELLED Not allowed Not allowed N/A N/A N/A
EXPIRED N/A N/A N/A N/A N/A
PAUSED N/A Automatically assigned on the resume date Allowed N/A N/A

Fetch recurring programs

You can fetch a recurring program by sending a GET request to the /recurringprograms endpoint. 

Customize your fetch requests using the following filters:

  • recurringProgramId
  • planId
  • recurringProgramStatus
  • consumerProfileId

You can fetch recurring programs using the recurringProgramStatus as well:

  • ACTIVE
  • SCHEDULED
  • CANCELLED
  • EXPIRED
  • PAUSED
  • ALL

HTTP method: GET

Endpoint: /recurringprograms

Scenario: Fetch a recurring program by recurringProgramId.

Json
{
    "recurringPrograms": [
        {
            "recurringProgramId": "",
            "merchantId": "998152096533",
            "consumerProfile": {
                "consumerProfileId": "JPMCW-JCUCH7WW3WGSNGZP",
                "paymentMethodId": "0d63e3fb-1a9f-4a85-8696-03734dbc3451",
                "paymentMethodType": {
                    "card": {
                        "cardType": "CZ",
                        "last4CardNumber": "1118",
                        "first6CardNumber": "455996",
                        "maskedAccountNumber": "455996XXXXXX1118",
                        "originalNetworkTransactionId": "014120692163075"
                    }
                }
            },
            "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_001",
            "recurringProgramName": "Your Recurring Program Text Label",
            "recurringProgramDescription": "Your Recurring Program Text Notes",
            "startDate": "2024-04-29",
            "endDate": "2024-11-29",
            "recurringProgramAutoRenewable": false,
            "planId": "vcTA8fn8Sl",
            "merchantPlanId": "YOUR_PLAN_ID_006",
            "planName": "Bronze Plan",
            "recurringPlanDefault": true,
            "recurringProgramQuantity": 1,
            "recurringProgramAmount": 1100,
            "currencyCode": "USD",
            "recurringProgramStatus": "ACTIVE",
            "statusChangeDate": "2024-04-29T15:47:38.727139",
            "communicationPreference": {
                "preferredPhoneOptIn": false,
                "preferredEmail": "john.babbit@email.com",
                "preferredEmailOptin": true
            },
            "billingInformation": {
                "currentBillingCycleStartDate": "2024-04-29",
                "currentBillingCycleEndDate": "2024-05-28",
                "nextBillingCycleStartDate": "2024-05-29",
                "nextBillingCycleEndDate": "2024-06-28",
                "billingCyclesTotalCount": 8,
                "billingCyclesProcessedCount": 1,
                "billingCyclesPaymentSuccessCount": 1,
                "billingCyclesPaymentFailureCount": 0,
                "currencyCode": "USD",
                "pastDueAmount": 0,
                "creditAmount": 0
            },
            "pauseInformation": {
                "pauseRequestedDate": "2024-05-01T00:46:55.879718Z",
                "recurringProgramPauseStatusCode": "PAUSE_SCHEDULED",
                "pauseBillingCyclesTotalCount": 2,
                "pauseRemainingBillingCycles": 2,
                "pauseStartDate": "2024-05-29",
                "pauseEndDate": "2024-07-28"
            }
        }
    ]
}