BasicsPayment APIEmbedded PaymentsReportingToolsSupport GuidesBlueSnap.com
Top of Section

Subscriptions Guide

Learn how to work with subscriptions in BlueSnap's Payment API

BlueSnap's Payment API provides two ways to work with subscriptions:

BlueSnap Subscription Billing Engine

The Payment API provides end-to-end subscription management capabilities, enabling you to:

  • Create custom subscription billing plans, with or without a trial period or an initial charge, and with the billing frequency you want
  • Create a subscription, which associates a shopper with a billing plan
  • Change subscription pricing for specific shoppers, for example for discounts or promotions
  • Easily move subscriptions from one plan to another

BlueSnap automatically processes your recurring subscription payments, keeps shoppers' cards updated, and runs automatic retries for subscription payments several times during a grace period.
For more details about our Subscription Billing Engine, see Subscription Capabilities.

Creating and Managing Subscriptions

This tutorial shows you how to work with subscriptions when using BlueSnap's full Subscription Billing Engine capabilities. We cover setting up subscription plans, adding shoppers to a plan (i.e. creating subscriptions), and performing common tasks like switching a subscription to a different plan or changing the subscription price.

Step 1: Setting up subscription billing plans

To get started, the first step is to set up some subscription billing plans. Each plan defines the billing frequency, amount, currency, and so on.

In this example, we set up billing plans for a gym membership. The plans have a monthly billing frequency and a trial period of one week. We set up three tiers:

  • Gold: $100
  • Silver: $50
  • Bronze: $25

To set up the plans, use the Create Plan request, and include the appropriate plan name, recurring charge amount, and other plan settings.

These are examples of the request content to create the Gold, Silver and Bronze plans:

{
    "chargeFrequency": "MONTHLY",
    "gracePeriodDays": 14,
    "trialPeriodDays": 7,
    "initialChargeAmount": 0,
    "name": "Gold Plan",
    "currency": "USD",
    "maxNumberOfCharges": 12,
    "recurringChargeAmount": 100,
    "chargeOnPlanSwitch": true
}

{
    "chargeFrequency": "MONTHLY",
    "gracePeriodDays": 14,
    "trialPeriodDays": 7,
    "initialChargeAmount": 0,
    "name": "Silver Plan",
    "currency": "USD",
    "maxNumberOfCharges": 12,
    "recurringChargeAmount": 50,
    "chargeOnPlanSwitch": true
}

{
    "chargeFrequency": "MONTHLY",
    "gracePeriodDays": 14,
    "trialPeriodDays": 7,
    "initialChargeAmount": 0,
    "name": "Bronze Plan",
    "currency": "USD",
    "maxNumberOfCharges": 12,
    "recurringChargeAmount": 25,
    "chargeOnPlanSwitch": true
}

The response provides the ID for each plan. In this example, the Gold Plan ID is 111, the Silver Plan ID is 222, and the Bronze Plan ID is 333. We need those IDs for the next step.

Step 2: Adding new subscriptions

Now that we have our plans ready, let's add a shopper to each one. To add a shopper to a plan, you create a subscription for that shopper.

Use the Create Subscription request, and include the relevant plan ID and shopper details.

These are examples of the request content to create subscriptions on the Gold, Silver and Bronze plans.

{
    "payerInfo": {
        "zip": 12345,
        "firstName": "Allen",
        "lastName": "A",
        "phone": "210-999-0000"
    },
    "paymentSource": {"creditCardInfo": {"creditCard": {
        "expirationYear": 2023,
        "securityCode": 111,
        "expirationMonth": "07",
        "cardNumber": 4111111111111111
    }}},
    "planId": 111
}

