BasicsPayment APIEmbedded PaymentsReportingToolsSupport GuidesBlueSnap.com
Top of Section
Start typing to search…

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.

Back to Top

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>