Working with BlueSnap Vaulted Shoppers

The E-Payment Integrator's RecurringBilling component allows you to work with BlueSnap vaulted shoppers.

Date Entered: 08/31/2017    Last Updated: 08/31/2017

The E-Payment Integrator's RecurringBilling component is used to interact with the BlueSnap vaulted shopper API, which allows you to easily manage use-cases involving returning shoppers. This article will break down all of the details on how best to leverage the RecurringBilling component to work with vaulted shoppers.

This article references a number of properties, methods, and configuration settings on the RecurringBilling component. Please be sure you have access to the latest E-Payment Integrator documentation for your platform, which can be found here on our site.

It is assumed that you have already reviewed the BlueSnap section of the "RecurringBilling Gateway Setup and Required Properties" page in the documentation, and therefore know the basics of setting up the RecurringBilling component for use with the BlueSnap gateway.

The code snippets shown in this article are written in C#, but the concepts apply to any platform. Additionally, they assume that this function is available:

GetSpecialFieldValue() Function (C#) public string GetSpecialFieldValue(Recurringbilling rb, string name) { foreach (var sf in rb.SpecialFields) if (sf.Name == name) return sf.Value; return ""; }


Table of Contents:

The BlueSnapRequestType Configuration Setting

The RecurringBilling component splits up different vaulted shopper requests into a handful of different types, and the BlueSnapRequestType configuration setting is used to control what each call to either CreateSubscription(), GetSubscriptionStatus(), or UpdateSubscription() does.

Each time you set this configuration setting, the component will automatically reset all of its properties, special fields, and configuration settings listed in the field mapping tables to their default values.

Request Type Description
0 Create vaulted shopper with basic information
1 Retrieve/Update basic vaulted shopper information
2 Retrieve/Add/Update a Card payment source
3 Retrieve/Update the ECheck payment source

The default value is 0, which is the only valid request type when calling CreateSubscription().

The other request types require you to set the Vaulted Shopper ID via the BlueSnapVaultedShopperId configuration setting, after which you may use GetSubscriptionStatus() and UpdateSubscription() to retrieve and add/update vaulted shopper data.

Creating a New Vaulted Shopper

Creating a new vaulted shopper is simple:

  1. Set BlueSnapRequestType to 0.
  2. Set the desired BlueSnap fields using the RecurringBilling equivalents listed in the first field mapping table.
  3. Call CreateSubscription(). If the request is successful, the new vaulted shopper's ID can be retrieved from the BlueSnapVaultedShopperId configuration setting.

Example Code Snippet (C#) // Set BlueSnapRequestType. rb.Config("BlueSnapRequestType=0"); // Set basic information. rb.Customer.Id = "TEST_SHOPPER"; rb.Customer.FirstName = "Ellen"; rb.Customer.LastName = "Johnson"; rb.Customer.Address = "14 Main Street"; rb.Customer.Address2 = "Apt. 54"; rb.Customer.City = "Pecan Springs"; rb.Customer.State = "TX"; rb.Customer.Zip = "46225"; rb.Customer.Country = "US"; rb.Customer.Phone = "123-456-7890"; rb.Customer.Email = "nobody@server.com"; rb.ShippingInfo.FirstName = "Joe"; rb.ShippingInfo.LastName = "Schmo"; rb.ShippingInfo.Address = "1st St."; rb.ShippingInfo.Address2 = "F9"; rb.ShippingInfo.City = "1st City"; rb.ShippingInfo.State = "NC"; rb.ShippingInfo.Zip = "98765"; rb.ShippingInfo.Country = "us"; rb.AddSpecialField("walletId", "345"); // Create the new vaulted shopper. (The method parameter is ignored.) rb.CreateSubscription(""); // Assuming that Response.Approved is 'true', the request succeeded, print out the new // vaulted shopper ID. Console.WriteLine("Vaulted Shopper Id = " + rb.Config("BlueSnapVaultedShopperId"));


Basic Vaulted Shopper Information

A vaulted shopper can have a variety of basic information associated with them, such as their name, billing and/or shipping information, and more. If you want to retrieve, and possibly update, a vaulted shopper's basic information, you'll need to:

  1. Set BlueSnapRequestType to 1.
  2. Set the BlueSnapVaultedShopperId configuration setting.
  3. Call GetSubscriptionStatus() to retrieve the latest basic information for the vaulted shopper and populate the component with it.
  4. Modify any values you wish to change (refer to the first field mapping table).
  5. Call UpdateSubscription() to send the updated basic vaulted shopper information.

Please note that any basic information you don't send in an update request will automatically be cleared by BlueSnap.

Example Code Snippet (C#) // Set BlueSnapRequestType and BlueSnapVaultedShopperId. rb.Config("BlueSnapRequestType=1"); rb.Config("BlueSnapVaultedShopperId=123456789"); // Retrieve the latest basic vaulted shopper information. (The method parameter is ignored.) rb.GetSubscriptionStatus(""); // Assuming that Response.Approved is 'true', the retrieve request succeesed, and the // component's fields will now be populated. Let's print out a few things. Console.WriteLine("For vaulted shopper ID 123456789:"); Console.WriteLine("First Name: " + rb.Customer.FirstName); Console.WriteLine("Last Name: " + rb.Customer.LastName); // Note that BlueSnap's server XML-encodes certain characters; e.g., '@' becomes "@". Console.WriteLine("Email Address: " + System.Net.WebUtility.HtmlDecode(rb.Customer.Email)); // Now, let's update some fields. rb.ShippingInfo.FirstName = "Arnold"; rb.ShippingInfo.LastName = "Tester"; rb.ShippingInfo.Address = "987 Last Ln."; rb.ShippingInfo.Address2 = ""; rb.ShippingInfo.City = "Some City"; rb.ShippingInfo.State = "GA"; rb.ShippingInfo.Zip = "12345"; // And now, we send the update request. (The method parameter is ignored.) rb.UpdateSubscription(""); if (rb.Response.Approved) Console.WriteLine("Updated!"); else Console.WriteLine("Update failed.");


Card Payment Sources

Vaulted shoppers can have multiple card payment sources configured, and your first step in working with them should always be to retrieve the latest information:

  1. Set BlueSnapRequestType to 2.
  2. Set the BlueSnapVaultedShopperId configuration setting.
  3. Call GetSubscriptionStatus() to retrieve and populate the component with the latest card payment sources for the vaulted shopper (refer to the second field mapping table).

At this point, the component will be populated with the card and billing information for the first card payment source returned in the respose, and the BlueSnapCardIndex configuration setting will be set to 0 (unless there are no pre-existing card payment sources, in which case no fields will have been populated, and BlueSnapCardIndex will be -1).

You can now query the BlueSnapCardCount configuration setting to determine how many card payment sources the vaulted shopper currently has, and then use BlueSnapCardIndex to change which one's information the component is currently populated with.

To add a new card payment source (after retrieving):

  1. Set BlueSnapCardIndex to -1, which will cause the component to reset the populated fields to their default values.
  2. Set the card and billing information for the new card payment source (refer to the second field mapping table).
  3. Call UpdateSubscription() to send the new card payment source. Be sure to check the Response.CVVResult and Response.AVSResult properties afterwards.
  4. Call GetSubscriptionStatus() so that the component has the latest information again.

To update an existing card payment source (after retrieving):

  1. Set BlueSnapCardIndex to the desired card's index so that the component is populated with its information.
  2. Modify the card expiration date or billing information as desired.
  3. Set the full card number and security code.
  4. Call UpdateSubscription() to send the updated card payment source. Be sure to check the Response.CVVResult and Response.AVSResult properties afterwards.
  5. Call GetSubscriptionStatus() so that the component has the latest information again.

That covers the basics of how to work with vaulted shoppers' card payment sources, but be sure to keep the following things in mind:

  • BlueSnap does not guarantee that a vaulted shopper's various card payment sources will be returned in the same order between requests. This is why it is important to retrieve the latest information both before you do anything involving card payment sources, and immediately after you add or update a card payment source.
  • For security reasons, BlueSnap only returns a card's last four digits and type (Visa, MasterCard, etc.) when you retrieve card payment source information.
  • Failing to specify the full card number and security code when updating a card will cause your update request to fail.
  • When adding a new card payment source, you can choose not to send explicit billing information, BlueSnap will automatically fill the required fields based on the vaulted shopper's basic information.
  • Similarly, billing information fields you don't specify when updating a card payment source will be automatically cleared if not required, or automatically filled based on the vaulted shopper's basic information if required.

Example Code Snippet (C#) // Set BlueSnapRequestType and BlueSnapVaultedShopperId. rb.Config("BlueSnapRequestType=2"); rb.Config("BlueSnapVaultedShopperId=123456789"); // Retrieve the latest card payment sources. (The method parameter is ignored.) rb.GetSubscriptionStatus(""); // Iterate over the existing cards (if there are any). int cardCount = rb.Config("BlueSnapCardCount"); for (int i = 0; i < cardCount; i++) { rb.Config("BlueSnapCardIndex=" + i); Console.WriteLine("Card at index " + i + ":"); Console.WriteLine("First Name: " + rb.Customer.FirstName); Console.WriteLine("Last Name: " + rb.Customer.LastName); Console.WriteLine("Card's Last 4 Digits: " + GetSpecialFieldValue(rb, "cardLastFourDigits")); Console.WriteLine("Card Type: " + rb.Config("CardType")); } // Let's add a new card. Set BlueSnapCardIndex to -1 to clear the currently populated fields. rb.Config("BlueSnapCardIndex=-1"); // Now fill in new card information. rb.Card.Number = "4111111111111111"; rb.Card.ExpMonth = 9; rb.Card.ExpYear = 2021; rb.Card.CVVData = "999"; // And card billing information (just the name, in this case). rb.Customer.FirstName = "Alexis"; rb.Customer.LastName = "Johnson"; // Adding/updating a card causes BlueSnap to do a $0.00 AUTH against it, so we'll specify a // soft descriptor that will show up on the customer's card statement. rb.AddSpecialField("softDescriptor", "TestAddCard"); // Now add the card. (The method parameter is ignored.) rb.UpdateSubscription(""); // Assuming Response.Approved is 'true', you should now check the return values of the // Response.CVVResult and Response.AVSResult properties. See the documentation for details. // Now, do a retrieve to make sure we have the latest card payment sources again. rb.GetSubscriptionStatus(""). // You'd want to iterate through the cards again now, BlueSnap doesn't guarantee that the // order they are returned in will remain the same between requests. // Now, assume we have an expired card at BlueSnapCardIndex==2, let's update it. // First, set BlueSnapCardIndex to populate the component with the card and billing info. rb.Config("BlueSnapCardIndex=2"); // Set the new expiration date. rb.Card.ExpMonth = 12; rb.Card.ExpYear = 24; // Be sure to specify the card's full number and security code, or the update request will fail. rb.Card.Number = "6011000000000012"; rb.Card.Number = 555; // Update the card now. rb.UpdateSubscription(""); // Assuming Response.Approved is 'true', you should again check the return values of the // Response.CVVResult and Response.AVSResult properties. See the documentation for details. // Now, do a retrieve to make sure we have the latest card payment sources again. rb.GetSubscriptionStatus("").


The ECheck Payment Source

A vaulted shopper can have a single ECheck payment source configured. An ECheck payment source consists of bank account information, a company name (for business accounts), and billing information. You can retrieve, and then add/update, that ECheck payment source by doing the following:

  1. Set BlueSnapRequestType to 3.
  2. Set the BlueSnapVaultedShopperId configuration setting.
  3. Call GetSubscriptionStatus() to retrieve the latest ECheck payment source information for the vaulted shopper and populate the component with it.
  4. Set/Modify any values you wish to add/change (refer to the second field mapping table). Note that if you don't send billing information, BlueSnap will automatically fill the required fields (and clear any unnecessary pre-existing fields) using the vaulted shopper's basic information.
  5. Call UpdateSubscription() to send the ECheck payment source information.

Example Code Snippet (C#) // Set BlueSnapRequestType and BlueSnapVaultedShopperId. rb.Config("BlueSnapRequestType=3"); rb.Config("BlueSnapVaultedShopperId=123456789"); // Retrieve the latest ECheck payment source. (The method parameter is ignored.) rb.GetSubscriptionStatus(""); // If there is a currently configured ECheck payment source, you can inspect it. if (rb.ECheckBank.AccountNumber != "") { Console.WriteLine("ECheck account info:"); Console.WriteLine("Account #: " + rb.ECheckBank.AccountNumber); Console.WriteLine("Routing #: " + rb.ECheckBank.RoutingNumber); Console.WriteLine("Account Type: " + (rb.ECheckBank.AccountType == AccountTypes.atChecking ? "Checking" : "Savings")); Console.WriteLine("Account Class: " + (rb.ECheckBank.AccountClass == AccountClass.acPersonal ? "Personal" : "Business")); } // Let's set up an ECheck payment source. Since you can only configure one ECheck payment // source, adding/updating is essentially the same thing. // (Tip: To start with a blank slate when updating the ECheck payment source, just set // BlueSnapRequestType to 3 again, since setting that config resets the populated fields.) // Fill in the fields. rb.ECheckBank.AccountNumber = "0123456789"; rb.ECheckBank.RoutingNumber = "021000021"; rb.ECheckBank.AccountType = AccountTypes.atChecking; rb.ECheckBank.AccountClass = AccountClass.acBusiness; // We'll forego setting billing information, BlueSnap will pull what it needs from our // pre-existing basic information. // For business accounts, you have to specify a company name. rb.Config("CompanyName=Test Company"); // Now send the add/update request. (The method parameter is ignored.) rb.UpdateSubscription("");


RecurringBilling Equivalents of BlueSnap Fields

The following tables show the RecurringBilling equivalents of the currently supported* BlueSnap JSON API fields.

When Creating, Retrieving, or Updating a Vaulted Shopper's Basic Information:

BlueSnap Field Name RecurringBilling Equivalent
address, address2, city, country, email, firstName,
lastName, merchantShopperId, phone, state, and zip fields
Customer property.
companyName CompanyName configuration setting.
personalIdentificationNumber Special field personalIdentificationNumber.
shippingContactInfo object fields ShippingInfo property.
shopperCurrency CurrencyCode configuration setting.
vendorInfo object fields Special fields vendorId, commissionPercent, and commissionAmount.
walletId Special field walletId.

When Adding, Retrieving, or Updating a Payment Source for a BlueSnap Vaulted Shopper:

BlueSnap Field Name RecurringBilling Equivalent
paymentSources.creditCardInfo.creditCard object fields Card property, or special field cardLastFourDigits and the CardType configuration setting. (If you wish to send encrypted card number and security code data, set the ValidateCardNumber configuration setting to False first.)
paymentSources.creditCardInfo.pfToken Special field pfToken.
paymentSources.ecpInfo.ecp object fields AccountNumber, RoutingNumber, AccountClass, and AccountType properties.
paymentSources.creditCardInfo.billingContactInfo or
paymentSources.ecpInfo.billingContactInfo object fields
Customer property, and special field personalIdentificationNumber.
softDescriptor (when adding/updating a card) Special field softDescriptor.
transactionFraudInfo object fields Special fields fraudSessionId, company, and enterpriseSiteId; and the PayerIP configuration setting.
transactionFraudInfo.enterpriseUdfs content BlueSnapEnterpriseUdfs configuration setting.
transactionFraudInfo.shippingContactInfo object fields ShippingInfo property.

*Please refer to the BlueSnap section of the "RecurringBilling Gateway Setup and Required Properties" page in the documentation for the most up-to-date tables


We appreciate your feedback.  If you have any questions, comments, or suggestions about this entry please contact our support team at kb@nsoftware.com.