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());
Did you find this page useful?