BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

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. If you include maxNumberOfCharges, please note that this parameter refers to the maximum number of charges after the initial charge.

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

<plan xmlns="http://ws.plimus.com">
   <name>Gold Plan</name>
   <recurring-charge-amount>100</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
</plan>

<plan xmlns="http://ws.plimus.com">
   <name>Silver Plan</name>
   <recurring-charge-amount>50</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
</plan>

<plan xmlns="http://ws.plimus.com">
   <name>Bronze Plan</name>
   <recurring-charge-amount>25</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
</plan>

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:

<recurring-subscription xmlns="http://ws.plimus.com">
   <plan-id>111</plan-id>
   <payer-info>
     <first-name>Allen</first-name>
     <last-name>A</last-name>
     <zip>12345</zip>
     <phone>210-999-0000</phone>
   </payer-info>
   <payment-source>
     <credit-card-info>
       <credit-card>
         <card-number>4263982640269299</card-number>
         <security-code>837</security-code>
         <expiration-month>02</expiration-month>
         <expiration-year>2018</expiration-year>         
       </credit-card>
     </credit-card-info>
   </payment-source>
</recurring-subscription>

<recurring-subscription xmlns="http://ws.plimus.com">
   <plan-id>222</plan-id>
   <payer-info>
     <first-name>Betty</first-name>
     <last-name>B</last-name>
     <zip>67890</zip>
     <phone>876-555-4343</phone>
   </payer-info>
   <payment-source>
     <credit-card-info>
       <credit-card>
         <card-number>4263982640269299</card-number>
         <security-code>837</security-code>
         <expiration-month>02</expiration-month>
         <expiration-year>2018</expiration-year>         
       </credit-card>
     </credit-card-info>
   </payment-source>
</recurring-subscription>

<recurring-subscription xmlns="http://ws.plimus.com">
   <plan-id>333</plan-id>
   <payer-info>
     <first-name>Carla</first-name>
     <last-name>C</last-name>
     <zip>12345</zip>
     <phone>654-333-2222</phone>
   </payer-info>
   <payment-source>
     <credit-card-info>
       <credit-card>
         <card-number>4263982640269299</card-number>
         <security-code>837</security-code>
         <expiration-month>02</expiration-month>
         <expiration-year>2018</expiration-year>         
       </credit-card>
     </credit-card-info>
   </payment-source>
</recurring-subscription>

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.

📘

ACH/ECP & SEPA Direct Debit subscriptions

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

Step 3: Upgrading a subscription

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

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

In the request, we'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:

<recurring-subscription xmlns="http://ws.plimus.com">
   <plan-id>111</plan-id>
</recurring-subscription>

📘

Notes on switching plans

Prorated charges
Because the charge-on-plan-switch 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 override-recurring-charge-amount 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:

<recurring-subscription xmlns="http://ws.plimus.com">
   <plan-id>222</plan-id>
   <override-recurring-charge-amount>40</override-recurring-charge-amount>
   <payer-info>
     <first-name>Daniel</first-name>
     <last-name>D</last-name>
     <zip>54321</zip>
     <phone>555-777-9999</phone>
   </payer-info>
   <payment-source>
     <credit-card-info>
	   <credit-card>
            <card-number>4263982640269299</card-number>
            <security-code>837</security-code>
            <expiration-month>02</expiration-month>
            <expiration-year>2018</expiration-year>         
         </credit-card>
     </credit-card-info>
   </payment-source>
</recurring-subscription>

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:

<plans xmlns="http://ws.plimus.com">
  <last-page>true</last-page>
  <plan>
   <plan-id>333</plan-id>
   <name>Bronze Plan</name>
   <recurring-charge-amount>25</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
   <status>ACTIVE</status>
  </plan>
  <plan>
   <plan-id>222</plan-id>
   <name>Silver Plan</name>
   <recurring-charge-amount>50</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
   <status>ACTIVE</status>
  </plan>
  <plan>
   <plan-id>111</plan-id>
   <name>Gold Plan</name>
   <recurring-charge-amount>100</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
   <status>ACTIVE</status>
  </plan>
</plans>

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:

