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:

📘

Send a test request

Go to API Explorer to send a test request to our sandbox environment and receive a response in real time.


Request Content

Send a vaultedShopper object with the following:

PropertyTypeRequired
addressstringoptional
address2stringoptional
citystringoptional
companyNamestringrequired for Corporate ECP accounts
countrystringoptional
descriptorPhoneNumberstringoptional
emailstringoptional
firstNamestringoptional
lastNamestringoptional
merchantShopperIdstringoptional
paymentSourcesobjectoptional (see paymentSources)
pfTokenstringrequired for Hosted Payment Fields. Unique token that contains the shopper's payment information for the transaction.
phonestringoptional
shippingContactInfoobjectoptional (see shippingContactInfo)
shopperCurrencystringoptional
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).
statestringoptional
threeDSecureobjectoptional (see threeDSecure)
transactionFraudInfoobjectoptional (see transactionFraudInfo)
transactionOrderSourcestringoptional
walletIdlongoptional, include if adding details for Masterpass or Visa Checkout
zipstringoptional

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 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 and higher

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 '
{
    "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 QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkFsdG9pZHMxIQ==' \
-d '
{
    "pfToken" : "2b1383fa5f25c819bee03e01e060b2c0efae00dfdd963a62c6e106829d727b63_",
    "firstName": "FirstName",
    "lastName": "LastName",
    "country": "fr",
    "zip": "75001",
    "phone": "1234567890",
    "shopperCurrency": "USD",
}'
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": "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 QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkFsdG9pZHMxIQ==' \
-d '
{
  "pfToken": "2b1383fa5f25c819bee03e01e060b2c0efae00dfdd963a62c6e106829d727b63_",  
  "firstName": "FirstName",
  "lastName": "LastName",
  "shopperCurrency": "USD",
  "country": "us",
  "state": "ca",
  "address": "Blue Lane 21",
  "zip": 12345,
  "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
                }
            }
        ]
    }
}
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": "de",
          "zip": "12345",
          "phone": "1234567890",
          "shopperCurrency": "EUR",
          "paymentSources": {
               "payByBankInfo": [
                    {
                         "payByBank": {
                              "iban": "DE12345678901234567890"
                         }
                    }
               ]
          }
     }'

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 and higher

{
  "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"
}
{
    "vaultedShopperId": 12345678,
    "firstName": "John",
    "lastName": "Doe",
    "country": "de",
    "zip": "12345",
    "phone": "1234567890",
    "shopperCurrency": "EUR",
    "paymentSources": {
        "payByBankInfo": [
            {
                "billingContactInfo": {
                    "firstName": "John",
                    "lastName": "Doe",
                    "zip": "12345",
                    "country": "de"
                },
                "payByBank": {
                    "ibanFirstFour": "DE12",
                    "ibanLastFour": "7890"
                },
                "dateCreated": "05/03/2024",
                "timeCreated": "08:17:18",
                "dateModified": "05/03/2024",
                "timeModified": "08:17:18"
            }
        ]
    },
    "fraudResultInfo": {},
    "dateCreated": "05/03/2024",
    "timeCreated": "08:17:16"
}

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

BlueSnap provides a sandbox environment so you can test basic requests with this endpoint. You can view the request in the API Explorer console and its response directly below the console.

The console includes a sample request with predefined parameter values. To send a request with custom values, edit the parameter fields below. As you edit the fields, your custom values display in the request in the console.

Click the Try it! button below the request example when you are ready to send your request.

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