{
    "payerInfo": {
        "zip": 67890,
        "firstName": "Betty",
        "lastName": "B",
        "phone": "876-555-4343"
    },
    "paymentSource": {"creditCardInfo": {"creditCard": {
        "expirationYear": 2023,
        "securityCode": 111,
        "expirationMonth": "07",
        "cardNumber": 4111111111111111
    }}:{},
    "planId": 222
}

{
    "payerInfo": {
        "zip": 12345,
        "firstName": "Carla",
        "lastName": "C",
        "phone": "654-333-2222"
    },
    "paymentSource": {"creditCardInfo": {"creditCard": {
        "expirationYear": 2023,
        "securityCode": 111,
        "expirationMonth": "07",
        "cardNumber": 4111111111111111
    }}},
    "planId": 333
}

Each response provides the ID for each subscription. In this example, Allen's subscription ID is 121212, Betty's subscription ID is 343434, and Carla's subscription ID is 565656. We need the subscription ID for Step 3: Upgrading a subscription.

📘

ACH/ECP & SEPA Direct Debit subscriptions

For ACH/ECP and SEPA Direct Debit subscriptions, the subscription ID is not returned in the Create Subscription response. It is created once the payment has been processed (typically within 2–6 business days). You will then be informed of the subscription ID via Charge webhook or via Retrieve Specific Charge request.

Step 3: Upgrading a subscription

Betty, who currently has a subscription on the Silver Plan, is very happy with her gym membership and wants to upgrade to the Gold Plan.

To switch Betty's subscription to a different plan, send an Update Subscription request, and include Betty's subscription ID in the URL, as follows:
services/2/recurring/subscriptions/343434

In the request, we change the plan ID for the subscription to the Gold Plan (ID 111). Since that is the only attribute that we want to change for this subscription, that is the only field we need to send in the request, as shown in this example:

{
  planId": 111
}

📘

Notes on switching plans

Prorated charges
Because the chargeOnPlanSwitch setting for the Gold Plan is set to true, the Gold Plan price is charged immediately upon switching the plan, rather than waiting until the next billing period. The amount that was already applied to the previous plan is deducted from the new plan's charge.

For example, the price for the Silver Plan is $50 per month and Betty upgraded to the Gold Plan after two weeks. This means that half of the monthly price paid was already used. So the remaining unspent amount ($25) is applied to the charge for the Gold Plan. The Gold Plan price is $100 and the prorated amount deducted is $25, so Betty is charged $75 at the time of the upgrade.

Trial period skipped
The trial period in the Gold Plan is automatically ignored, since this is an existing subscription that already started running.

Step 4: Creating a subscription with a discounted price

You now have a new shopper, Daniel, who would like to sign up for the Silver Plan at the discounted price of $40, which you offered as a promotion.

To do this, you send a Create Subscription request with Daniel's payment information. In the request, you include the overrideRecurringChargeAmount parameter, with the value set to 40. This changes the recurring price to $40 permanently. It applies only to Daniel's subscription and does not affect the price of the Silver Plan itself.

This is an example of the request content:

{
    "overrideRecurringChargeAmount": 40,
    "payerInfo": {
        "zip": 54321,
        "firstName": "Daniel",
        "lastName": "D",
        "phone": "555-777-9999"
    },
    "paymentSource": {"creditCardInfo": [{"creditCard": {
        "expirationYear": 2018,
        "securityCode": 837,
        "expirationMonth": "02",
        "cardNumber": 4263982640269299
    }}]},
    "planId": 222
}

Step 5: Retrieving plan and subscription details

Finally, we can see what plans and subscriptions we have by retrieving a list of each.

To retrieve a list of all plans, we send a Retrieve All Plans request to /services/2/recurring/plans
This is an example response to our GET request:

{
    "lastPage": true,
    "plans": [
        {
            "chargeFrequency": "MONTHLY",
            "gracePeriodDays": 14,
            "trialPeriodDays": 7,
            "initialChargeAmount": 0,
            "name": "Bronze Plan",
            "planId": 333,
            "currency": "USD",
            "maxNumberOfCharges": 12,
            "recurringChargeAmount": 25,
            "chargeOnPlanSwitch": true,
            "status": "ACTIVE"
        },
        {
            "chargeFrequency": "MONTHLY",
            "gracePeriodDays": 14,
            "trialPeriodDays": 7,
            "initialChargeAmount": 0,
            "name": "Silver Plan",
            "planId": 222,
            "currency": "USD",
            "maxNumberOfCharges": 12,
            "recurringChargeAmount": 50,
            "chargeOnPlanSwitch": true,
            "status": "ACTIVE"
        },
        {
            "chargeFrequency": "MONTHLY",
            "gracePeriodDays": 14,
            "trialPeriodDays": 7,
            "initialChargeAmount": 0,
            "name": "Gold Plan",
            "planId": 111,
            "currency": "USD",
            "maxNumberOfCharges": 12,
            "recurringChargeAmount": 100,
            "chargeOnPlanSwitch": true,
            "status": "ACTIVE"
        }
    ]
}

To retrieve a list of all subscriptions for a specific plan, for example the Gold Plan, we send a Retrieve All Subscriptions request to the subscriptions URL, with the Plan ID as a query parameter. For example:

/services/2/recurring/subscriptions/?planid=111

This is an example response to our GET request:

{
    "lastPage": true,
    "subscriptions": [
        {
            "nextChargeDate": "2017-07-01",
            "quantity": 1,
            "trialPeriodDays": 7,
            "paymentSource": {"creditCardInfo": [{"creditCard": {
                "expirationYear": 2018,
                "cardLastFourDigits": 9299,
                "cardType": "VISA",
                "expirationMonth": "02"
            }}]},
            "softDescriptor": "Merchant Name",
            "recurringChargeAmount": 100,
            "chargeFrequency": "MONTHLY",
            "vaultedShopperId": 7895455,
            "payerInfo": {
                "zip": 67890,
                "firstName": "Betty",
                "lastName": "B",
                "phone": "876-555-4343"
            },
            "initialChargeAmount": 0,
            "autoRenew": true,
            "planId": 111,
            "currency": "USD",
            "subscriptionId": 343434,
            "status": "ACTIVE"
        },
        {
            "nextChargeDate": "2017-07-01",
            "quantity": 1,
            "trialPeriodDays": 7,
            "paymentSource": {"creditCardInfo": [{"creditCard": {
                "expirationYear": 2018,
                "cardLastFourDigits": 9299,
                "cardType": "VISA",
                "expirationMonth": "02"
            }}]},
            "softDescriptor": "Merchant Name",
            "recurringChargeAmount": 100,
            "chargeFrequency": "MONTHLY",
            "vaultedShopperId": 7891234,
            "payerInfo": {
                "zip": 12345,
                "firstName": "Allen",
                "lastName": "A",
                "phone": "210-999-0000"
            },
            "initialChargeAmount": 0,
            "autoRenew": true,
            "planId": 111,
            "currency": "USD",
            "subscriptionId": 121212,
            "status": "ACTIVE"
        }
    ]
}

Testing your Subscriptions

Because the subscription model requires a time lapse in order to understand the total flow, we have provided a simulator to test your subscriptions in sandbox.

Enter the subscriptionId in the following POST request, to simulate a subscription event. The execution of this request triggers the IPNs, emails, and invoices associated with the transaction.

/services/2/recurring/subscriptions/{subscriptionId}/run-specific

The successful response is 204 No Content.

📘

Note

This request does not impact subscription dates, meaning time-sensitive properties, such as grace period, are not simulated.

Merchant-Managed Subscriptions

If you prefer to manage subscriptions on your side (or through a third party) but process the payments through BlueSnap, you simply send in each recurring transaction to be processed. BlueSnap's built-in support for Account Updater ensures your shopper's card information is kept up-to-date. It works by automatically updating cards set to expire within a month so you don't lose sales and the shopper continues to enjoy their subscription service.

The flow for processing your own subscriptions consists of three primary steps:

676

You also get access to our advanced reporting capabilities that provide a clear differentiation between one-time and recurring charges, and our conversion reports that take into account your specific dunning logic.

Cards and Wallets

If you want to process merchant-managed subscription payments for cards or wallet, then follow these steps:

Step 1: Process initial subscription payment via card or wallet

To process the initial subscription charge, send a Create Merchant-Managed Subscription request with the shopper's information and charge details. For example: 

{
  "amount": 45, 
  "currency": "USD",
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "us"
  },
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "expirationYear": 2018,
        "securityCode": 111,
        "expirationMonth": "05",
        "cardNumber": 4012000033330026
      }
    }
  }
}

