Create Vaulted Shopper

To securely store your shopper's payment details in BlueSnap, you will perform the Create Vaulted Shopper request and BlueSnap will provide a BlueSnap token (vaulted-shopper-id) for that saved shopper.

You can then use the BlueSnap token in order to complete payment transactions, run subscriptions, improve the checkout experience for a returning shopper, and update the shopper's payment details. To see an example using the BlueSnap token for a returning shopper, see Returning Shoppers Guide.

Keep in mind:

  • Each vaulted shopper can have multiple credit cards and multiple ACH accounts.
  • If you add a credit card to a vaulted shopper, BlueSnap will validate the card before adding it to the shopper.
  • To create a shopper with wallet details for Masterpass or Visa Checkout, including the payment info and billing and shipping info, you will simply include the walletId in the request. For details, see:

πŸ“˜

Tip

You can test out a request that hits our sandbox in real-time. Follow the instructions here to use the "Try It!" feature on the right side.

Request Content

Send a vaulted-shopper object with the following:

PropertyTypeRequired
payment-sourcescontaineroptional (see payment-sources)
first-namestringoptional
last-namestringoptional
soft-descriptorstringOptional. If this is not passed when ACH/ECP is a payment source, it will default to the company name (which should be less than 20 characters).
descriptor-phone-numberstringoptional
merchant-shopper-idstringoptional
countrystringoptional
statestringoptional
citystringoptional
addressstringoptional
address2stringoptional
emailstringoptional
zipstringoptional
phonestringoptional
company-namestringrequired for Corporate ECP accounts
shopper-currencystringoptional
shipping-contact-infocontaineroptional (see shipping-contact-info)
wallet-idlongoptional, include if adding Masterpass or Visa Checkout wallet details
transaction-fraud-infocontaineroptional (see transaction-fraud-info)
transaction-order-sourcestringoptional
three-d-securecontaineroptional (see three-d-secure)

Response Details

The response content depends on which version of the API you are using (see Authentication & headers), as follows:

  • API version 3.0
    If successful, the response HTTP status code is 200 OK.
    If you use ACH/ECP, the response includes the ecp-details container, which replaces the ecp-info resource, allowing for multiple ACH accounts to be stored for the shopper.

  • API version 2.0
    If successful, the response HTTP status code is 200 OK.
    The response body includes the vaulted-shopper resource, which contains all details saved for that shopper.
    The vaulted-shopper-id appears in the response body, as well as in the URL in the location header. In the example below, the vaulted-shopper-id is 20848977.

  • API version 1.0
    If successful, the response HTTP status code is 201 Created.
    The vaulted-shopper-id appears in the URL in the location header. In the example below, the vaulted-shopper-id is 19549020.
    There is no content in the response body.

Back to Top


Examples

Request Examples

For API Version 3.0

curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <country>us</country>
   <descriptor-phone-number>5121231212</descriptor-phone-number>
   <zip>02453</zip>
   <phone>1234567890</phone>
   <merchant-shopper-id>6783334400</merchant-shopper-id>
   <payment-sources>
        <credit-card-info>
         <credit-card>
            <card-number>3411 1159 7241 002</card-number>
            <security-code>1121</security-code>
            <expiration-month>07</expiration-month>
            <expiration-year>2023</expiration-year>
         </credit-card>
      </credit-card-info>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <payment-sources>
      <credit-card-info>
         <credit-card>
            <card-number>4263982640269299</card-number>
            <security-code>837</security-code>
            <expiration-month>02</expiration-month>
            <expiration-year>2023</expiration-year>
         </credit-card>
         <billing-contact-info>
            <first-name>billingFirstName</first-name>
            <last-name>billingLastName</last-name>
            <country>US</country>
            <state>MA</state>
            <address1>10 Main St</address1>
            <address2>Apt 1</address2>
            <zip>02453</zip>
         </billing-contact-info>
      </credit-card-info>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <payment-sources>
      <credit-card-info>
         <credit-card>
            <card-number>4263982640269299</card-number>
            <security-code>837</security-code>
            <expiration-month>02</expiration-month>
            <expiration-year>2023</expiration-year>
         </credit-card>
         <billing-contact-info>
            <first-name>billingFirstName</first-name>
            <last-name>billingLastName</last-name>
            <country>US</country>
            <state>MA</state>
            <address1>10 Main St</address1>
            <address2>Apt 1</address2>
            <zip>02453</zip>
         </billing-contact-info>
      </credit-card-info>
   </payment-sources>
   <transaction-fraud-info>
      <fraud-session-id>1234</fraud-session-id>
      <shopper-ip-address>123.12.134.1</shopper-ip-address>
      <company>company</company>
      <shipping-contact-info>
         <last-name>shippingFirstName</last-name>
         <first-name>shippingLastName</first-name>
         <country>US</country>
         <state>AL</state>
         <city>shippingCity</city>
         <address1>shippingAddress1</address1>
         <address2>shippingAddress2</address2>
         <zip>02453</zip>
      </shipping-contact-info>
   </transaction-fraud-info>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
   <wallet-id>21</wallet-id>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <payment-sources>
      <credit-card-info>
            <pf-token>9688f4f6945f615b1ab6954ceb5dbf67f63d6b41fa27dbff6ac342cff9bf50fc_</pf-token>
      </credit-card-info>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <soft-descriptor>MYCOMPANY</soft-descriptor>
   <payment-sources>
      <credit-card-info>
         <credit-card>
            <card-number>4263982640269299</card-number>
            <security-code>837</security-code>
            <expiration-month>02</expiration-month>
            <expiration-year>2023</expiration-year>
         </credit-card>
      </credit-card-info>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>Jane</first-name>
   <last-name>Shopper</last-name>
   <zip>12345</zip>
   <phone>1234567890</phone>
   <payment-sources>
      <sepa-direct-debit-info>
         <sepa-direct-debit>
            <iban>DE09100100101234567893</iban>
         </sepa-direct-debit>
      </sepa-direct-debit-info>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <country>us</country>
   <zip>02453</zip>
   <phone>1234567890</phone>
   <company-name>MyCo LLC</company-name>
   <payment-sources>
      <ecp-details>
         <ecp>
          <account-number>4099999992</account-number>
          <routing-number>011075150</routing-number>
          <account-type>CORPORATE_CHECKING</account-type>
         </ecp>
      </ecp-details>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <country>us</country>
   <zip>02453</zip>
   <phone>1234567890</phone>
   <company-name>Harel LLC</company-name>
   <payment-sources>
      <ecp-details>
         <billing-contact-info>
            <company-name>Scott LLC</company-name>
         </billing-contact-info>
         <ecp>
          <account-number>4099999992</account-number>
          <routing-number>011075150</routing-number>
          <account-type>CORPORATE_CHECKING</account-type>
         </ecp>
      </ecp-details>
      <ecp-details>
         <ecp>
          <account-number>4099999993</account-number>
          <routing-number>011075151</routing-number>
          <account-type>CONSUMER_SAVINGS</account-type>
         </ecp>
      </ecp-details>
   </payment-sources>
</vaulted-shopper>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
   <first-name>FirstName</first-name>
   <last-name>LastName</last-name>
   <country>us</country>
   <descriptor-phone-number>98765</descriptor-phone-number>
   <zip>02453</zip>
   <phone>1234567890</phone>
   <transaction-order-source>MOTO</transaction-order-source>
   <payment-sources>
        <credit-card-info>
         <credit-card>
            <card-number>4111111111111111</card-number>
            <security-code>111</security-code>
            <expiration-month>07</expiration-month>
            <expiration-year>2023</expiration-year>
         </credit-card>
      </credit-card-info>
   </payment-sources>
</vaulted-shopper>

For Previous API Versions

curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '

<?xml version="1.0" encoding="UTF-8"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
    <first-name>FirstName</first-name>
    <last-name>LastName</last-name>
    <country>us</country>
    <zip>02453</zip>
    <phone>1234567890</phone>
    <company-name>MyCo LLC</company-name>
    <payment-sources>
        <ecp-info>
            <ecp>
                <routing-number>011075150</routing-number>
                <account-type>CORPORATE_CHECKING</account-type>
                <account-number>4099999992</account-number>
            </ecp>
        </ecp-info>
    </payment-sources>
</vaulted-shopper>'

Response Examples

