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

boolean isOnline = apiClient.customerVaultService().monitor();

Customer Profile

Create a customer profile
Profile profile =
    Profile.builder()
      .merchantCustomerId("0f8fad5bd9cb469fa16570867728950e")
      .locale(Locale.en_US)
      .firstName("John")
      .lastName("Smith")
      .email("john.smith@example.com")
      .phone("713-444-5555")
      .build();

apiClient.customerVaultService().create(profile);
Create a customer profile using a single-use token
Profile profile =
    Profile.builder()
      .merchantCustomerId("0f8fad5bd9cb469fa16570867728950e")
      .locale(Locale.en_US)
      .firstName("John")
      .lastName("Smith")
      .email("john.smith@example.com")
      .phone("713-444-5555")
      .card()
      .singleUseToken("SCrGrrRANmOVtcVc")
      .done()
      .build();

apiClient.customerVaultService().create(profile);
Look up a customer profile
Profile lookupResponse = apiClient.customerVaultService().lookup(profile.getId());
Update a customer profile
Profile updatedProfile =
    Profile.builder()
      .id(profile.getId())
      .merchantCustomerId(profile.getMerchantCustomerId())
      .firstName("Jack")
      .build();

Profile updatedProfileResponse = apiClient.customerVaultService().update(updatedProfile);
Delete a customer profile
boolean profileDeleted = apiClient.customerVaultService().delete(profile.getId());

Profile Addresses

Create a customer address
Address address =
   Address.builder()
     .profileId(profile.getId())
     .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();

 apiClient.customerVaultService().create(address);
Look up a customer address
Address addressResponse = apiClient.customerVaultService().lookup(address.getId());
Update a customer address
Address addressToUpdate =
    Address.builder()
      .profileId(profile.getId())
      .id(address.getId())
      .nickName("New Home")
      .build();

Address updatedAddress = apiClient.customerVaultService().update(addressToUpdate);
Delete a customer address
boolean addressDeleted = apiClient.customerVaultService().delete(address.getId());;

Profile Cards

Create a customer card
Card card =
    Card.builder()
      .profileId(profile.getId())
      .nickName("John's corporate Visa2")
      .holderName("MR. JOHN SMITH")
      .cardNum("4111111111111111")
      .cardExpiry()
       .month(12)
       .year(2019)
       .done()
      .billingAddressId(address.getId())
      .build();
apiClient.customerVaultService().create(card);
Look up a customer card
Card cardResponse = apiClient.customerVaultService().lookup(card.getId());
Update a customer card
Card cardUpdate =
     Card.builder()
       .profileId(profile.getId())
       .id(cardResponse.getId())
       .nickName("NEW CARD NAME")
       .build();

 Card updatedCard = apiClient.customerVaultService().update(cardUpdate);
Delete a customer card
boolean cardDeleted = apiClient.customerVaultService().delete(card.getId());

Profile Bank Accounts

Managing ACH Bank Accounts

Create an ACH bank account
ACHBankAccounts achBankAccounts=
  ACHBankAccounts.builder()
    .nickName("John RBC Business Bank Account")
    .accountNumber("511201")
    .routingNumber("123456789")
    .accountHolderName("XYZ Business")
    .billingAddressId("60022f38-fd17-4731-909c-923930d0d5d4")
    .accountType("CHECKING")
    .profileId(profile.getId())
    .build();

ACHBankAccounts achBankAccountsRes=apiClient.customerVaultService().create(achBankAccounts);
Look up an ACH bank account
ACHBankAccounts achBankAccounts=
  ACHBankAccounts.builder()
    .profileId(achBankAccountsRes.getProfileId())
    .id(achBankAccountsRes.getId())
    .build();

ACHBankAccounts response=apiClient.customerVaultService().lookup(achBankAccounts);
Update an ACH bank account
ACHBankAccounts achBankAccountsToUpdate=
  ACHBankAccounts.builder()
    .nickName("John RBC Business Bank Account")
    .profileId(achBankAccountsRes.getProfileId())
    .id(achBankAccountsRes.getId())
    .build();

ACHBankAccounts response=apiClient.customerVaultService().update(achBankAccountsToUpdate);
Delete an ACH bank account
ACHBankAccounts delACHBankAccount=
  ACHBankAccounts.builder()
    .profileId(achBankAccounts.getProfileId())
    .id(achBankAccounts.getId())
    .build();