{
	"amount": 45, 
    "currency": "USD",
	"paymentSource": {
		"wallet": {
			"walletType": "APPLE_PAY",
			"encodedPaymentToken": "eyJiaWxsaW5nQ29udGFjdCI6eyJhZGRyZ..."
		}
	}
}

{
  "amount": 45, 
  "currency": "USD", 
  "paymentSource": {
    "wallet": {
      "walletType": "GOOGLE_PAY",
      "encodedPaymentToken": "ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd"
      }
    }
  }	
}

Step 2: Get the subscription ID

A successful Create Merchant-Managed Subscription response contains a subscriptionId property, whose value is a unique ID that BlueSnap assigns to the subscription. You use this subscription ID to process recurring payments and associate them to the correct subscription. For example: 

{
  "chargeId": 12947185,
  "subscriptionId": 10541275,
  "vaultedShopperId": 22192749,
  "transactionId": "1015006793",
  "transactionDate": "2017-10-30",
  "amount": 45,
  "currency": "USD",
  "softDescriptor": "BLS*Testing",
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "cardLastFourDigits": "0026",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "CLASSIC",
        "expirationMonth": "05",
        "expirationYear": "2018"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  },
  "processingInfo": {
    "processingStatus": "SUCCESS"
  }
}

{
    "chargeId": 175047,
    "subscriptionId": 39555006,
    "vaultedShopperId": 19598228,
    "transactionId": "38599972",
    "transactionDate": "2021-09-16",
    "amount": 45.00,
    "currency": "USD",
    "softDescriptor": "BLS*CodeDiggers",
    "paymentSource": {
        "wallet": {
            "walletType": "APPLE_PAY",
            "billingContactInfo": {
                "firstName": "John",
                "lastName": "Smith",
                "address1": "800 South Street",
                "city": "Waltham",
                "state": "MA",
                "zip": "01822",
                "country": "us"
            },
            "applePay": {
                "cardLastFourDigits": "1471",
                "cardType": "MASTERCARD",
                "cardSubType": "DEBIT",
                "cardCategory": "ACQUIRER ONLY",
                "binCategory": "CONSUMER",
                "cardRegulated": "N",
                "issuingCountryCode": "us",
                "issuingBank": "MASTERCARD - MEMBER TEST FACILITY",
                "dpanLastFourDigits": "6937",
                "dpanExpirationMonth": "9",
                "dpanExpirationYear": "2022"
            },
            "tokenizedCard": {
                "dpanExpirationMonth": "9",
                "dpanExpirationYear": "2022",
                "dpanLastFourDigits": "6937",
                "cardLastFourDigits": "1471",
                "cardType": "MASTERCARD",
                "cardSubType": "DEBIT",
                "cardCategory": "ACQUIRER ONLY",
                "binCategory": "CONSUMER",
                "cardRegulated": "N",
                "issuingCountryCode": "us",
                "issuingBank": "MASTERCARD - MEMBER TEST FACILITY"
            }
        }
    },
    "chargeInfo": {
        "chargeType": "INITIAL"
    },
    "processingInfo": {
        "processingStatus": "SUCCESS",
        "authorizationCode": "732032"
    },
    "fraudResultInfo": {}
}

