{"_id":"59dfa5838b51880010b74ad8","category":{"_id":"59dfa5828b51880010b74ac4","version":"59dfa5828b51880010b74ab6","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":"59dfa5828b51880010b74ab6","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-10-12T17:25:22.850Z","releaseDate":"2017-10-12T17:25:22.850Z","categories":["59dfa5828b51880010b74ab7","59dfa5828b51880010b74ab8","59dfa5828b51880010b74ab9","59dfa5828b51880010b74aba","59dfa5828b51880010b74abb","59dfa5828b51880010b74abc","59dfa5828b51880010b74abd","59dfa5828b51880010b74abe","59dfa5828b51880010b74abf","59dfa5828b51880010b74ac0","59dfa5828b51880010b74ac1","59dfa5828b51880010b74ac2","59dfa5828b51880010b74ac3","59dfa5828b51880010b74ac4","59dfa5828b51880010b74ac5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.23 Release","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":17,"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**Note:** For SEPA Direct Debit payments, the subscription ID is created once the payment has been processed (typically within 5 - 6 business days). See [Create Subscription](doc:create-subscription#section-create-subscription-with-sepa-direct-debit) for more details.\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 simulate a subscription event. The execution of this request will trigger the IPNs, emails, and invoices associated with the transaction.\n\n**Note**: This request does not impact subscription dates, meaning time-sensitive properties, such as grace period, are not simulated.  \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.\n\nThe flow for processing your own subscriptions consists of three primary steps:\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]\nFor specific details, see: \n  * [Processing merchant-managed credit card or Apple Pay subscription payments](#section-processing-merchant-managed-credit-card-or-apple-pay-subscription-payments)\n  * [Processing  merchant-managed SEPA Direct Debit subscription payments](#section-processing-merchant-managed-sepa-direct-debit-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 or Apple Pay subscription payments\nIf  you want to process merchant-managed subscription payments for credit cards or Apple Pay, then follow these steps: \n\n### Step 1: Process initial subscription payment\nTo process the initial subscription charge, send a [Create Merchant-Managed Subscription](doc:create-merchant-managed-subscription) request with the shopper's information and charge details.  For example: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"payerInfo\\\": {\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"country\\\": \\\"us\\\"\\n  },\\n  \\\"paymentSource\\\": {\\n    \\\"creditCardInfo\\\": {\\n      \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 111,\\n        \\\"expirationMonth\\\": \\\"05\\\",\\n        \\\"cardNumber\\\": 4012000033330026\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Initial subscription payment via credit card\"\n    },\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\", \\n  \\\"paymentSource\\\": {\\n    \\\"wallet\\\": {\\n      \\\"applePay\\\": {\\n        \\\"encodedPaymentToken\\\": \\\"eyJ0b2tliZ2l2ZW5OYW1lIjoiTG9kIiwiY291bnRye…\\\"\\n      }\\n    }\\n  }\\t\\n}\",\n      \"language\": \"json\",\n      \"name\": \"via Apple Pay\"\n    }\n  ]\n}\n[/block]\n### Step 2: Get the ID for the new subscription \nA successful Create Merchant-Managed Subscription response will contain a `subscriptionId` property, whose value is a unique ID that BlueSnap assigns to the subscription. You will use this subscription ID to process recurring payments and associate them to the correct subscription. For example: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"chargeId\\\": 12947185,\\n  \\\"subscriptionId\\\": 10541275,\\n  \\\"vaultedShopperId\\\": 22192749,\\n  \\\"transactionId\\\": \\\"1015006793\\\",\\n  \\\"transactionDate\\\": \\\"2017-10-30\\\",\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"softDescriptor\\\": \\\"BLS&#x2a;Testing\\\",\\n  \\\"paymentSource\\\": {\\n    \\\"creditCardInfo\\\": {\\n      \\\"creditCard\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"0026\\\",\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"cardSubType\\\": \\\"CREDIT\\\",\\n        \\\"cardCategory\\\": \\\"CLASSIC\\\",\\n        \\\"expirationMonth\\\": \\\"05\\\",\\n        \\\"expirationYear\\\": \\\"2018\\\"\\n      }\\n    }\\n  },\\n  \\\"chargeInfo\\\": {\\n    \\\"chargeType\\\": \\\"INITIAL\\\"\\n  },\\n  \\\"processingInfo\\\": {\\n    \\\"processingStatus\\\": \\\"SUCCESS\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response to initial subscription payment via credit card\"\n    },\n    {\n      \"code\": \"{\\n  \\\"chargeId\\\": \\\"165323\\\",\\n  \\\"subscriptionId\\\": 39518448,\\n  \\\"vaultedShopperId\\\": 19559630,\\n  \\\"transactionId\\\": \\\"38492608\\\",\\n  \\\"transactionDate\\\": \\\"2017-10-13\\\",\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"softDescriptor\\\": \\\"BLS*Testing\\\",\\n  \\\"paymentSource\\\": {\\n    \\\"wallet\\\": {\\n      \\\"billingContactInfo\\\": {\\n        \\\"firstName\\\": \\\"Jane\\\",\\n        \\\"lastName\\\": \\\"Shopper\\\",\\n        \\\"address1\\\": \\\"800 South St\\\",\\n        \\\"city\\\": \\\"Waltham\\\",\\n        \\\"zip\\\": \\\"02453\\\",\\n        \\\"country\\\": \\\"us\\\"\\n      },\\n      \\\"applePay\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"0492\\\",\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"cardSubType\\\": \\\"DEBIT\\\",\\n        \\\"dpanLastFourDigits\\\": \\\"6889\\\",\\n        \\\"dpanExpirationMonth\\\": \\\"11\\\",\\n        \\\"dpanExpirationYear\\\": \\\"2025\\\"\\n      }\\n    }\\n  },\\n  \\\"chargeInfo\\\": {\\n    \\\"chargeType\\\": \\\"INITIAL\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"via Apple Pay\"\n    }\n  ]\n}\n[/block]\n### Step 3: Process recurring payments\nYou can then process recurring payments by sending a [Create Merchant-Managed Subscription Charge](doc: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}`\nFor example: \n`/services/2/recurring/ondemand/10541275`\n\nAdditionally, include the charge details in the request body. For example: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Recurring subscription payment via credit card or Apple Pay\"\n    }\n  ]\n}\n[/block]\nA successful response will have HTTP status code 200 OK. To view request and response examples, see [Create Merchant-Managed Subscription Charge](doc:create-merchant-managed-subscription-charge).\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n## Processing merchant-managed SEPA Direct Debit subscription payments\nIf  you want to process merchant-managed subscription payments for SEPA Direct Debit, then follow the steps in this section. Please note that SEPA Direct Debit must first be enabled for your account by contacting [Merchant Support](mailto:merchants:::at:::bluesnap.com).  \n\n### Step 1: Process initial subscription payment\nTo process the initial subscription charge, send a [Create Merchant-Managed Subscription](doc:create-merchant-managed-subscription) request with the shopper's information and charge details. For example: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"EUR\\\",\\n  \\\"authorizedByShopper\\\": true,\\n  \\\"payerInfo\\\": {\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"country\\\": \\\"fr\\\"\\n  },\\n  \\\"paymentSource\\\": {\\n    \\\"sepaDirectDebitInfo\\\": {\\n      \\\"sepaDirectDebit\\\": {\\n        \\\"iban\\\": \\\"DE09100100101234567893\\\"\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Initial subscription payment via SEPA Direct Debit\"\n    }\n  ]\n}\n[/block]\nA successful response will have HTTP status code 200 OK. To view request and response examples, see [Create Merchant-Managed Subscription](doc:create-merchant-managed-subscription).\n\n### Step 2: Get the ID for the new subscription\nWithin 5 - 6 business days, the initial payment will be processed and BlueSnap will assign 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 Specific Charge](doc:retrieve-specific-charge) request once the payment has been processed. If the request is successful, the response will be similar to the following, with the `subscriptionId` property.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"chargeId\\\": 12947225,\\n  \\\"subscriptionId\\\": 10541329,\\n  \\\"vaultedShopperId\\\": 22192833,\\n  \\\"transactionId\\\": \\\"1015006899\\\",\\n  \\\"transactionDate\\\": \\\"2017-10-30\\\",\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"EUR\\\",\\n  \\\"softDescriptor\\\": \\\"Testing\\\",\\n  \\\"paymentSource\\\": {\\n    \\\"sepaDirectDebitInfo\\\": {\\n      \\\"sepaDirectDebit\\\": {\\n        \\\"ibanFirstFour\\\": \\\"DE09\\\",\\n        \\\"ibanLastFour\\\": \\\"7893\\\",\\n        \\\"mandateId\\\": \\\"Jan153537\\\",\\n        \\\"mandateDate\\\": \\\"30-Oct-17\\\"\\n      }\\n    }\\n  },\\n  \\\"chargeInfo\\\": {\\n    \\\"chargeType\\\": \\\"INITIAL\\\"\\n  },\\n  \\\"processingInfo\\\": {\\n    \\\"processingStatus\\\": \\\"SUCCESS\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response to Retrieve Specific Charge request\"\n    }\n  ]\n}\n[/block]\n### Step 3: Process recurring payments\nYou can then process recurring payments by sending a [Create Merchant-Managed Subscription Charge](doc: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}`\nFor example: \n`/services/2/recurring/ondemand/10541329`\n\nAdditionally, include the charge details in the request body. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"EUR\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Recurring subscription payment via SEPA Direct Debit\"\n    }\n  ]\n}\n[/block]\nA successful response will have HTTP status code 200 OK and the payment will be in pending status. To view request and response examples, see [Create Merchant-Managed Subscription Charge](doc:create-merchant-managed-subscription-charge). Within 5 - 6 business days, the payment will either be approved or declined. If it's approved, the shopper will be charged and a Charge IPN will be sent to notify you of the successful transaction. You can also retrieve the payment status via the [Retrieve Specific Charge](doc:retrieve-specific-charge) request. \n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\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: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.

Note: For SEPA Direct Debit payments, the subscription ID is created once the payment has been processed (typically within 5 - 6 business days). See Create Subscription for more details.

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 simulate a subscription event. The execution of this request will trigger the IPNs, emails, and invoices associated with the transaction.

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

/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.

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

For specific details, see:

Processing merchant-managed credit card or Apple Pay subscription payments

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

Step 1: Process initial subscription payment

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": {
      "applePay": {
        "encodedPaymentToken": "eyJ0b2tliZ2l2ZW5OYW1lIjoiTG9kIiwiY291bnRye…"
      }
    }
  }	
}