boolean response=apiClient.customerVaultService().delete(delACHBankAccount);

Managing BACS Bank Accounts

Create a BACS bank account
BACSBankAccounts bacsBankAccounts=
  BACSBankAccounts.builder()
    .nickName("Sally's Bank of Montreal Account")
    .accountNumber("34898396")
    .accountHolderName("Sally")
    .sortCode("070116")
    .billingAddressId(address.getId())
    .profileId(profile.getId())
    .build();

BACSBankAccounts bacsBankAccountsRes=apiClient.customerVaultService().create(bacsBankAccounts);
Create a BACS bank account with a mandate
ArrayList<Mandates> m = new ArrayList<Mandates>();
Mandates mandts =
  Mandates.builder()
    .reference("SUBCRIP345")
    .build();
    m.add(mandts);

BACSBankAccounts bacsBankAccounts=
  BACSBankAccounts.builder()
    .nickName("Sally's Bank of Montreal Account")
    .accountNumber("34898396")
    .accountHolderName("Sally")
    .sortCode("070116")
    .mandates(m)
    .billingAddressId(address.getId())
    .profileId(profile.getId())
    .build());

BACSBankAccounts bacsBankAccountsRes=apiClient.customerVaultService().create(bacsBankAccounts);
Look up a BACS bank account
BACSBankAccounts bacsBankAccounts=
  BACSBankAccounts.builder()
    .profileId(bacsBankAccountsRes.getProfileId())
    .id(bacsBankAccountsRes.getId())
    .build();

BACSBankAccounts response=apiClient.customerVaultService().lookup(bacsBankAccounts);
Update a BACS bank account
BACSBankAccounts bacsBankAccountsToUpdate=
  BACSBankAccounts.builder()
    .nickName("Sally's Bank of Montreal Account")
    .profileId(bacsBankAccountsRes.getProfileId())
    .id(bacsBankAccountsRes.getId())
    .build();

BACSBankAccounts response=apiClient.customerVaultService().update(bacsBankAccountsToUpdate);
Delete a BACS bank account
BACSBankAccounts delbacsBankAccounts=
  BACSBankAccounts.builder()
    .profileId(bacsBankAccountsRes.getProfileId())
    .id(bacsBankAccountsRes.getId())
    .build();

boolean response=apiClient.customerVaultService().delete(delbacsBankAccounts);

Managing EFT Bank Accounts

Create an EFT bank account
EFTBankAccounts eftBankAccounts=
  EFTBankAccounts.builder()
    .nickName("Sally's Bank of Montreal Account")
    .accountNumber("511201")
    .accountHolderName("Sally")
    .transitNumber("25039")
    .institutionId("001")
    .billingAddressId(address.getId())
    .profileId(profile.getId())
    .build();

EFTBankAccounts eftBankAccountsRes=apiClient.customerVaultService().create(eftBankAccounts);
Look up an EFT bank account
EFTBankAccounts eftBankAccounts=
  EFTBankAccounts.builder()
    .profileId(eftBankAccountsRes.getProfileId())
    .id(eftBankAccountsRes.getId())
    .build();

EFTBankAccounts response=apiClient.customerVaultService().lookup(eftBankAccounts);
Update an EFT bank account
EFTBankAccounts eftBankAccountsToUpdate=
  EFTBankAccounts.builder()
    .nickName("Sally's Bank of Montreal Account")
    .profileId(eftBankAccountsRes.getProfileId())
    .id(eftBankAccountsRes.getId())
    .build();

EFTBankAccounts response=apiClient.customerVaultService().update(eftBankAccountsToUpdate);
Delete an EFT bank account
EFTBankAccounts deleftBankAccounts=
  EFTBankAccounts.builder()
    .profileId(eftBankAccountsRes.getProfileId())
    .id(eftBankAccountsRes.getId())
    .build();

boolean response=apiClient.customerVaultService().delete(deleftBankAccounts);

Managing SEPA Bank Accounts

Create a SEPA bank account
SEPABankAccounts sepaBankAccounts=
  SEPABankAccounts.builder()
    .nickName("John RBC Business Bank Account")
    .accountHolderName("XYZ Business")
    .bic("ABNANL2A")
    .iban("NL25BSAB9133933065")
    .billingAddressId(address.getId())
    .profileId(profile.getId())
    .build();

