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.

Request Content

Send a vaultedShopper object with the following:

Property	Type	Required
`address`	string	optional
`address2`	string	optional
`city`	string	optional
`companyName`	string	required for Corporate ECP accounts
`country`	string	optional
`descriptorPhoneNumber`	string	optional
`email`	string	optional
`firstName`	string	optional
`lastName`	string	optional
`merchantShopperId`	string	optional
`paymentSources`	object	optional (see paymentSources)
`pfToken`	string	required for Hosted Payment Fields. Unique token that contains the shopper's payment information for the transaction.
`phone`	string	optional
`shippingContactInfo`	object	optional (see shippingContactInfo)
`shopperCurrency`	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).
`state`	string	optional
`threeDSecure`	object	optional (see threeDSecure)
`transactionFraudInfo`	object	optional (see transactionFraudInfo)
`transactionOrderSource`	string	optional
`walletId`	long	optional
`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 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.

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"
            }
        }
    }
}

API Explorer