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 (vaultedShopperId) 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 vaultedShopper object with the following:

PropertyTypeRequired
paymentSourcesobjectoptional (see paymentSources)
firstNamestringoptional
lastNamestringoptional
softDescriptorstringOptional. 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).
descriptorPhoneNumberstringoptional
merchantShopperIdstringoptional
countrystringoptional
statestringoptional
citystringoptional
addressstringoptional
address2stringoptional
emailstringoptional
zipstringoptional
phonestringoptional
companyNamestringrequired for Corporate ECP accounts
shopperCurrencystringoptional
shippingContactInfoobjectoptional (see shippingContactInfo)
walletIdlongoptional, include if adding details for Masterpass or Visa Checkout
transactionFraudInfoobjectoptional (see transactionFraudInfo)
transactionOrderSourcestringoptional
threeDSecureobjectoptional (see threeDSecure)

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 ecpDetails object, which replaces the ecpInfo object, 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 includes the vaultedShopper object, which contains all details that are saved for that shopper.
    The vaultedShopperId appears in the response body, as well as in the URL in the location header. In the example below, the vaultedShopperId is 20848977.

  • API version 1.0
    If successful, the response HTTP status code is 201 Created.
    The vaultedShopperId appears in the URL in the location header. In the example below, the vaultedShopperId 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/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "FirstName",
    "lastName": "LastName",
		"merchantShopperId": "6783334400"
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "FirstName",
    "lastName": "LastName",
    "country": "fr",
    "zip": "02453",
    "phone": "1234567890",
    "shopperCurrency": "USD",
    "paymentSources": {
        "creditCardInfo": [
            {
                "billingContactInfo": {
                    "firstName": "FirstName",
                    "lastName": "LastName",
                    "zip": "02453",
                    "country": "us"
                },
                "creditCard": {
                    "cardNumber": "4111 1111 1111 1111",
                    "securityCode": "123",
                    "expirationMonth": "07",
                    "expirationYear": "2023"
                }
            }
        ]
        
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "paymentSources": {"creditCardInfo": [{
        "billingContactInfo": {
            "zip": "02453",
            "country": "US",
            "firstName": "billingFirstName",
            "lastName": "billingLastName",
            "address2": "Apt 1",
            "address1": "10 Main St",
            "state": "MA"
        },
        "creditCard": {
            "expirationYear": "2023",
            "securityCode": "837",
            "expirationMonth": "02",
            "cardNumber": "4263982640269299"
        }
    }]},
    "firstName": "FirstName",
    "lastName": "LastName",
    "transactionFraudInfo": {
        "shopperIpAddress": "123.12.134.1",
        "fraudSessionId": "1234",
        "company": "company",
        "shippingContactInfo": {
            "zip": "shippingZip",
            "country": "US",
            "firstName": "shippingLastName",
            "lastName": "shippingFirstName",
            "city": "shippingCity",
            "address2": "shippingAddress2",
            "address1": "shippingAddress1",
            "state": "AL"
        }
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{"walletId": "21"}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "FirstName",
    "lastName": "LastName",
    "country": "fr",
    "zip": "75001",
    "phone": "1234567890",
    "shopperCurrency": "USD",
    "paymentSources": {
        "creditCardInfo": [
            {
                "pfToken" : "2b1383fa5f25c819bee03e01e060b2c0efae00dfdd963a62c6e106829d727b63_"
            }
        ]
        
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "paymentSources": {"creditCardInfo": [{"creditCard": {
        "expirationYear": "2023",
        "securityCode": "837",
        "expirationMonth": "02",
        "cardNumber": "4263982640269299"
    }}]},
    "firstName": "FirstName",
    "lastName": "LastName",
    "softDescriptor": "MYCOMPANY"
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "firstName": "Jane", 
  "lastName": "Shopper", 
  "zip": "75001", 
  "country": "fr",
  "phone": "1234567890", 
  "paymentSources": {
    "sepaDirectDebitInfo": [{ "sepaDirectDebit": {
          "iban": "DE09100100101234567893"
    }}]}
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "FirstName",
    "lastName": "LastName",
    "country": "us",
    "zip": "02453",
    "phone": "1234567890",
    "shopperCurrency": "USD",
    "paymentSources": {  
      "ecpDetails":[  
         {  
            "ecp":{  
               "routingNumber":"011075150",
               "accountType":"CONSUMER_CHECKING",
               "accountNumber":"4099999992"
            }
         }
      ]
   }
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{  
   "zip":"12345",
   "country":"us",
   "paymentSources":{  
      "ecpDetails":[  
         {  
            "ecp":{  
               "routingNumber":"011075150",
               "accountType":"CONSUMER_CHECKING",
               "accountNumber":"4099999992"
            }
         },
         {  
            "ecp":{  
               "routingNumber":"011075151",
               "accountType":"CONSUMER_SAVINGS",
               "accountNumber":"4099999993"
            }
         }
      ]
   },
   "firstName":"FirstName",
   "lastName":"LastName",
   "phone":"1234567890"
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "FirstName",
    "lastName": "LastName",
    "country": "fr",
    "zip": "02453",
    "phone": "1234567890",
    "shopperCurrency": "USD",
    "transactionOrderSource" : "MOTO",
    "paymentSources": {
    	"creditCardInfo": [
            {
                "billingContactInfo": {
                    "firstName": "FirstName",
                    "lastName": "LastName",
                    "zip": "02453",
                    "country": "us"
                },
                "creditCard": {
                    "cardNumber": "4111 1111 1111 1111",
                    "securityCode": "123",
                    "expirationMonth": "07",
                    "expirationYear": "2023"
                }
            }
        ]
    	
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "John",
    "lastName": "Doe",
    "country": "au",
    "zip": "12345",
    "phone": "1234567890",
    "shopperCurrency": "AUD",
    "paymentSources": {
        "becsDirectDebitInfo": [
            {
                "becsDirectDebit": {
                    "bsbNumber": "880010",
                    "accountNumber": "4099999993",
                    "accountName": "John Doe",
                    "financialInstitution": "financialInstitution",
                    "branchName": "branchName",
                    "agreementId": 81
                }
            }
        ]
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/vaulted-shoppers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '

{
    "firstName": "Boris",
    "lastName": "Britva",
    "country": "ca",
    "zip": "12345",
    "phone": "1234567890",
    "shopperCurrency": "CAD",
    "paymentSources": {
        "acssDirectDebitInfo": [
            {
                "acssDirectDebit": {
                    "routingNumber": "9999999999",
                    "accountNumber": "4099999992",
                    "accountType": "PERSONAL",
                    "agreementId": 43
                }
            }
        ]
    }
}

For Previous API Versions

curl -L -X POST 'https://sandbox.bluesnap.com/services/2/vaulted-shoppers' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'bluesnap-version: 2.0' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "firstName": "FirstName",
    "lastName": "LastName",
    "country": "us",
    "zip": "02453",
    "phone": "1234567890",
    "shopperCurrency": "USD",
    "paymentSources": {
        "ecpInfo": {
            "ecp": {
                "routingNumber": "011075150",
                "accountType": "CONSUMER_CHECKING",
                "accountNumber": "4099999992"
            }
        }
    }
 }'

Response Examples

For API Version 3.0

{
  "vaultedShopperId": 19574802,
  "firstName": "FirstName",
  "lastName": "LastName",
  "merchantShopperId": "6783334400",
  "country": "fr",
  "zip": "175001",
  "phone": "1234567890",
  "softDescriptor": "BLS*BS",
  "shopperCurrency": "USD",
  "paymentSources": {
    "creditCardInfo": [
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName",
          "zip": "75001",
          "country": "us"
        },
        "creditCard": {
          "cardLastFourDigits": "1111",
          "cardType": "VISA",
          "cardSubType": "CREDIT",
          "binCategory": "CONSUMER",
          "cardRegulated": "N",
          "issuingBank": "JPMORGAN CHASE BANK, N.A.",
          "expirationMonth": "07",
          "expirationYear": "2023",
          "issuingCountryCode": "US"
        },
        "processingInfo": {
          "cvvResponseCode": "MA",
          "avsResponseCodeZip": "M",
          "avsResponseCodeAddress": "M",
          "avsResponseCodeName": "U",
          "networkTransactionId": "759211614372286"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:59:40"
      }
    ]
  },
  "fraudResultInfo": {
    "deviceDataCollector": "N"
  },
  "dateCreated": "09/22/2020",
  "timeCreated": "13:41:10"
}
{
  "vaultedShopperId": 19574600,
  "firstName": "FirstName",
  "lastName": "LastName",
  "country": "fr",
  "zip": "75001",
  "phone": "1234567890",
  "softDescriptor": "BLS*BS",
  "shopperCurrency": "USD",
  "paymentSources": {
    "creditCardInfo": [
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName",
          "zip": "02453",
          "country": "us"
        },
        "creditCard": {
          "cardLastFourDigits": "1111",
          "cardType": "VISA",
          "cardSubType": "CREDIT",
          "binCategory": "CONSUMER",
          "cardRegulated": "N",
          "issuingBank": "JPMORGAN CHASE BANK, N.A.",
          "expirationMonth": "07",
          "expirationYear": "2023",
          "issuingCountryCode": "US"
        },
        "processingInfo": {
          "cvvResponseCode": "MA",
          "avsResponseCodeZip": "M",
          "avsResponseCodeAddress": "M",
          "avsResponseCodeName": "U",
          "networkTransactionId": "759205478861907"
        },
        "dateCreated": "09/22/2020",
        "timeCreated": "10:41:12"
      }
    ]
  },
  "fraudResultInfo": {
    "deviceDataCollector": "N"
  },
  "transactionOrderSource": "MOTO",
  "dateCreated": "09/22/2020",
  "timeCreated": "13:41:10"
}
{
  "vaultedShopperId": 19574636,
  "firstName": "FirstName",
  "lastName": "LastName",
  "country": "fr",
  "zip": "75001",
  "phone": "1234567890",
  "softDescriptor": "BLS*BS",
  "shopperCurrency": "USD",
  "paymentSources": {
    "creditCardInfo": [
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName",
          "zip": "75001",
          "country": "fr"
        },
        "creditCard": {
          "cardLastFourDigits": "1000",
          "cardType": "VISA",
          "cardSubType": "CREDIT",
          "binCategory": "CONSUMER",
          "cardRegulated": "N",
          "expirationMonth": "01",
          "expirationYear": "2022",
          "issuingCountryCode": "US"
        },
        "processingInfo": {
          "cvvResponseCode": "NR",
          "avsResponseCodeZip": "N",
          "avsResponseCodeAddress": "N",
          "avsResponseCodeName": "U",
          "networkTransactionId": "019072416172166"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:59:40"
      }
    ]
  },
  "threeDSecure": {
    "authenticationResult": "AUTHENTICATION_SUCCEEDED"
  },
  "dateCreated": "09/22/2020",
  "timeCreated": "13:41:10"
}
{
  "vaultedShopperId": 19569754,
  "firstName": "FirstName",
  "lastName": "LastName",
  "country": "us",
  "zip": "12345",
  "phone": "1234567890",
  "shopperCurrency": "USD",
  "paymentSources": {
    "ecpDetails": [
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName"
        },
        "ecp": {
          "accountType": "CONSUMER_CHECKING",
          "publicAccountNumber": "99992",
          "publicRoutingNumber": "75150"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:48:18"
      },
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName"
        },
        "ecp": {
          "accountType": "CONSUMER_SAVINGS",
          "publicAccountNumber": "99993",
          "publicRoutingNumber": "75151"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:48:18"
      }
    ]
  },
  "fraudResultInfo": {"deviceDataCollector": "Y"},
  "dateCreated": "09/22/2020",
  "timeCreated": "13:41:10"
}
{
  "vaultedShopperId": 19582622,
  "firstName": "FirstName",
  "lastName": "LastName",
  "softDescriptor": "BLS*BS",
  "shopperCurrency": "USD",
  "paymentSources": {
    "creditCardInfo": [
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName"
        },
        "creditCard": {
          "cardLastFourDigits": "1091",
          "cardType": "VISA",
          "cardSubType": "CREDIT",
          "binCategory": "CONSUMER",
          "expirationMonth": "07",
          "expirationYear": "2023"
        },
        "processingInfo": {
          "cvvResponseCode": "NR",
          "avsResponseCodeZip": "U",
          "avsResponseCodeAddress": "U",
          "avsResponseCodeName": "U",
          "networkTransactionId": "020020314211584"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:59:40"
      }
    ]
  },
  "fraudResultInfo": {
    "deviceDataCollector": "N"
  },
  "threeDSecure": {
    "authenticationResult": "AUTHENTICATION_SUCCEEDED"
  },
  "dateCreated": "09/22/2020",
  "timeCreated": "13:41:10"
}
{
    "vaultedShopperId": 19610970,
    "firstName": "John",
    "lastName": "Doe",
    "country": "au",
    "zip": "12345",
    "phone": "1234567890",
    "shopperCurrency": "AUD",
    "paymentSources": {
        "becsDirectDebitInfo": [
            {
                "billingContactInfo": {
                    "firstName": "John",
                    "lastName": "Doe",
                    "zip": "12345",
                    "country": "au"
                },
                "becsDirectDebit": {
                    "bsbNumber": "880010",
                    "accountName": "John Doe",
                    "financialInstitution": "financialInstitution",
                    "branchName": "branchName",
                    "publicAccountNumber": "9993",
                    "agreementId": 81
                },
                "dateCreated": "07/08/2022",
                "timeCreated": "07:13:51"
            }
        ]
    },
    "fraudResultInfo": {},
    "dateCreated": "07/08/2022",
    "timeCreated": "07:13:51"
}
{
    "vaultedShopperId": 19610788,
    "firstName": "Boris",
    "lastName": "Britva",
    "country": "ca",
    "zip": "12345",
    "phone": "1234567890",
    "shopperCurrency": "CAD",
    "paymentSources": {
        "acssDirectDebitInfo": [
            {
                "billingContactInfo": {
                    "firstName": "Boris",
                    "lastName": "Britva",
                    "zip": "12345",
                    "country": "ca"
                },
                "acssDirectDebit": {
                    "routingNumber": "9999999999",
                    "accountType": "PERSONAL",
                    "publicAccountNumber": "9992",
                    "agreementId": 7573
                },
                "dateCreated": "06/27/2022",
                "timeCreated": "10:16:43"
            }
        ]
    },
    "fraudResultInfo": {},
    "dateCreated": "06/27/2022",
    "timeCreated": "10:16:43"
}