<recurring-subscriptions xmlns="http://ws.plimus.com">
   <last-page>true</last-page>
      <recurring-subscription>
         <subscription-id>343434</subscription-id>
         <plan-id>111</plan-id>
         <vaulted-shopper-id>7895455</vaulted-shopper-id>
         <status>ACTIVE</status>
         <quantity>1</quantity>
         <soft-descriptor>Merchant Name</soft-descriptor>
         <charge-frequency>MONTHLY</charge-frequency>
         <recurring-charge-amount>100</recurring-charge-amount>
         <currency>USD</currency>
         <trial-period-days>7</trial-period-days>
         <initial-charge-amount>0<initial-charge-amount>
         <auto-renew>true</auto-renew>
         <next-charge-date>2017-07-01</next-charge-date>
         <payer-info>
            <first-name>Betty</first-name>
            <last-name>B</last-name>
            <zip>67890</zip>
            <phone>876-555-4343</phone>
         </payer-info>
         <payment-source>
            <credit-card-info>
               <credit-card>
                  <card-last-four-digits>9299</card-last-four-digits>
                  <card-type>VISA</card-type>
                  <expiration-month>02</expiration-month>
                  <expiration-year>2018</expiration-year>
               </credit-card>
            </credit-card-info>
         </payment-source>
      </recurring-subscription>
      <recurring-subscription>
         <subscription-id>121212</subscription-id>
         <plan-id>111</plan-id>
         <vaulted-shopper-id>7891234</vaulted-shopper-id>
         <status>ACTIVE</status>
         <quantity>1</quantity>
         <soft-descriptor>Merchant Name</soft-descriptor>
         <charge-frequency>MONTHLY</charge-frequency>
         <recurring-charge-amount>100</recurring-charge-amount>
         <currency>USD</currency>
         <trial-period-days>7</trial-period-days>
         <initial-charge-amount>0<initial-charge-amount>
         <auto-renew>true</auto-renew>
         <next-charge-date>2017-07-01</next-charge-date>
         <payer-info>
            <first-name>Allen</first-name>
            <last-name>A</last-name>
            <zip>12345</zip>
            <phone>210-999-0000</phone>
         </payer-info>
         <payment-source>
            <credit-card-info>
               <credit-card>
                  <card-last-four-digits>9299</card-last-four-digits>
                  <card-type>VISA</card-type>
                  <expiration-month>02</expiration-month>
                  <expiration-year>2018</expiration-year>
               </credit-card>
            </credit-card-info>
         </payment-source>
      </recurring-subscription>
</recurring-subscriptions>

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 subscription-id in the following POST 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/recurring/subscriptions/{subscription-id}/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. BlueSnap's built-in support for [Account Updater](https://support.bluesnap.com/docs/account-updater) ensures your shopper's card information is kept up-to-date. It works by automatically updating cards set to expire within a month so you don't lose sales and the shopper continues to enjoy their subscription service.

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

676

For specific details, see:

Processing merchant-managed card and 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 via card or Apple Pay

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

<charge xmlns="http://ws.plimus.com">
  <amount>45</amount>
  <currency>USD</currency>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <zip>12345</zip>
    <country>us</country>
  </payer-info>
  <payment-source>
    <credit-card-info>
      <credit-card>
        <card-number>4012000033330026</card-number>
        <security-code>111</security-code>
        <expiration-month>05</expiration-month>
        <expiration-year>2018</expiration-year>
      </credit-card>
    </credit-card-info>
  </payment-source>
</charge>

<charge xmlns="http://ws.plimus.com">
  <amount>45</amount>
  <currency>USD</currency>
  <paymentSource>
    <wallet>
      <walletType>APPLE_PAY</walletType>
      <encodedPaymentToken>eyJiaWxsaW5nQ29udGFjdCI6eyJhZGRyZ...
      </encodedPaymentToken>
    </wallet>
  </paymentSource>
</charge>'

Step 2: Get the subscription ID