Step 2: Get the ID for the new subscription

A successful Create Merchant-Managed Subscription response will contain a subscriptionId property, whose value is a unique ID that BlueSnap assigns to the subscription. You will 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&#x2a;Testing",
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "cardLastFourDigits": "0026",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "CLASSIC",
        "expirationMonth": "05",
        "expirationYear": "2018"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  },
  "processingInfo": {
    "processingStatus": "SUCCESS"
  }
}
{
  "chargeId": "165323",
  "subscriptionId": 39518448,
  "vaultedShopperId": 19559630,
  "transactionId": "38492608",
  "transactionDate": "2017-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"
      },
      "applePay": {
        "cardLastFourDigits": "0492",
        "cardType": "VISA",
        "cardSubType": "DEBIT",
        "dpanLastFourDigits": "6889",
        "dpanExpirationMonth": "11",
        "dpanExpirationYear": "2025"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  }
}

Step 3: Process recurring payments

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:

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

Back to Top

Processing merchant-managed SEPA Direct Debit subscription payments

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

Step 1: Process initial subscription payment

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": "EUR",
  "authorizedByShopper": true,
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "fr"
  },
  "paymentSource": {
    "sepaDirectDebitInfo": {
      "sepaDirectDebit": {
        "iban": "DE09100100101234567893"
      }
    }
  }
}

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

Step 2: Get the ID for the new subscription

Within 5 - 6 business days, the initial payment will be processed and BlueSnap will assign 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 Specific Charge request once the payment has been processed. If the request is successful, the response will be similar to the following, with the subscriptionId property.
{
  "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

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": 45, 
  "currency": "EUR"
}

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

Back to Top

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