For API Version 3.0

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
  <vaulted-shopper-id>19574796</vaulted-shopper-id>
  <first-name>FirstName</first-name>
  <last-name>LastName</last-name>
  <country>us</country>
  <zip>02453</zip>
  <phone>1234567890</phone>
  <merchant-shopper-id>6783334400</merchant-shopper-id>
  <company-name></company-name>
  <soft-descriptor>BLS&#x2a;BS</soft-descriptor>
  <descriptor-phone-number>5121231212</descriptor-phone-number>
  <shopper-currency>USD</shopper-currency>
  <payment-sources>
    <credit-card-info>
      <billing-contact-info>
        <first-name>FirstName</first-name>
        <last-name>LastName</last-name>
        <city></city>
        <zip>02453</zip>
        <country>us</country>
      </billing-contact-info>
      <credit-card>
        <card-last-four-digits>1002</card-last-four-digits>
        <card-type>AMEX</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <bin-category>CONSUMER</bin-category>
        <card-regulated>N</card-regulated>
        <expiration-month>07</expiration-month>
        <expiration-year>2023</expiration-year>
        <issuing-country-code>US</issuing-country-code>
      </credit-card>
      <processing-info>
        <cvv-response-code>MA</cvv-response-code>
        <avs-response-code-zip>M</avs-response-code-zip>
        <avs-response-code-address>M</avs-response-code-address>
        <avs-response-code-name>U</avs-response-code-name>
      </processing-info>
      <date-created>09/30/2020</date-created>
      <time-created>05:59:40</time-created>
    </credit-card-info>
  </payment-sources>
  <fraud-result-info>
    <device-data-collector>N</device-data-collector>
  </fraud-result-info>
  <date-created>09/22/2020</date-created>
  <time-created>13:41:10</time-created>
</vaulted-shopper>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
  <vaulted-shopper-id>19574596</vaulted-shopper-id>
  <first-name>FirstName</first-name>
  <last-name>LastName</last-name>
  <country>us</country>
  <zip>02453</zip>
  <phone>1234567890</phone>
  <company-name></company-name>
  <soft-descriptor>BLS&#x2a;BS</soft-descriptor>
  <descriptor-phone-number>98765</descriptor-phone-number>
  <shopper-currency>USD</shopper-currency>
  <payment-sources>
    <credit-card-info>
      <billing-contact-info>
        <first-name>FirstName</first-name>
        <last-name>LastName</last-name>
        <city></city>
        <zip>02453</zip>
        <country>us</country>
      </billing-contact-info>
      <credit-card>
        <card-last-four-digits>1111</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <bin-category>CONSUMER</bin-category>
        <card-regulated>N</card-regulated>
        <issuing-bank>JPMORGAN CHASE BANK, N.A.</issuing-bank>
        <expiration-month>07</expiration-month>
        <expiration-year>2023</expiration-year>
        <issuing-country-code>US</issuing-country-code>
      </credit-card>
      <processing-info>
        <cvv-response-code>MA</cvv-response-code>
        <avs-response-code-zip>M</avs-response-code-zip>
        <avs-response-code-address>M</avs-response-code-address>
        <avs-response-code-name>U</avs-response-code-name>
        <network-transaction-id>759205438350294</network-transaction-id>
      </processing-info>
      <date-created>09/30/2020</date-created>
      <time-created>05:59:40</time-created>
    </credit-card-info>
  </payment-sources>
  <fraud-result-info>
    <device-data-collector>N</device-data-collector>
  </fraud-result-info>
  <transaction-order-source>MOTO</transaction-order-source>
  <date-created>09/22/2020</date-created>
  <time-created>13:41:10</time-created>
</vaulted-shopper>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
  <vaulted-shopper-id>19574596</vaulted-shopper-id>
  <first-name>FirstName</first-name>
  <last-name>LastName</last-name>
  <country>us</country>
  <zip>02453</zip>
  <phone>1234567890</phone>
  <soft-descriptor>BLS&#x2a;BS</soft-descriptor>
  <shopper-currency>USD</shopper-currency>
  <payment-sources>
    <credit-card-info>
      <billing-contact-info>
        <first-name>FirstName</first-name>
        <last-name>LastName</last-name>
        <city></city>
        <zip>02453</zip>
        <country>us</country>
      </billing-contact-info>
      <credit-card>
        <card-last-four-digits>1111</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <bin-category>CONSUMER</bin-category>
        <card-regulated>N</card-regulated>
        <expiration-month>07</expiration-month>
        <expiration-year>2023</expiration-year>
        <issuing-country-code>US</issuing-country-code>
      </credit-card>
      <processing-info>
        <cvv-response-code>MA</cvv-response-code>
        <avs-response-code-zip>M</avs-response-code-zip>
        <avs-response-code-address>M</avs-response-code-address>
        <avs-response-code-name>U</avs-response-code-name>
        <network-transaction-id>759205438350294</network-transaction-id>
      </processing-info>
      <date-created>09/30/2020</date-created>
      <time-created>05:59:40</time-created>
    </credit-card-info>
  </payment-sources>
  <three-d-secure>
    <authentication-result>AUTHENTICATION_SUCCEEDED</authentication-result>
  </three-d-secure>
  <date-created>09/22/2020</date-created>
  <time-created>13:41:10</time-created>
