{"_id":"59a45d2bd12e81000f842f10","category":{"_id":"59a45d2bd12e81000f842ef0","version":"59a45d2bd12e81000f842ee2","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":13,"slug":"topics","title":"Guides & Tools"},"parentDoc":null,"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","version":{"_id":"59a45d2bd12e81000f842ee2","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-08-28T18:12:59.168Z","releaseDate":"2017-08-28T18:12:59.168Z","categories":["59a45d2bd12e81000f842ee3","59a45d2bd12e81000f842ee4","59a45d2bd12e81000f842ee5","59a45d2bd12e81000f842ee6","59a45d2bd12e81000f842ee7","59a45d2bd12e81000f842ee8","59a45d2bd12e81000f842ee9","59a45d2bd12e81000f842eea","59a45d2bd12e81000f842eeb","59a45d2bd12e81000f842eec","59a45d2bd12e81000f842eed","59a45d2bd12e81000f842eee","59a45d2bd12e81000f842eef","59a45d2bd12e81000f842ef0","59a45d2bd12e81000f842ef1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.22.1","version_clean":"8976.0.0-JSON","version":"8976-JSON"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-13T12:54:21.149Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":117,"body":"BlueSnap's **Payment API** provides two ways to work with subscriptions:\n\n  * [BlueSnap Subscription Billing Engine](#section-bluesnap-subscription-billing-engine): Take advantage of our award-winning Subscription Billing Engine to automate and optimize your subscriptions.\n  * [Merchant-Managed Subscriptions](#section-merchant-managed-subscriptions): Manage your own subscriptions and process the payments through BlueSnap.\n\n#BlueSnap Subscription Billing Engine\nThe Payment API provides end-to-end subscription management capabilities, enabling you to:\n  * Create custom subscription billing plans, with or without a trial period or an initial charge, and with the billing frequency you want\n  * Create a subscription, which associates a shopper with a billing plan\n  * Change subscription pricing for specific shoppers, for example for discounts or promotions\n  * Easily move subscriptions from one plan to another\n\nBlueSnap automatically processes your recurring subscription payments, keeps shoppers' cards updated, and runs automatic retries for subscription payments several times during a grace period.\nFor more details about our Subscription Billing Engine, see [Subscription Capabilities](http://support.bluesnap.com/docs/subscription-options).\n\n##Tutorial: Subscriptions\nThis tutorial will show you how to work with subscriptions when using BlueSnap's full Subscription Billing Engine capabilities. We'll 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.\n  * [Step 1: Setting up subscription billing plans](#section-step-1-setting-up-subscription-billing-plans)\n  * [Step 2: Adding new subscriptions](#section-step-2-adding-new-subscriptions)\n  * [Step 3: Upgrading a subscription](#section-step-3-upgrading-a-subscription)\n  * [Step 4: Creating a subscription with a discounted price](#section-step-4-creating-a-subscription-with-a-discounted-price)\n  * [Step 5: Retrieving plan and subscription details](#section-step-5-retrieving-plan-and-subscription-details)\n  * [Testing your subscriptions](#section-testing-your-subscriptions)\n\n###Step 1: Setting up subscription billing plans\nTo get started, the first step is to set up some subscription billing plans. Each plan defines the billing frequency, amount, currency, and so on. \n\nIn this example, we will set up billing plans for a gym membership. The plans will have a **monthly** billing frequency and a **trial period of one week**. We will set up three tiers:\n  * Gold: $100\n  * Silver: $50\n  * Bronze: $25\n\nTo set up the plans, use the [Create Plan](doc:create-plan) request, and include the appropriate plan name, recurring charge amount, and other plan settings.\n\nThese are examples of the request content to create the Gold, Silver and Bronze plans:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n    \\\"gracePeriodDays\\\": 14,\\n    \\\"trialPeriodDays\\\": 7,\\n    \\\"initialChargeAmount\\\": 0,\\n    \\\"name\\\": \\\"Gold Plan\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"maxNumberOfCharges\\\": 12,\\n    \\\"recurringChargeAmount\\\": 100,\\n    \\\"chargeOnPlanSwitch\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Plan: Gold\"\n    },\n    {\n      \"code\": \"{\\n    \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n    \\\"gracePeriodDays\\\": 14,\\n    \\\"trialPeriodDays\\\": 7,\\n    \\\"initialChargeAmount\\\": 0,\\n    \\\"name\\\": \\\"Silver Plan\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"maxNumberOfCharges\\\": 12,\\n    \\\"recurringChargeAmount\\\": 50,\\n    \\\"chargeOnPlanSwitch\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Plan: Silver\"\n    },\n    {\n      \"code\": \"{\\n    \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n    \\\"gracePeriodDays\\\": 14,\\n    \\\"trialPeriodDays\\\": 7,\\n    \\\"initialChargeAmount\\\": 0,\\n    \\\"name\\\": \\\"Bronze Plan\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"maxNumberOfCharges\\\": 12,\\n    \\\"recurringChargeAmount\\\": 25,\\n    \\\"chargeOnPlanSwitch\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Plan: Bronze\"\n    }\n  ]\n}\n[/block]\nThe response will provide the ID for each plan. In this example, the Gold Plan's ID will be `111`, the Silver Plan's ID will be `222`, and the Bronze Plan's ID will be `333`. We'll need those IDs for the next step.\n\n###Step 2: Adding new subscriptions\nNow that we have our plans ready, let's add a shopper to each one. To add a shopper to a plan, you will create a subscription for that shopper.\n\nUse the [Create Subscription](doc:create-subscription) request, and include the relevant plan ID and shopper details.\n\nThese are examples of the request content to create subscriptions on the Gold, Silver and Bronze plans.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"payerInfo\\\": {\\n        \\\"zip\\\": 12345,\\n        \\\"firstName\\\": \\\"Allen\\\",\\n        \\\"lastName\\\": \\\"A\\\",\\n        \\\"phone\\\": \\\"210-999-0000\\\"\\n    },\\n    \\\"paymentSource\\\": {\\\"creditCardInfo\\\": [{\\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 837,\\n        \\\"expirationMonth\\\": \\\"02\\\",\\n        \\\"cardNumber\\\": 4263982640269299\\n    }}]},\\n    \\\"planId\\\": 111\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Subscription on Gold Plan\"\n    },\n    {\n      \"code\": \"{\\n    \\\"payerInfo\\\": {\\n        \\\"zip\\\": 67890,\\n        \\\"firstName\\\": \\\"Betty\\\",\\n        \\\"lastName\\\": \\\"B\\\",\\n        \\\"phone\\\": \\\"876-555-4343\\\"\\n    },\\n    \\\"paymentSource\\\": {\\\"creditCardInfo\\\": [{\\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 837,\\n        \\\"expirationMonth\\\": \\\"02\\\",\\n        \\\"cardNumber\\\": 4263982640269299\\n    }}]},\\n    \\\"planId\\\": 222\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Subscription on Silver Plan\"\n    },\n    {\n      \"code\": \"{\\n    \\\"payerInfo\\\": {\\n        \\\"zip\\\": 12345,\\n        \\\"firstName\\\": \\\"Carla\\\",\\n        \\\"lastName\\\": \\\"C\\\",\\n        \\\"phone\\\": \\\"654-333-2222\\\"\\n    },\\n    \\\"paymentSource\\\": {\\\"creditCardInfo\\\": [{\\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 837,\\n        \\\"expirationMonth\\\": \\\"02\\\",\\n        \\\"cardNumber\\\": 4263982640269299\\n    }}]},\\n    \\\"planId\\\": 333\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Subscription on Bronze Plan\"\n    }\n  ]\n}\n[/block]\nEach response will provide the ID for each subscription. In this example, Allen's subscription ID will be `121212`, Betty's subscription ID will be `343434`, and Carla's subscription ID will be `565656`. We'll need the subscription ID for *Step 3: Upgrading a subscription*.\n\n###Step 3: Upgrading a subscription\nBetty, who currently has a subscription on the Silver Plan, is very happy with her gym membership and wants to upgrade to the Gold Plan.\n\nTo switch Betty's subscription to a different plan, send an [Update Subscription](doc:update-subscription) request, and include Betty's subscription ID in the URL, as follows:\n`services/2/recurring/subscriptions/343434`\n\nIn the request, we'll 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"planId\\\": 111}\",\n      \"language\": \"json\",\n      \"name\": \"Upgrade Subscription to Gold Plan\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Notes on switching plans\",\n  \"body\": \"**Prorated charges**\\nBecause the `chargeOnPlanSwitch` setting for the Gold Plan is set to **true**, the Gold Plan price will be charged immediately upon switching the plan, rather than waiting until the next billing period. The amount that was already applied to the previous plan will be deducted from the new plan's charge.\\n\\nFor 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) will be applied to the charge for the Gold Plan. The Gold Plan price is $100 and the prorated amount deducted is $25, so Betty will be charged $75 at the time of the upgrade.\\n\\n**Trial period skipped**\\nThe trial period in the Gold Plan will be automatically ignored, since this is an existing subscription that already started running.\"\n}\n[/block]\n###Step 4: Creating a subscription with a discounted price\nYou 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. \n\nTo do this, you will send a [Create Subscription](doc:create-subscription) request with Daniel's payment information. In the request, you will include the `overrideRecurringChargeAmount` parameter, with the value set to **40**. This will change the recurring price to $40 permanently. It applies only to Daniel's subscription and does not affect the price of the Silver Plan itself.\n\nThis is an example of the request content:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"overrideRecurringChargeAmount\\\": 40,\\n    \\\"payerInfo\\\": {\\n        \\\"zip\\\": 54321,\\n        \\\"firstName\\\": \\\"Daniel\\\",\\n        \\\"lastName\\\": \\\"D\\\",\\n        \\\"phone\\\": \\\"555-777-9999\\\"\\n    },\\n    \\\"paymentSource\\\": {\\\"creditCardInfo\\\": [{\\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 837,\\n        \\\"expirationMonth\\\": \\\"02\\\",\\n        \\\"cardNumber\\\": 4263982640269299\\n    }}]},\\n    \\\"planId\\\": 222\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Subscription with discounted price for Silver Plan\"\n    }\n  ]\n}\n[/block]\n###Step 5: Retrieving plan and subscription details\nFinally, we can see what plans and subscriptions we have by retrieving a list of each.\n\nTo retrieve a list of all **plans**, we send a [Retrieve All Plans](doc:retrieve-all-plans) request to `/services/2/recurring/plans`\nThis is an example response to our GET request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"lastPage\\\": true,\\n    \\\"plans\\\": [\\n        {\\n            \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n            \\\"gracePeriodDays\\\": 14,\\n            \\\"trialPeriodDays\\\": 7,\\n            \\\"initialChargeAmount\\\": 0,\\n            \\\"name\\\": \\\"Bronze Plan\\\",\\n            \\\"planId\\\": 333,\\n            \\\"currency\\\": \\\"USD\\\",\\n            \\\"maxNumberOfCharges\\\": 12,\\n            \\\"recurringChargeAmount\\\": 25,\\n            \\\"chargeOnPlanSwitch\\\": true,\\n            \\\"status\\\": \\\"ACTIVE\\\"\\n        },\\n        {\\n            \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n            \\\"gracePeriodDays\\\": 14,\\n            \\\"trialPeriodDays\\\": 7,\\n            \\\"initialChargeAmount\\\": 0,\\n            \\\"name\\\": \\\"Silver Plan\\\",\\n            \\\"planId\\\": 222,\\n            \\\"currency\\\": \\\"USD\\\",\\n            \\\"maxNumberOfCharges\\\": 12,\\n            \\\"recurringChargeAmount\\\": 50,\\n            \\\"chargeOnPlanSwitch\\\": true,\\n            \\\"status\\\": \\\"ACTIVE\\\"\\n        },\\n        {\\n            \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n            \\\"gracePeriodDays\\\": 14,\\n            \\\"trialPeriodDays\\\": 7,\\n            \\\"initialChargeAmount\\\": 0,\\n            \\\"name\\\": \\\"Gold Plan\\\",\\n            \\\"planId\\\": 111,\\n            \\\"currency\\\": \\\"USD\\\",\\n            \\\"maxNumberOfCharges\\\": 12,\\n            \\\"recurringChargeAmount\\\": 100,\\n            \\\"chargeOnPlanSwitch\\\": true,\\n            \\\"status\\\": \\\"ACTIVE\\\"\\n        }\\n    ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Retrieve Plans Response\"\n    }\n  ]\n}\n[/block]\nTo retrieve a list of all **subscriptions** for a specific plan, for example the Gold Plan, we send a [Retrieve All Subscriptions](doc:retrieve-all-subscriptions) request to the subscriptions URL, with the Plan ID as a query parameter. For example: `/services/2/recurring/subscriptions/?planid=111`\n\nThis is an example response to our GET request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"lastPage\\\": true,\\n    \\\"subscriptions\\\": [\\n        {\\n            \\\"nextChargeDate\\\": \\\"2017-07-01\\\",\\n            \\\"quantity\\\": 1,\\n            \\\"trialPeriodDays\\\": 7,\\n            \\\"paymentSource\\\": {\\\"creditCardInfo\\\": [{\\\"creditCard\\\": {\\n                \\\"expirationYear\\\": 2018,\\n                \\\"cardLastFourDigits\\\": 9299,\\n                \\\"cardType\\\": \\\"VISA\\\",\\n                \\\"expirationMonth\\\": \\\"02\\\"\\n            }}]},\\n            \\\"softDescriptor\\\": \\\"Merchant Name\\\",\\n            \\\"recurringChargeAmount\\\": 100,\\n            \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n            \\\"vaultedShopperId\\\": 7895455,\\n            \\\"payerInfo\\\": {\\n                \\\"zip\\\": 67890,\\n                \\\"firstName\\\": \\\"Betty\\\",\\n                \\\"lastName\\\": \\\"B\\\",\\n                \\\"phone\\\": \\\"876-555-4343\\\"\\n            },\\n            \\\"initialChargeAmount\\\": 0,\\n            \\\"autoRenew\\\": true,\\n            \\\"planId\\\": 111,\\n            \\\"currency\\\": \\\"USD\\\",\\n            \\\"subscriptionId\\\": 343434,\\n            \\\"status\\\": \\\"ACTIVE\\\"\\n        },\\n        {\\n            \\\"nextChargeDate\\\": \\\"2017-07-01\\\",\\n            \\\"quantity\\\": 1,\\n            \\\"trialPeriodDays\\\": 7,\\n            \\\"paymentSource\\\": {\\\"creditCardInfo\\\": [{\\\"creditCard\\\": {\\n                \\\"expirationYear\\\": 2018,\\n                \\\"cardLastFourDigits\\\": 9299,\\n                \\\"cardType\\\": \\\"VISA\\\",\\n                \\\"expirationMonth\\\": \\\"02\\\"\\n            }}]},\\n            \\\"softDescriptor\\\": \\\"Merchant Name\\\",\\n            \\\"recurringChargeAmount\\\": 100,\\n            \\\"chargeFrequency\\\": \\\"MONTHLY\\\",\\n            \\\"vaultedShopperId\\\": 7891234,\\n            \\\"payerInfo\\\": {\\n                \\\"zip\\\": 12345,\\n                \\\"firstName\\\": \\\"Allen\\\",\\n                \\\"lastName\\\": \\\"A\\\",\\n                \\\"phone\\\": \\\"210-999-0000\\\"\\n            },\\n            \\\"initialChargeAmount\\\": 0,\\n            \\\"autoRenew\\\": true,\\n            \\\"planId\\\": 111,\\n            \\\"currency\\\": \\\"USD\\\",\\n            \\\"subscriptionId\\\": 121212,\\n            \\\"status\\\": \\\"ACTIVE\\\"\\n        }\\n    ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Retrieve Subscriptions Response: subscriptions on the Gold Plan\"\n    }\n  ]\n}\n[/block]\n## Testing your subscriptions\nBecause 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.\n\nEnter the `subscriptionId` in the following GET request, to execute the next scheduled subscription event.  The execution of this request will trigger the IPN's, emails, and invoices associated with the transaction.\n\n`/services/2/subscriptions/subscriptionId/run-specific`\n\nThe successful response is 204 No Content\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n#Merchant-Managed Subscriptions\nIf you prefer to manage subscriptions on your side (or through a third party) but process the payments through BlueSnap, you will simply send in each recurring transaction to be processed. More details are provided below for credit card transactions, PayPal, batch processing, and Account Updater (a tool to boost sales by keep shoppers' cards updated).\n  * [Processing merchant-managed credit card subscription payments](#section-processing-merchant-managed-credit-card-subscription-payments)\n  * [Processing merchant-managed PayPal subscription payments](#section-processing-merchant-managed-paypal-subscription-payments)\n  * [Batch processing merchant-managed subscription payments](#section-batch-processing-merchant-managed-subscription-payments)\n  * [Account Updater for merchant-managed cards](#section-account-updater-for-merchant-managed-cards)\n\n##Processing merchant-managed credit card subscription payments\nWhen you want to process a recurring payment via a credit card, you will send an [Auth Capture](doc:auth-capture) or [Auth Only](doc:auth-only) request by following these steps: \n1. For an initial charge, include the shopper's payment information, and in the `recurringTransaction` field, enter **ECOMMERCE**. \n2. For all subsequent charges, enter **RECURRING**. This means that you will not need to send the CVV of the shopper's card when you send a transaction for processing. \n\nLater on, if you want to change the credit card, start at Step 1 again. \n\nThe below examples show Auth Capture requests to process a recurring payment. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 11,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"softDescriptor\\\": \\\"DescTest\\\",\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 837,\\n        \\\"expirationMonth\\\": \\\"02\\\",\\n        \\\"cardNumber\\\": 4263982640269299\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Capture Request for recurring payment: Initial charge \"\n    },\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 11,\\n    \\\"vaultedShopperId\\\": 20769005,\\n    \\\"recurringTransaction\\\": \\\"RECURRING\\\",\\n    \\\"softDescriptor\\\": \\\"DescTest\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Capture Request for recurring payment: All subsequent charges \"\n    }\n  ]\n}\n[/block]\n##Processing merchant-managed PayPal subscription payments\nIf 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.\n\nWhen you processes the initial subscription payment, you'll simply mark it as a recurring transaction. Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You will 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/wFCDAYM8QsWbP836kNGW_PayPalSubscription.png\",\n        \"PayPalSubscription.png\",\n        \"676\",\n        \"251\",\n        \"#3d6cbc\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Prerequisites\",\n  \"body\": \"Before you begin, make sure that you have [connected PayPal and BlueSnap](http://support.bluesnap.com/docs/connecting-paypal-and-bluesnap), and that the [reference transaction option has been enabled](http://support.bluesnap.com/docs/enabling-subscriptions-with-paypal) in your PayPal account.\"\n}\n[/block]\n###Step 1: Process initial subscription payment\nFor a new subscription, make sure to set the `recurring` property to **1** in your [Create PayPal Transaction](doc:create-paypal-transaction) request.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 100,\\n    \\\"payerInfo\\\": {\\n        \\\"firstName\\\": \\\"John\\\",\\n        \\\"lastName\\\": \\\"Doe\\\"\\n    },\\n    \\\"merchantTransactionId\\\": \\\"A3bn43\\\",\\n    \\\"softDescriptor\\\": \\\"ABC COMPANY\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"paypalTransaction\\\": {\\n        \\\"cancelUrl\\\": \\\"http://www.cancelURL.com\\\",\\n        \\\"recurring\\\": 1,\\n        \\\"returnUrl\\\": \\\"http://www.returnURL.com\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Initial subscription payment via PayPal \"\n    }\n  ]\n}\n[/block]\nIf the request is successful, the response will be similar to the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 100,\\n    \\\"payerInfo\\\": {\\n        \\\"firstName\\\": \\\"John\\\",\\n        \\\"lastName\\\": \\\"Doe\\\"\\n    },\\n    \\\"processingInfo\\\": {\\\"status\\\": \\\"PENDING\\\"},\\n    \\\"softDescriptor\\\": \\\"ABC COMPANY\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"paypalTransaction\\\": {\\n        \\\"paypalUrl\\\": \\\"https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout\\\",\\n        \\\"orderId\\\": 980111\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response to initial subscription payment via PayPal\"\n    }\n  ]\n}\n[/block]\n###Step 2: Get the ID for the new subscription\nOnce the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You will use this subscription ID to process recurring payments and associate them to the correct subscription.\n\nYou can obtain the subscription ID in two ways:\n* In the `subscriptionId` field in the Charge IPN that is sent once the initial payment is processed. See [IPNs (Webhooks)](/v1.0/docs/webhooks-ipns).\n*or*\n* By sending a [Retrieve PayPal Transaction](doc:paypal-retrieve) 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 will be similar to the following, with the `paypalSubscriptionId` in the `paypalTransaction` element:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 100,\\n    \\\"payerInfo\\\": {\\n        \\\"firstName\\\": \\\"John\\\",\\n        \\\"lastName\\\": \\\"Doe\\\"\\n    },\\n    \\\"processingInfo\\\": {\\\"status\\\": \\\"SUCCESS\\\"},\\n    \\\"softDescriptor\\\": \\\"ABC COMPANY\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"transactionId\\\": 38500786,\\n    \\\"paypalTransaction\\\": {\\n        \\\"paypalUrl\\\": \\\"https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout\\\",\\n        \\\"orderId\\\": 980111,\\n        \\\"paypalSubscriptionId\\\": 1234567\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Reponse to Retrieve PayPal Transaction request\"\n    }\n  ]\n}\n[/block]\n###Step 3: Process recurring payments\nYou 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 100,\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"paypalTransaction\\\": {\\\"paypalSubscriptionId\\\": 1234567}\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Recurring subscription payment via PayPal\"\n    }\n  ]\n}\n[/block]\nIf the request is successful, the response will be similar to the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 100,\\n    \\\"processingInfo\\\": {\\\"status\\\": \\\"SUCCESS\\\"},\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"transactionId\\\": 38500786,\\n    \\\"paypalTransaction\\\": {\\\"paypalSubscriptionId\\\": 1234567}\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response to recurring subscription payment via PayPal\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Batch processing merchant-managed subscription payments\nIf 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](doc:batch-processing-tutorial).\n \n##Account Updater for merchant-managed cards\nIf 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](/v4.0/docs/account-updater).\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"Learn how to work with subscriptions in BlueSnap's Payment API","slug":"subscription-management","type":"basic","title":"Subscriptions Guide"}

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.

Tutorial: Subscriptions

This tutorial will show you how to work with subscriptions when using BlueSnap's full Subscription Billing Engine capabilities. We'll 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 will set up billing plans for a gym membership. The plans will have a monthly billing frequency and a trial period of one week. We will 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 will provide the ID for each plan. In this example, the Gold Plan's ID will be 111, the Silver Plan's ID will be 222, and the Bronze Plan's ID will be 333. We'll 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 will 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": 2018,
        "securityCode": 837,
        "expirationMonth": "02",
        "cardNumber": 4263982640269299
    }}]},
    "planId": 111
}
{
    "payerInfo": {
        "zip": 67890,
        "firstName": "Betty",
        "lastName": "B",
        "phone": "876-555-4343"
    },
    "paymentSource": {"creditCardInfo": [{"creditCard": {
        "expirationYear": 2018,
        "securityCode": 837,
        "expirationMonth": "02",
        "cardNumber": 4263982640269299
    }}]},
    "planId": 222
}
{
    "payerInfo": {
        "zip": 12345,
        "firstName": "Carla",
        "lastName": "C",
        "phone": "654-333-2222"
    },
    "paymentSource": {"creditCardInfo": [{"creditCard": {
        "expirationYear": 2018,
        "securityCode": 837,
        "expirationMonth": "02",
        "cardNumber": 4263982640269299
    }}]},
    "planId": 333
}

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

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'll 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:

Notes on switching plans

Prorated charges
Because the chargeOnPlanSwitch setting for the Gold Plan is set to true, the Gold Plan price will be charged immediately upon switching the plan, rather than waiting until the next billing period. The amount that was already applied to the previous plan will be 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) will be applied to the charge for the Gold Plan. The Gold Plan price is $100 and the prorated amount deducted is $25, so Betty will be charged $75 at the time of the upgrade.

Trial period skipped
The trial period in the Gold Plan will be 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 will send a Create Subscription request with Daniel's payment information. In the request, you will include the overrideRecurringChargeAmount parameter, with the value set to 40. This will change 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 GET request, to execute the next scheduled subscription event. The execution of this request will trigger the IPN's, emails, and invoices associated with the transaction.

/services/2/subscriptions/subscriptionId/run-specific

The successful response is 204 No Content

Back to Top


Merchant-Managed Subscriptions

If you prefer to manage subscriptions on your side (or through a third party) but process the payments through BlueSnap, you will simply send in each recurring transaction to be processed. More details are provided below for credit card transactions, PayPal, batch processing, and Account Updater (a tool to boost sales by keep shoppers' cards updated).

Processing merchant-managed credit card subscription payments

When you want to process a recurring payment via a credit card, you will send an Auth Capture or Auth Only request by following these steps:

  1. For an initial charge, include the shopper's payment information, and in the recurringTransaction field, enter ECOMMERCE.
  2. For all subsequent charges, enter RECURRING. This means that you will not need to send the CVV of the shopper's card when you send a transaction for processing.

Later on, if you want to change the credit card, start at Step 1 again.

The below examples show Auth Capture requests to process a recurring payment.

{
    "amount": 11,
    "recurringTransaction": "ECOMMERCE",
    "softDescriptor": "DescTest",
    "cardHolderInfo": {
        "firstName": "test first name",
        "lastName": "test last name"
    },
    "currency": "USD",
    "creditCard": {
        "expirationYear": 2018,
        "securityCode": 837,
        "expirationMonth": "02",
        "cardNumber": 4263982640269299
    },
    "cardTransactionType": "AUTH_CAPTURE"
}
{
    "amount": 11,
    "vaultedShopperId": 20769005,
    "recurringTransaction": "RECURRING",
    "softDescriptor": "DescTest",
    "currency": "USD",
    "cardTransactionType": "AUTH_CAPTURE"
}

Processing merchant-managed PayPal subscription payments

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 processes the initial subscription payment, you'll simply mark it as a recurring transaction. Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You will 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

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 will be 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 ID for the new subscription

Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You will 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 will be 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

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 will be similar to the following:

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

Back to Top

Batch processing merchant-managed subscription payments

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.



Back to Top