A successful Create Merchant-Managed Subscription response will contain a subscription-id 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: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<charge xmlns="http://ws.plimus.com">
  <charge-id>6198862</charge-id>
  <subscription-id>8129231</subscription-id>
  <vaulted-shopper-id>22220051</vaulted-shopper-id>
  <transaction-id>1011791561</transaction-id>
  <transaction-date>2017-10-12</transaction-date>
  <amount>45.00</amount>
  <currency>USD</currency>
  <soft-descriptor>BLS&#x2a;testing</soft-descriptor>
  <payment-source>
    <credit-card-info>
      <credit-card>
        <card-last-four-digits>0026</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <card-category>CLASSIC</card-category>
        <expiration-month>05</expiration-month>
        <expiration-year>2018</expiration-year>
      </credit-card>
    </credit-card-info>
  </payment-source>
  <charge-info>
    <charge-type>INITIAL</charge-type>
  </charge-info>
</charge>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<charge xmlns="http://ws.plimus.com">
  <chargeId>175047</chargeId>
  <subscriptionId>39555006</subscriptionId>
  <vaultedShopperId>19598228</vaultedShopperId>
  <transactionId>38599972</transactionId>
  <transactionDate>2021-09-16</transactionDate>
  <amount>45</amount>
  <currency>USD</currency>
  <softDescriptor>BLS*CodeDiggers</softDescriptor>
  <paymentSource>
    <wallet>
      <walletType>APPLE_PAY</walletType>
      <billingContactInfo>
        <firstName>John</firstName>
        <lastName>Smith</lastName>
        <address1>800 South Street</address1>
        <city>Waltham</city>
        <state>MA</state>
        <zip>01822</zip>
        <country>us</country>
      </billingContactInfo>
      <applePay>
        <cardLastFourDigits>1471</cardLastFourDigits>
        <cardType>MASTERCARD</cardType>
        <cardSubType>DEBIT</cardSubType>
        <cardCategory>ACQUIRER ONLY</cardCategory>
        <binCategory>CONSUMER</binCategory>
        <cardRegulated>N</cardRegulated>
        <issuingCountryCode>us</issuingCountryCode>
        <issuingBank>MASTERCARD - MEMBER TEST FACILITY</issuingBank>
        <dpanLastFourDigits>6937</dpanLastFourDigits>
        <dpanExpirationMonth>9</dpanExpirationMonth>
        <dpanExpirationYear>2022</dpanExpirationYear>
      </applePay>
      <tokenizedCard>
        <dpanExpirationMonth>9</dpanExpirationMonth>
        <dpanExpirationYear>2022</dpanExpirationYear>
        <dpanLastFourDigits>6937</dpanLastFourDigits>
        <cardLastFourDigits>1471</cardLastFourDigits>
        <cardType>MASTERCARD</cardType>
        <cardSubType>DEBIT</cardSubType>
        <cardCategory>ACQUIRER ONLY</cardCategory>
        <binCategory>CONSUMER</binCategory>
        <cardRegulated>N</cardRegulated>
        <issuingCountryCode>us</issuingCountryCode>
        <issuingBank>MASTERCARD - MEMBER TEST FACILITY</issuingBank>
      </tokenizedCard>
    </wallet>
  </paymentSource>
  <chargeInfo>
    <chargeType>INITIAL</chargeType>
  </chargeInfo>
  <processingInfo>
    <processingStatus>SUCCESS</processingStatus>
    <authorizationCode>732032</authorizationCode>
  </processingInfo>
  <fraudResultInfo/>
</charge>

Step 3: Process recurring payments via card or Apple Pay

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/{subscription-id}
For example:
/services/2/recurring/ondemand/8129231

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

<charge xmlns="http://ws.plimus.com">
  <amount>45</amount>
  <currency>USD</currency>
</charge>

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 ACH and SEPA Direct Debit subscription payments

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

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

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

<charge xmlns="http://ws.plimus.com">
  <amount>65</amount>
  <currency>USD</currency>
  <authorized-by-shopper>true</authorized-by-shopper>
  <payer-info>
    <first-name>Jane</first-name>
    <last-name>Doe</last-name>
    <zip>12345</zip>
    <country>us</country>
  </payer-info>
  <payment-source>
    <ecp-info>
      <ecp>
        <account-number>4099999992</account-number>
        <routing-number>011075150</routing-number>
        <account-type>CONSUMER_CHECKING</account-type>
      </ecp>
    </ecp-info>
  </payment-source>
</charge>