</vaulted-shopper>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
  <vaulted-shopper-id>19569774</vaulted-shopper-id>
  <first-name>FirstName</first-name>
  <last-name>LastName</last-name>
  <country>us</country>
  <zip>02453</zip>
  <phone>1234567890</phone>
  <company-name>Harel LLC</company-name>
  <shopper-currency>USD</shopper-currency>
  <payment-sources>
    <ecp-details>
      <billing-contact-info>
        <first-name>FirstName</first-name>
        <last-name>LastName</last-name>
        <city></city>
        <company-name>Scott LLC</company-name>
      </billing-contact-info>
      <ecp>
        <account-type>CORPORATE_CHECKING</account-type>
        <public-account-number>99992</public-account-number>
        <public-routing-number>75150</public-routing-number>
      </ecp>
      <date-created>09/30/2020</date-created>
      <time-created>05:48:18</time-created>
    </ecp-details>
    <ecp-details>
      <billing-contact-info>
        <first-name>FirstName</first-name>
        <last-name>LastName</last-name>
        <company-name>Harel LLC</company-name>
      </billing-contact-info>
      <ecp>
        <account-type>CONSUMER_SAVINGS</account-type>
        <public-account-number>99993</public-account-number>
        <public-routing-number>75151</public-routing-number>
      </ecp>
      <date-created>09/30/2020</date-created>
      <time-created>05:59:40</time-created>
    </ecp-details>
    <fraud-result-info>
      <device-data-collector>Y</device-data-collector>
    </fraud-result-info>
  </payment-sources>
  <date-created>09/22/2020</date-created>
  <time-created>13:41:10</time-created>
</vaulted-shopper>

Responses for Previous API Versions

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
  <vaulted-shopper-id>20848977</vaulted-shopper-id>
  <first-name>FirstName</first-name>
  <last-name>LastName</last-name>
  <shopper-currency>USD</shopper-currency>
  <payment-sources>
    <credit-card-info>
      <billing-contact-info>
        <first-name>FirstName</first-name>
        <last-name>LastName</last-name>
        <city></city>
        <company-name>CompanyName</company-name>
      </billing-contact-info>
      <credit-card>
        <card-last-four-digits>9299</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <card-category>CLASSIC</card-category>
        <expiration-month>02</expiration-month>
        <expiration-year>2023</expiration-year>
      </credit-card>
      <processing-info>
        <cvv-response-code>MA</cvv-response-code>
        <avs-response-code-zip>U</avs-response-code-zip>
        <avs-response-code-address>U</avs-response-code-address>
        <avs-response-code-name>U</avs-response-code-name>
      </processing-info>
      <fraud-result-info>
        <device-data-collector>N</device-data-collector>
      </fraud-result-info>
    </credit-card-info>
  </payment-sources>
</vaulted-shopper>
HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/vaulted-shoppers/19549020
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
    <first-name>FirstName</first-name>
    <last-name>LastName</last-name>
    <country>us</country>
    <zip>12345</zip>
    <phone>1234567890</phone>
    <shopper-currency>USD</shopper-currency>
    <payment-sources>
        <ecp-info>
            <ecp>
                <routing-number>011075150</routing-number>
                <account-type>CORPORATE_CHECKING</account-type>
                <account-number>4099999992</account-number>
            </ecp>
        </ecp-info>
    </payment-sources>
</vaulted-shopper>

Back to Top


API Explorer

To test out a basic API request, click the "Try It!" button in the right-hand column to test using the default, pre-populated sample values. To test with your own values, edit the parameter fields below. You'll see them populate in the right-hand column and you can click the "Try It!" button to submit your test request and see a response.

Language
Authentication
Header
Click Try It! to start a request and see the response here!