Customer Vault API
The Customer Vault API allows you to create customer profiles containing their payment information – i.e., tokens – and then to make repeat payments without having to directly access sensitive payment information. It is a highly efficient and secure method for enabling repeat customer payments.
Click the links below to view our code samples.
Verify That the Service Is Accessible
bool isOnline = client.customerVaultService().monitor();
Customer Profile
Create a customer profile
Profile profile = Profile.Builder()
.merchantCustomerId("0f8fad5bd9cb469fa16570867728950e")
.locale("en_US")
.firstName("John")
.lastName("Smith")
.email("john.smith@example.com")
.phone("713-444-5555")
.Build();
Profile response = client.customerVaultService().create(profile);
Create a customer profile using a single-use token
Profile profile = Profile.Builder()
.merchantCustomerId("0f8fad5bd9cb469fa16570867728950e")
.locale("en_US")
.firstName("John")
.lastName("Smith")
.email("john.smith@example.com")
.phone("713-444-5555")
.card()
.singleUseToken("SCO0Jpx9JUP9hESh")
.Done()
.Build();
Profile response = client.customerVaultService().create(profile);
Look up a customer profile
Profile response = client.customerVaultService().get(Profile.Builder()
.id(profile.id())
.Build());
Update a customer profile
Profile response = client.customerVaultService().get(Profile.Builder()
.id(profile.id())
.Build());
response.firstName("Jack");
Profile response = client.customerVaultService().update(profile);
Delete a customer profile
bool response = client.customerVaultService().delete(profile);
Profile Addresses
Create a customer address
Address address = client.customerVaultService().create(Address.Builder()
.profileId(profile.id())
.nickName("home")
.street("100 Queen Street West")
.street2("Unit 201")
.city("Toronto")
.country("CA")
.state("ON")
.zip("M5H 2N2")
.recipientName("Jane Doe")
.phone("647-788-3901")
.Build());
Look up a customer address
Address response = client.customerVaultService().get(Address.Builder()
.id(address.id())
.profileId(profile.id())
.Build());
Update a customer address
Address address = client.customerVaultService().get(Address.Builder()
.id(address.id())
.profileId(profile.id())
.Build());
address.nickName("NEW HOME");
Address response = client.customerVaultService().update(address);
Delete a customer address
bool response = client.customerVaultService().delete(address);
Profile Cards
Create a customer card
Card card = Card.Builder()
.profileId(profile.id())
.nickName("John's corporate Visa")
.cardNum("4111111111111111")
.cardExpiry()
.month(DateTime.Now.Month)
.year(DateTime.Now.Year)
.Done()
.billingAddressId(address.id())
.Build();
Card response = client.customerVaultService().create(card);
Look up a customer card
Card response = client.customerVaultService().get(Card.Builder()
.id(card.id())
.profileId(profile.id())
.Build());
Update a customer card
Card updateCard = client.customerVaultService().get(Card.Builder()
.id(card.id())
.profileId(profile.id())
.Build());
updateCard.nickName("NEW CARD NAME");
Card response = client.customerVaultService().update(updateCard);
Delete a customer card
bool response = client.customerVaultService().delete(card);
Profile Bank Accounts
Managing ACH Bank Accounts
Create an ACH bank account
ACHBankAccounts account = client.customerVaultService().create(ACHBankAccounts.Builder()
.nickName("Johns RBC Business Bank Account")
.accountNumber("8754326712")
.routingNumber("123456789")
.accountHolderName("XYZ Business")
.billingAddressId(address.id())
.accountType("CHECKING")
.merchantRefNum(System.Guid.NewGuid().ToString())
.profileId(profile.id())
.Build());
Look up an ACH bank account
ACHBankAccounts response = client.customerVaultService().get(ACHBankAccounts.Builder()
.id(account.id())
.profileId(profile.id())
.Build());
Update an ACH bank account
account.nickName("Johns RBC");
ACHBankAccounts response = client.customerVaultService().update(account);
Delete an ACH bank account
ACHBankAccounts account = client.customerVaultService().create(ACHBankAccounts.Builder()
.nickName("Johns RBC Business Bank Account")
.accountNumber(getRandomNumber())
.routingNumber("123456789")
.accountHolderName("XYZ Business")
.billingAddressId(address.id())
.accountType("CHECKING")
.merchantRefNum(System.Guid.NewGuid().ToString())
.profileId(profile.id())
.Build());
bool response = client.customerVaultService().delete(account);
Managing BACS Bank Accounts
Create a BACS bank account
BACSBankAccounts account = client.customerVaultService().create(BACSBankAccounts.Builder()
.nickName("Sally Barclays Account")
.accountNumber("34898396")
.accountHolderName("XYZ Business")
.sortCode("070116")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
Create a BACS bank account with a mandate
List<Mandates> mandateList = new List<Mandates>();
Mandates mandate = Mandates.Builder()
.reference("SUBCRIP345")
.Build();
mandateList.Add(mandate);
BACSBankAccounts account = client.customerVaultService().create(BACSBankAccounts.Builder()
.nickName("Johns RBC Business Bank Account")
.accountNumber(getRandomNumber())
.mandates(mandateList)
.accountHolderName("XYZ Business")
.sortCode("070246")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
Look up a BACS bank account
BACSBankAccounts response = client.customerVaultService().get(BACSBankAccounts.Builder()
.id(account.id())
.profileId(profile.id())
.Build());
Update a BACS bank account
account.nickName("Johns RBC");
BACSBankAccounts response = client.customerVaultService().update(account);
Delete a BACS bank account
BACSBankAccounts account = client.customerVaultService().update(BACSBankAccounts.Builder()
.nickName("Johns RBC Business Bank Account")
.accountNumber(getRandomNumber())
.sortCode("1234567")
.accountHolderName("XYZ Business")
.billingAddressId(address.id())
.merchantRefNum(System.Guid.NewGuid().ToString())
.profileId(profile.id())
.Build());
bool response = client.customerVaultService().delete(account);
Managing EFT Bank Accounts
Create an EFT bank account
EFTBankAccounts account = client.customerVaultService().create(EFTBankAccounts.Builder()
.accountNumber("9867243561")
.transitNumber("11224")
.institutionId("123")
.accountHolderName("John Smith")
.nickName("Johns RBC Business Bank Account")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
Look up an EFT bank account
EFTBankAccounts response = client.customerVaultService().get(EFTBankAccounts.Builder()
.id(account.id())
.profileId(profile.id())
.billingAddressId(address.id())
.Build());
Update an EFT bank account
account.nickName("John's RBC");
EFTBankAccounts response = client.customerVaultService().update(account);
Delete an EFT bank account
EFTBankAccounts account = client.customerVaultService().create(EFTBankAccounts.Builder()
.accountNumber(getRandomNumber())
.transitNumber("11224")
.institutionId("123")
.accountHolderName("John Smith")
.nickName("Johns RBC Business Bank Account")
.merchantRefNum(System.Guid.NewGuid().ToString())
.lastDigits("01")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
bool response = client.customerVaultService().delete(account);
Managing SEPA Bank Accounts
Create a SEPA bank account
SEPABankAccounts account = client.customerVaultService().create(SEPABankAccounts.Builder()
.iban("AL28745014269242491970013523")
.bic("OKOYFIHH")
.accountHolderName("John Smith")
.nickName("Johns RBC Business Bank Account")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
Create a SEPA bank account with a mandate
List<Mandates> mandateList = new List<Mandates>();
Mandates mandate = Mandates.Builder()
.reference("SUBCRIP345")
.Build();
mandateList.Add(mandate);
SEPABankAccounts account = client.customerVaultService().create(SEPABankAccounts.Builder()
.iban("AL12752544481837493126293094")
.bic("OKOYFIHH")
.mandates(mandateList)
.accountHolderName("John Smith")
.nickName("Johns RBC Business Bank Account")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
Look up a SEPA bank account
SEPABankAccounts response = client.customerVaultService().get(SEPABankAccounts.Builder()
.id(account.id())
.profileId(profile.id())
.billingAddressId(address.id())
.Build());account.nickName("Johns RBC");
SEPABankAccounts response = client.customerVaultService().update(account);
Update a SEPA bank account
account.nickName("Johns RBC");
SEPABankAccounts response = client.customerVaultService().update(account);
Delete a SEPA bank account
SEPABankAccounts account = client.customerVaultService().create(SEPABankAccounts.Builder()
.iban("AL67018473703433137977774895")
.bic("HANDFIHH")
.accountHolderName("John Smith")
.nickName("Johns RBC Business Bank Account")
.billingAddressId(address.id())
.profileId(profile.id())
.Build());
bool response = client.customerVaultService().delete(account);
Mandates
Create a BACS bank account mandate
BACSBankAccounts account = client.customerVaultService().create(BACSBankAccounts.Builder()
.nickName("Sally Barclays Account")
.accountNumber("563241265")
.accountHolderName("XYZ Business")
.sortCode("070246")
.billingAddressId("a7b218e7-290a-4434-aea2-a1f985fc26c0")
.profileId("a7b218e7-290a-4434-aea2-a1f985fc26c0")
.Build());
accountName = "BACS";
Mandates mandate = client.customerVaultService().create(Mandates.Builder()
.reference("SUBSCRIP09")
.bankAccountId("60022f38-fd17-4731-909c-923930d0d5d4")
.profileId("a7b218e7-290a-4434-aea2-a1f985fc26c0")
.Build(), accountName);
Create a SEPA bank account mandate
SEPABankAccounts account = client.customerVaultService().create(SEPABankAccounts.Builder()
.iban("AL97413297905487084294919656")
.bic("HANDFIHH")
.accountHolderName("John Smith")
.nickName("Johns RBC Business Bank Account")
.billingAddressId("a7b218e7-290a-4434-aea2-a1f985fc26c0")
.profileId("a7b218e7-290a-4434-aea2-a1f985fc26c0")
.Build());
accountName = "SEPA";
Mandates mandate = client.customerVaultService().create(Mandates.Builder()
.reference("SUBSCRIP09")
.bankAccountId("60022f38-fd17-4731-909c-923930d0d5d4")
.profileId("a7b218e7-290a-4434-aea2-a1f985fc26c0")
.Build(), accountName);
Look up a mandate
Mandates mandate = client.customerVaultService().create(Mandates.Builder()
.reference("SUBCRIBE100")
.bankAccountId(account.id())
.profileId(profile.id())
.Build(), accountName);
Mandates mandates = Mandates.Builder()
.id(mandate.id())
.profileId(profile.id())
.Build();
Mandates response = client.customerVaultService().get(mandate);
Update a mandate
Mandates mandate = client.customerVaultService().create(Mandates.Builder()
.reference("SUBSCRIB100")
.bankAccountId(account.id())
.profileId(profile.id())
.Build(), accountName);
Mandates mandates = Mandates.Builder()
.id(mandate.id())
.bankAccountId(account.id())
.profileId(profile.id())
.Build();
mandates.status("CANCELLED");
Mandates response = client.customerVaultService().update(mandates);
Delete a mandate
Mandates mandate = client.customerVaultService().create(Mandates.Builder()
.reference("SUBCRIBE100")
.bankAccountId(account.id())
.profileId(profile.id())
.Build(), accountName);
Mandates mandates = Mandates.Builder()
.id(mandate.id())
.bankAccountId(account.id())
.profileId(profile.id())
.Build();
bool response = client.customerVaultService().delete(mandates);
Process a Payment Using a Payment Token
Process an authorization with a payment token
Authorization response = client.cardPaymentService().authorize(Authorization.Builder()
.merchantRefNum("0f8fad5bd9cb469fa16570867728950e")
.amount(555)
.settleWithAuth(false)
.card()
.paymentToken(card.paymentToken())
.Done()
.Build());
Verify a card using a payment token
Verification response = client.cardPaymentService().verify(Verification.Builder()
.merchantRefNum("0f8fad5bd9cb469fa16570867728950e")
.card()
.paymentToken(card.paymentToken())
.Done()
.Build());