{
  "chargeId": "165323",
  "subscriptionId": 39518448,
  "vaultedShopperId": 19559630,
  "transactionId": "38492608",
  "transactionDate": "2018-10-13",
  "amount": 45,
  "currency": "USD",
  "softDescriptor": "BLS*Testing",
  "paymentSource": {
    "wallet": {
      "billingContactInfo": {
        "firstName": "Jane",
        "lastName": "Shopper",
        "address1": "800 South St",
        "city": "Waltham",
        "zip": "02453",
        "country": "us"
      },
      "tokenizedCard": {
        "cardLastFourDigits": "0492",
        "cardType": "VISA",
        "cardSubType": "DEBIT",
        "dpanLastFourDigits": "6889",
        "dpanExpirationMonth": "11",
        "dpanExpirationYear": "2025"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  }
}

Step 3: Process recurring payments via card or wallet

You can then process recurring payments by sending a Create Merchant-Managed Subscription Charge request. To associate the recurring payments with the relevant subscription, include the subscription ID in the request endpoint in the format: /services/2/recurring/ondemand/{subscriptionId}
For example:
/services/2/recurring/ondemand/10541275

Additionally, include the charge details in the request body. For example:

{
  "amount": 45, 
  "currency": "USD"
}

A successful response has HTTP status code 200 OK. To view request and response examples, see Create Merchant-Managed Subscription Charge.

Back to Top

ACH and SEPA Direct Debit

If you want to process merchant-managed subscription payments for ACH/ECP or SEPA Direct Debit, then follow the steps in this section. Please note that for SEPA Direct Debit, you must first have it enabled for your account by contacting Merchant Support.

Step 1: Process initial subscription payment via ACH or SEPA Direct Debit

To process the initial subscription charge, send a Create Merchant-Managed Subscription request with the shopper's information and charge details. For example: 

{
  "amount": 65,
  "currency": "USD",
  "authorizedByShopper": true,
  "payerInfo": {
    "firstName": "Jane",
    "lastName": "Doe",
    "zip": "12345",
    "country": "us"
  },
  "paymentSource": {
    "ecpInfo": {
      "ecp": {
        "accountNumber": 4099999992, 
        "routingNumber": "011075150",
        "accountType": "CONSUMER_CHECKING"
      }
    }
  }
}

{
  "amount": 45,
  "currency": "EUR",
  "authorizedByShopper": true,
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "fr"
  },
  "paymentSource": {
    "sepaDirectDebitInfo": {
      "sepaDirectDebit": {
        "iban": "DE09100100101234567893"
      }
    }
  }
}

A successful response has HTTP status code 200 OK. To view request and response examples, see Create Merchant-Managed Subscription.

Step 2: Get the subscription ID within 2 - 6 business days

Within 2–6 business days, the initial payment is processed and BlueSnap assigns a subscription ID to the new subscription. You use this subscription ID to process recurring payments and associate them with the correct subscription.

You can obtain the subscription ID in two ways:

  • In the subscriptionId field in the Charge IPN that is sent once the initial payment is processed. See IPNs (Webhooks).
    or
  • By sending a Retrieve Specific Charge request once the payment has been processed. If the request is successful, the response is similar to the following, with the subscriptionId property.
{
  "chargeId": 13209397,
  "subscriptionId": 10939179,
  "vaultedShopperId": 22330225,
  "transactionId": "1015609477",
  "transactionDate": "2018-01-25",
  "amount": 65,
  "currency": "USD",
  "softDescriptor": "default_descriptor",
  "paymentSource": {
    "ecpInfo": {
      "ecp": {
        "accountNumber": "4099999992",
        "routingNumber": "011075150",
        "accountType": "CONSUMER_CHECKING"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  },
  "processingInfo": {
    "processingStatus": "SUCCESS"
  }
}

{
  "chargeId": 12947225,
  "subscriptionId": 10541329,
  "vaultedShopperId": 22192833,
  "transactionId": "1015006899",
  "transactionDate": "2017-10-30",
  "amount": 45,
  "currency": "EUR",
  "softDescriptor": "Testing",
  "paymentSource": {
    "sepaDirectDebitInfo": {
      "sepaDirectDebit": {
        "ibanFirstFour": "DE09",
        "ibanLastFour": "7893",
        "mandateId": "Jan153537",
        "mandateDate": "30-Oct-17"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  },
  "processingInfo": {
    "processingStatus": "SUCCESS"
  }
}

Step 3: Process recurring payments via ACH or SEPA Direct Debit

You can then process recurring payments by sending a Create Merchant-Managed Subscription Charge request. To associate the recurring payments with the relevant subscription, include the subscription ID in the request endpoint in the format: /services/2/recurring/ondemand/{subscriptionId}
For example:
/services/2/recurring/ondemand/10541329

Additionally, include the charge details in the request body. For example:

{
  "amount": 65,
  "currency": "USD"
}

{
  "amount": 45, 
  "currency": "EUR"
}

A successful response has have HTTP status code 200 OK and the payment is in pending status. To view request and response examples, see Create Merchant-Managed Subscription Charge. Within 2–6 business days, the payment is either be approved or declined. If it's approved, the shopper is charged and a Charge IPN is sent to notify you of the successful transaction. You can also retrieve the payment status via the Retrieve Specific Charge request.

Back to Top

PayPal

If you are managing subscriptions yourself (or through a third party) and want to offer the PayPal payment method for recurring subscription payments, this option is available via the Payment API.

When you process the initial subscription payment, you simply mark it as a recurring transaction. Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You use this subscription ID to process recurring payments (either individually or as part of a batch transaction) and associate them to the correct subscription. Follow the steps below to get started.

👍

Prerequisites

Before you begin, make sure that you have connected PayPal and BlueSnap, and that the reference transaction option has been enabled in your PayPal account.

Step 1: Process initial subscription payment via PayPal

For a new subscription, make sure to set the recurring property to 1 in your Create PayPal Transaction request.

For example:

{
    "amount": 100,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "merchantTransactionId": "A3bn43",
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "cancelUrl": "http://www.cancelURL.com",
        "recurring": 1,
        "returnUrl": "http://www.returnURL.com"
    }
}

If the request is successful, the response is similar to the following:

{
    "amount": 100,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "processingInfo": {"status": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout",
        "orderId": 980111
    }
}

Step 2: Get the subscription ID after initial payment has been processed

Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You use this subscription ID to process recurring payments and associate them to the correct subscription.

You can obtain the subscription ID in two ways:

  • In the subscriptionId field in the Charge IPN that is sent once the initial payment is processed. See IPNs (Webhooks).
    or
  • By sending a Retrieve PayPal Transaction request once the payment has been processed (likely no more than five minutes after submission, to allow time for the shopper to complete checkout on PayPal). If the request is successful, the response is similar to the following, with the paypalSubscriptionId in the paypalTransaction element:
{
    "amount": 100,
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "processingInfo": {"status": "SUCCESS"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "transactionId": 38500786,
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout",
        "orderId": 980111,
        "paypalSubscriptionId": 1234567
    }
}

Step 3: Process recurring payments via PayPal

You can then process recurring payments, either individually or as part of a batch transaction. To associate the recurring payments with the relevant subscription, include the subscription ID in the request. For example:

{
    "amount": 100,
    "currency": "USD",
    "paypalTransaction": {"paypalSubscriptionId": 1234567}
}

If the request is successful, the response is similar to the following:

{
    "amount": 100,
    "processingInfo": {"status": "SUCCESS"},
    "currency": "USD",
    "transactionId": 38500786,
    "paypalTransaction": {"paypalSubscriptionId": 1234567}
}

Back to Top

Batch Processing

If you manage your own subscriptions, you can increase efficiency by processing your shoppers' recurring payments in a batch. This is easy to achieve by saving the shopper's payment info in BlueSnap, running a query in your system to obtain a list of the subscriptions with payments due, and then compiling those subscription payments into a single batch file to send to BlueSnap for processing. For a detailed walk-through of this flow, see the Batch Processing Guide.

Account Updater for Merchant-Managed Cards

If you are storing your shoppers' credit cards, you can use BlueSnap's Account Updater service to stay up-to-date with the last card and account information. For more information, see Account Updater.