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:
Property | Type | Required |
---|---|---|
paymentSources | object | optional (see paymentSources) |
firstName | string | optional |
lastName | string | optional |
softDescriptor | 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). |
descriptorPhoneNumber | string | optional |
merchantShopperId | string | optional |
country | string | optional |
state | string | optional |
city | string | optional |
address | string | optional |
address2 | string | optional |
email | string | optional |
zip | string | optional |
phone | string | optional |
companyName | string | required for Corporate ECP accounts |
shopperCurrency | string | optional |
shippingContactInfo | object | optional (see shippingContactInfo) |
walletId | long | optional, include if adding details for Masterpass or Visa Checkout |
transactionFraudInfo | object | optional (see transactionFraudInfo) |
transactionOrderSource | string | optional |
threeDSecure | object | optional (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.
ThevaultedShopperId
appears in the response body, as well as in the URL in the location header. In the example below, thevaultedShopperId
is 20848977. -
API version 1.0
If successful, the response HTTP status code is 201 Created.
ThevaultedShopperId
appears in the URL in the location header. In the example below, thevaultedShopperId
is 19549020.
There is no content in the response body.
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"
}
}
}
}
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.