<charge xmlns="http://ws.plimus.com">
  <amount>45</amount>
  <currency>EUR</currency>
  <authorized-by-shopper>true</authorized-by-shopper>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <zip>12345</zip>
    <country>fr</country>
  </payer-info>
  <payment-source>
    <sepa-direct-debit-info>
      <sepa-direct-debit>
        <iban>DE09100100101234567893</iban>
      </sepa-direct-debit>
    </sepa-direct-debit-info>
  </payment-source>
</charge>

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 subscription ID within 2 - 6 business days

Within 2 - 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 subscription-id property.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<charge xmlns="http://ws.plimus.com">
  <charge-id>13212679</charge-id>
  <subscription-id>10942779</subscription-id>
  <vaulted-shopper-id>22331737</vaulted-shopper-id>
  <transaction-id>1015615791</transaction-id>
  <transaction-date>2018-01-26</transaction-date>
  <amount>65.00</amount>
  <currency>USD</currency>
  <soft-descriptor>default_descriptor</soft-descriptor>
  <payment-source>
    <ecp-info>
      <ecp>
        <account-number>4099999992</account-number>
        <routing-number>011075150</routing-number>
        <account-type>CONSUMER_CHECKING</account-type>
      </ecp>
    </ecp-info>
  </payment-source>
  <charge-info>
    <charge-type>INITIAL</charge-type>
  </charge-info>
  <processing-info>
    <processing-status>SUCCESS</processing-status>
  </processing-info>
</charge>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<charge xmlns="http://ws.plimus.com">
  <charge-id>6198866</charge-id>
  <subscription-id>8129239</subscription-id>
  <vaulted-shopper-id>22220063</vaulted-shopper-id>
  <transaction-id>1011791571</transaction-id>
  <transaction-date>2017-10-12</transaction-date>
  <amount>45.00</amount>
  <currency>EUR</currency>
  <soft-descriptor>BLS&#x2a;testing</soft-descriptor>
  <payment-source>
    <sepa-direct-debit-info>
      <sepa-direct-debit>
        <iban-first-four>DE09</iban-first-four>
        <iban-last-four>7893</iban-last-four>
        <mandate-id>Sep165925</mandate-id>
        <mandate-date>12-Oct-17</mandate-date>
      </sepa-direct-debit>
    </sepa-direct-debit-info>
  </payment-source>
  <charge-info>
    <charge-type>INITIAL</charge-type>
  </charge-info>
  <processing-info>
    <processing-status>SUCCESS</processing-status>
  </processing-info>
</charge>

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

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

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

<charge xmlns="http://ws.plimus.com">
  <amount>65</amount>
  <currency>USD</currency>
</charge>

<charge xmlns="http://ws.plimus.com">
  <amount>45</amount>
  <currency>EUR</currency>
</charge>

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 2 - 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 process 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 via PayPal

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

<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <merchant-transaction-id>A3bn43</merchant-transaction-id>
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
   </payer-info>
   <paypal-transaction>
      <return-url>http://www.returnURL.com</return-url>
      <cancel-url>http://www.cancelURL.com</cancel-url>
      <recurring>1</recurring>
   </paypal-transaction>
</alt-transaction>

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

<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
   </payer-info>
   <paypal-transaction>
     <paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout</paypal-url>
     <order-id>980111</order-id>
   </paypal-transaction>
   <processing-info>
      <status>PENDING</processing-info>
</alt-transaction>

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

Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. You 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 paypal-subscription-id in the paypal-transaction element:
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <transaction-id>38500786</transaction-id>
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
   </payer-info>
   <paypal-transaction>
      <paypal-url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout</paypal-url>
      <paypal-subscription-id>1234567</paypal-subscription-id>
      <order-id>980111</order-id>
   </paypal-transaction>
   <processing-info>
      <status>SUCCESS</status>
   </processing-info>
</alt-transaction>

Step 3: Process recurring payments via PayPal

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

<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <amount>100.00</amount>
   <currency>USD</currency>
   <paypal-transaction>
      <paypal-subscription-id>1234567</paypal-subscription-id>
   </paypal-transaction>
</alt-transaction>

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

<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <transaction-id>38500786</transaction-id>
   <amount>100.00</amount>
   <currency>USD</currency>
   <paypal-transaction>
      <paypal-subscription-id>1234567</paypal-subscription-id>
   </paypal-transaction>
   <processing-info>
      <status>SUCCESS</processing-info>
</alt-transaction>

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