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:
- Masterpass Guide
- Visa Checkout Guide

Request Content

Send a vaulted-shopper object with the following:

Property	Type	Required
`address`	string	optional
`address2`	string	optional
`city`	string	optional
`company-name`	string	required for Corporate ECP accounts
`country`	string	optional
`descriptor-phone-number`	string	optional
`email`	string	optional
`first-name`	string	optional
`last-name`	string	optional
`merchant-shopper-id`	string	optional
`payment-sources`	container	optional (see payment-sources)
`phone`	string	optional
`shipping-contact-info`	container	optional (see shipping-contact-info)
`shopper-currency`	string	optional
`soft-descriptor`	string	Optional. 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).
`state`	string	optional
`three-d-secure`	container	optional (see three-d-secure)
`transaction-fraud-info`	container	optional (see transaction-fraud-info)
`transaction-order-source`	string	optional
`wallet-id`	long	optional, include if adding Masterpass or Visa Checkout wallet details
`zip`	string	optional

Response Details

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

API version 3.0 and higher
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.

Examples

Request Examples

API Version 3.0 and higher

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>

curl -X POST 'https://sandbox.bluesnap.com/services/2/vaulted-shoppers' \
     -H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkFsdG9pZHMxIQ==' \
     -H 'Content-Type: application/xml' \
     -H 'accept: application/xml' \
     -d '
    <vaulted-shopper xmlns="http://ws.plimus.com">
    <shopper-currency>EUR</shopper-currency>
    <first-name>Jane</first-name>
    <last-name>Shopper</last-name>
    <phone>1800808080</phone>
    <zip>43310</zip>
    <country>de</country>
    <payment-sources>
        <pay-by-bank-info>
        <pay-by-bank>
            <iban>DE12345678909876543210</iban>
        </pay-by-bank>
        </pay-by-bank-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

API Version 3.0 and higher

<?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>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vaulted-shopper xmlns="http://ws.plimus.com">
    <vaulted-shopper-id>51669859</vaulted-shopper-id>
    <first-name>Jane</first-name>
    <last-name>Shopper</last-name>
    <country>de</country>
    <zip>43310</zip>
    <phone>1800808080</phone>
    <company-name></company-name>
    <shopper-currency>EUR</shopper-currency>
    <payment-sources>
        <pay-by-bank-info>
            <billing-contact-info>
                <first-name>Jane</first-name>
                <last-name>Shopper</last-name>
                <zip>43310</zip>
                <country>de</country>
            </billing-contact-info>
            <pay-by-bank>
                <iban-first-four>DE12</iban-first-four>
                <iban-last-four>3210</iban-last-four>
            </pay-by-bank>
            <date-created>07/18/2024</date-created>
            <time-created>05:47:46</time-created>
            <date-modified>07/18/2024</date-modified>
            <time-modified>05:47:46</time-modified>
        </pay-by-bank-info>
    </payment-sources>
    <fraud-result-info/>
    <date-created>07/18/2024</date-created>
    <time-created>05:47:46</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>