Responses for Previous API Versions

{
    "paymentSources": {"creditCardInfo": [{
        "billingContactInfo": {
            "firstName": "FirstName",
            "lastName": "LastName",
            "city": "",
            "companyName": "JohnDoeAndSons"
        },
        "processingInfo": {
            "avsResponseCodeAddress": "U",
            "cvvResponseCode": "MA",
            "avsResponseCodeName": "U",
            "avsResponseCodeZip": "U"
        },
        "fraudResultInfo": {"deviceDataCollector": "N"},
        "creditCard": {
            "expirationYear": 2023,
            "cardLastFourDigits": 9299,
            "cardSubType": "CREDIT",
            "cardType": "VISA",
            "cardCategory": "CLASSIC",
            "expirationMonth": "02"
        }
    }]},
    "firstName": "FirstName",
    "lastName": "LastName",
    "vaultedShopperId": 20848977,
    "shopperCurrency": "USD"
}
HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/vaulted-shoppers/19549020
{
    "firstName": "FirstName",
    "lastName": " LastName",
    "country": "us",
    "zip": "12345",
    "phone": "1234567890",
    "shopperCurrency": "USD",
    "paymentSources": {
        "ecpInfo": {
            "ecp": {
                "routingNumber": "011075150",
                "accountType": "CONSUMER_CHECKING",
                "accountNumber": "4099999992"
            }
        }
    }
}

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
Authorization
Header
Click Try It! to start a request and see the response here!