SEPABankAccounts sepaBankAccountsRes=apiClient.customerVaultService().create(sepaBankAccounts);
Create a SEPA bank account with a mandate
ArrayList<Mandates> m = new ArrayList<Mandates>();
  Mandates mandts =
    Mandates.builder()
      .reference("SUBCRIP345")
      .build();
      m.add(mandts);
  SEPABankAccounts sepaBankAccounts=
    SEPABankAccounts.builder()
      .nickName("John RBC Business Bank Account")
      .accountHolderName("XYZ Business")
      .bic("HANDFIHH")
      .mandates(m)
      .iban("AL51934179606309730572538012")
      .billingAddressId(address.getId())
      .profileId(profile.getId())
      .build());

SEPABankAccounts sepaBankAccountsRes=apiClient.customerVaultService().create(sepaBankAccounts);
Look up a SEPA bank account
SEPABankAccounts sepaBankAccounts=
  SEPABankAccounts.builder()
    .profileId(sepaBankAccountsRes.getProfileId())
    .id(sepaBankAccountsRes.getId())
    .build();

SEPABankAccounts response=apiClient.customerVaultService().lookup(sepaBankAccounts);
Update a SEPA bank account
SEPABankAccounts sepaBankAccountsToUpdate=
  SEPABankAccounts.builder()
    .nickName("John RBC Business Bank Account")
    .profileId(sepaBankAccountsRes.getProfileId())
    .id(sepaBankAccountsRes.getId())
    .build();

SEPABankAccounts response=apiClient.customerVaultService().update(sepaBankAccountsToUpdate);
Delete a SEPA bank account
SEPABankAccounts delsepaBankAccounts=
  SEPABankAccounts.builder()
    .profileId(sepaBankAccountsRes.getProfileId())
    .id(sepaBankAccountsRes.getId())
    .build();

boolean response=apiClient.customerVaultService().delete(delsepaBankAccounts);

Mandates

Create a BACS bank account mandate
Mandates mandates=
  Mandates.builder()
    .reference("SUBSCRIPTION103")
    .profileId(profile.getId())
    .bankAccountId(bacsBankAccounts.getId().toString())
    .build();

Mandates mandatesRes=apiClient.customerVaultService().create(mandates,"BACS");
Create a SEPA bank account mandate
Mandates mandates=
  Mandates.builder()
    .reference("SUBSCRIPTION103")
    .profileId(profile.getId())
    .bankAccountId(sepaBankAccounts.getId().toString())
    .build();

Mandates mandatesRes=apiClient.customerVaultService().create(mandates,"SEPA");
Look up a mandate
Mandates mandates=
  Mandates.builder()
    .id(mandatesRes.getId())
    .profileId(mandatesRes.getProfileId())
    .build();

Mandates response=apiClient.customerVaultService().lookup(mandates);
Update a mandate
Mandates mandatesToUpdate=
  Mandates.builder()
    .status(Status.CANCELLED)
    .profileId(mandatesRes.getProfileId())
    .id(mandatesRes.getId())
    .build());

Mandates response=apiClient.customerVaultService().update(mandatesToUpdate);
Delete a mandate
Mandates mandatesToDelete=
  Mandates.builder()
    .id(mandatesRes.getId())
    .profileId(mandatesRes.getProfileId())
    .build());

boolean response=apiClient.customerVaultService().delete(mandatesToDelete);

Process a Payment Using a Payment Token

Process an authorization with a payment token
Authorization auth =
    Authorization.builder()
      .merchantRefNum("0f8fad5bd9cb469fa16570867728950e")
      .amount(1295)
      .settleWithAuth(true)
      .card()
      .paymentToken(card.getPaymentToken())
      .done()
      .build();

apiClient.cardPaymentService().authorize(auth);
Verify a card using a payment token
Authorization auth =
    Authorization.builder()
      .merchantRefNum("0f8fad5bd9cb469fa16570867728950e")
      .card()
        .paymentToken(cardResponse.getPaymentToken())
        .done()
      .build();

Verification verificationResponse = apiClient.cardPaymentService().verify(auth);
Did you find this page useful?