Skip to main content

Recurring programs

A recurring program determines 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).

Each recurring program must be associated with a recurring plan to define a base price and billing frequency (MONTHLY, YEARLY, DAILY, etc.). Managed Recurring Payments (MRPS) enables you to setup recurring programs for your consumers and automatically bill them at fixed billing cycles. All the recurring payments are collected at the beginning of the cycle (i.e., pre-paid).

How it works

  1. Your consumer chooses the recurring plan they want.
  2. A recurring program for the consumer is created based on the recurring plan.
    1. If the consumer does not have a consumer profile, you can choose to: 
      1. Provide the consumer details when creating the recurring program. Managed Recurring Payments will create a new consumer profile and store in J.P. Morgan's Consumer Profile system.
      2. Create a consumer profile using J.P. Morgan's Consumer Profile Management.
    2. if the consumer has an existing consumer profile, provide the consumerProfileId and paymentMethodId to create the recurring program.
  3. If the recurring program starts immediately, the first payment request is sent to the provided payment method.
  4. If the recurring program starts in the future, the first payment will be sent on the provided start date.
  5. Payment requests are sent automatically on the billing date to the consumer to retrieve the recurring program amount.
  6. If you sign-up for Merchant Notifications and Consumer E-mail Notifications, Managed Recurring Payment services will communicate to you and to your consumers the status or each payment.
  7. Manage the billing cycles at any point during the recurring program life-cycle by retrieving the payment status information and performing manual payments or refunding for your consumers.
Note

EU/UK merchants must perform 3DS authentication to meet EU/UK Payment Services Directive 2 (PSD2) Strong Customer Authentication (SCA) requirements. Refer to 3-D Secure authentication to discover how to ensure your recurring programs are complying with SCA rules.

Tip

For information on how payments are calculated and how to manage them, refer to Recurring payments.

For information on how to manage billing cycles, refer to how to retrieve billing cycles and refund a billing cycle.

Features

The following features help you create and customize your recurring program. 

Recurring program features
Feature Description
Consumer profile

To create a recurring program, you must link it with a consumer profile. To help you with this, we provide you with the following features:

  • Consumer Profile: You can leverage the Consumer Profile Management API to store and retrieve consumer and payment information to set up a recurring program. There are two ways you can do this:
    • Set up a recurring program and create a consumer profile together.
    • Set up a recurring program using an existing consumer profile ID.
  • Payment Method: You need the payment method information from a consumer profile to set up a recurring program. There are two ways you can do this:
    • Use an existing payment method from the consumer profile.
    • Add a new payment method for the recurring payments. The newly added payment method will be added to the profile. Currently only Card Payments (credit and debit) are supported.
  • Consumer Communication: MRPS will send automatic consumer emails on your behalf. You can add new or leverage existing email information from the consumer profile.
Recurring program details

You have the flexibility to manage the duration of a recurring program.

  • Start Date: A recurring program can start immediately or at a future date.
  • End Date: A recurring program can have an end date or it can run indefinitely.
  • Term Auto Renewable: If a program is built using an auto-renewable recurring plan, it will automatically renew at the end of the term. You also have the flexibility to override the auto–renewable feature inherited from the recurring plan.
Recurring program amount

A recurring program will automatically inherit pricing from the linked recurring plan. However, you can customize the pricing you offer at the recurring program level by overriding the plan amount.

  • Overriding the plan amount: You can override the recurring plan's default pricing by setting the planDefault = false and providing a non-zero monetary value in the recurringProgramAmount. The overridden price should be tax inclusive.
Billing frequency A recurring program will automatically inherit the billing frequency from the linked recurring plan.
Recurring program status You can choose when a recurring program will go active, either immediately or at a future date. If you change your mind and want to cancel it, you can do that as well.
  • Scheduled: Programs that you want to start at a future date are in Scheduled status.
  • Active: Recurring program goes into the active status when the billing cycle starts automatically.
  • Cancelled: Recurring programs that are no longer charged should be set to Cancelled status.
  • Paused: Pause a recurring program during the billing cycle.
  • Expired: Recurring programs whose term has ended and are not auto-renewable will be set to EXPIRED status automatically without your intervention. You can’t mark programs as EXPIRED. Cancelled programs will remain in the cancelled status and won’t be EXPIRED.

If you wish to know more about which program status you can update, refer to the Allowed status transitions table.
Custom merchant recurring program ID

 Apart from system-generated recurring program IDs, you can also tag your custom program identifier from your internal CRM, CMS, and ERP systems. The merchant recurring program ID must be unique.
Recurring program metadata You can store custom metadata (for example: labels, tags, consumer birthday, anniversary date, etc.) in the recurring program to enrich your consumer's experience.

if you wish to know more about how to fetch this metadata, refer to the Fetch recurring programs section.

Create a recurring program with a consumer profile

Once you decide the recurring plan to use, you can create a recurring program in two ways:

Create a recurring program using MRPS API

You can create a recurring program linked to an existing consumer profile or a new consumer profile by sending a POST request to the /recurringprograms endpoint.

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

HTTP Method: POST

Endpoint: /recurringprograms

Scenario: Creating a recurring program for a new consumer whose consumerProfileId does not exist. (creating a new consumer profile)

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
    }
}

Manage your recurring program

Managed Recurring Payments API allows you to manage and customize your recurring program to your business needs using the following features:

Notifications

Recurring payments

Manage recurring programs

Pause recurring programs

Make a manual payment

Refund a billing cycle