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

response_object = self.client.customer_vault_service_handler().monitor()

Customer Profile

Create a customer profile
profile_obj = Profile(None)
profile_obj.merchantCustomerId(RandomTokenGenerator().generateToken())
profile_obj.locale("en_US")
profile_obj.firstName("John")
profile_obj.lastName("Smith")
profile_obj.email("john.smith@somedomain.com")
profile_obj.phone("713-444-5555")
response_object = self. optimal_api_object.customer_vault_service_handler().create_profile(profile_obj)
Create a customer profile using a single-use token
profile_obj = Profile(None)
profile_obj.merchantCustomerId(RandomTokenGenerator().generateToken())
profile_obj.locale("en_US")
profile_obj.firstName("John")
profile_obj.lastName("Smith")
profile_obj.email("john.smith@somedomain.com")
profile_obj.phone("713-444-5555")
card_obj = Card(None)
card_obj.singleUseToken("SCO0Jpx9JUP9hESh")
profile_obj.card(card_obj)
response_object = self. optimal_api_object.customer_vault_service_handler().create_profile(profile_obj)
Look up a customer profile
profile_obj = Profile(None)
profile_obj.id("d1ecd379-58d3-4850-abce-744efb1eea91")
response_object = self. optimal_api_object.customer_vault_service_handler().lookup_profile(profile_obj)
Update a customer profile
profile_obj = Profile(None)
profile_obj.id("e5f567a2-6661-45ef-8103-48069c51c6a2")
profile_obj.merchantCustomerId("4y7t56kdls6u25yh")
profile_obj.locale("en_US")
profile_obj.firstName("John")
profile_obj.middleName("Wilbur")
profile_obj.lastName("")
profile_obj.gender("M")
profile_obj.email("")
dob = DateOfBirth(None)
dob.day("27")
dob.month("12")
dob.year("1990")
profile_obj.dateOfBirth(dob)
response_object = self. optimal_api_object.customer_vault_service_handler().update_profile(profile_obj)
Delete a customer profile
profile_obj = Profile(None)
profile_obj.id("d1ecd379-58d3-4850-abce-744efb1eea91")
response_object = self. optimal_api_object.customer_vault_service_handler().delete_profile(profile_obj)

Profile Addresses

Create a customer address
address_obj = Address(None)
profile_obj = Profile(None)
address_obj.nickName("home")
address_obj.street("100 Queen Street West")
address_obj.street2("Unit 201")
address_obj.city("Toronto")
address_obj.country("CA")
address_obj.state("ON")
address_obj.zip("M5H 2N2")
address_obj.phone("647-788-3901")
address_obj.recipientName("Jane Doe")
profile_obj.id("0dcdc277-c024-4cd4-b7c4-1a43fa733c8f")
address_obj.profile(profile_obj)
response_object = self. optimal_api_object.customer_vault_service_handler().create_address(address_obj)
Look up a customer address
address_obj = Address(None)
profile_obj = Profile(None)
address_obj.id("7fc8a442-88c9-45d1-a480-88d45a532816")
profile_obj.id("f920d2a3-6582-4cc2-acc6-bdf7cfa626a3")
address_obj.profile(profile_obj)
response_object = self. optimal_api_object.customer_vault_service_handler().lookup_address(address_obj)
Update a customer address
address_obj = Address(None)
profile_obj = Profile(None)
address_obj.id("f6bb6f41-962b-4cb3-8011-53cc7be60d29")
address_obj.country("CA")
address_obj.city("Toronto")
address_obj.nickName("home")
address_obj.street("323 Queen Street West")
address_obj.state("ON")
address_obj.zip("M5H 2N2")
address_obj.recipientName("Jane Doe")
address_obj.phone("647-788-3901")
profile_obj.id("f920d2a3-6582-4cc2-acc6-bdf7cfa626a3")
address_obj.profile(profile_obj)
response_object = self. optimal_api_object.customer_vault_service_handler().update_address(address_obj)
Delete a customer address
address_obj = Address(None)
profile_obj = Profile(None)
address_obj.id("7fc8a442-88c9-45d1-a480-88d45a532816")
profile_obj.id("f920d2a3-6582-4cc2-acc6-bdf7cfa626a3")
address_obj.profile(profile_obj)
response_object = self. optimal_api_object.customer_vault_service_handler().delete_address(address_obj)

Profile Cards

Create a customer card
profile_obj = Profile(None)
card_obj = Card(None)
card_exp_obj = CardExpiry(None)
card_obj.nickName("John's corporate Visa")
card_obj.holderName("MR. JOHN SMITH")
card_obj.cardNum("4530910000012345")
card_obj.billingAddressId("779c7930-8a3c-474f-8788-9aeea2558b27")
card_obj.defaultCardIndicator("true")
card_exp_obj.month("12")
card_exp_obj.year("2019")
profile_obj.id("0dcdc277-c024-4cd4-b7c4-1a43fa733c8f")
card_obj.profile(profile_obj)
card_obj.cardExpiry(card_exp_obj)
response_object = self.client.customer_vault_service_handler().create_card(card_obj)
Look up a customer card
profile_obj = Profile(None)
card_obj = Card(None)
card_obj.id("492d583b-4360-4cae-affe-1d7fc8cb3a7b")
profile_obj.id("f920d2a3-6582-4cc2-acc6-bdf7cfa626a3")
card_obj.profile(profile_obj)
response_object = self.client.customer_vault_service_handler().lookup_card(card_obj)
Update a customer card
profile_obj = Profile(None)
card_obj = Card(None)
card_exp_obj = CardExpiry(None)
card_obj.id("0ee626fe-44fb-46b2-97a1-53795bd24d40")
card_obj.holderName("MR. JOHN JAMES SMITH")
card_obj.defaultCardIndicator("true")
card_exp_obj.month("12")
card_exp_obj.year("2019")
profile_obj.id("6ce868cf-5488-414c-87a1-d51dc461a3e2")
card_obj.profile(profile_obj)
card_obj.cardExpiry(card_exp_obj)
response_object = self.client.customer_vault_service_handler().update_card(card_obj)
Delete a customer card
profile_obj = Profile(None)
card_obj = Card(None)
card_obj.id("492d583b-4360-4cae-affe-1d7fc8cb3a7b")
profile_obj.id("f920d2a3-6582-4cc2-acc6-bdf7cfa626a3")
card_obj.profile(profile_obj)
response_object = self.client.customer_vault_service_handler().delete_card(card_obj)

Profile Bank Accounts

Managing ACH Bank Accounts

Create an ACH bank account
achbankaccount_obj = ACHBankAccount(None)
achbankaccount_obj.nickName("John's RBC Business Bank Account")
achbankaccount_obj.accountNumber(RandomTokenGenerator().generateNumber())
achbankaccount_obj.routingNumber("123456789")
achbankaccount_obj.accountHolderName("XYZ Business")
achbankaccount_obj.billingAddressId("7994e959-166f-4e6b-a3c9-21692148fc58")
achbankaccount_obj.accountType("CHECKING")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

achbankaccount_obj.profile(profile_obj)
response_object = self.client.customer_vault_service_handler().create_ach_bank_account(achbankaccount_obj)
Look up an ACH bank account
achbankaccount_obj = ACHBankAccount(None)
achbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")
achbankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().lookup_ach_bank_account(achbankaccount_obj)
Update an ACH bank account
achbankaccount_obj = ACHBankAccount(None)
achbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")

achbankaccount_obj.nickName("John's RBC Business Bank Account")
achbankaccount_obj.accountNumber("511201")
achbankaccount_obj.routingNumber("123456789")
achbankaccount_obj.accountHolderName("XYZ Business")
achbankaccount_obj.billingAddressId("7994e959-166f-4e6b-a3c9-21692148fc58")
achbankaccount_obj.accountType("SAVINGS")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")
achbankaccount_obj.profile(profile_obj)

response_object4 = self.client.customer_vault_service_handler().update_ach_bank_account(achbankaccount_obj)
Delete an ACH bank account
achbankaccount_obj = ACHBankAccount(None)
achbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")
achbankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().delete_ach_bank_account(achbankaccount_obj)

Managing BACS Bank Accounts

Create a BACS bank account
bacsbankaccount_obj = BACSBankAccount(None)
bacsbankaccount_obj.nickName("Sally's Barclays Account")
bacsbankaccount_obj.accountHolderName("Sally Barnes")
bacsbankaccount_obj.accountNumber(RandomTokenGenerator().generateNumber())
bacsbankaccount_obj.sortCode("207405")
bacsbankaccount_obj.billingAddressId("7994e959-166f-4e6b-a3c9-21692148fc58")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

bacsbankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().create_bacs_bank_account(bacsbankaccount_obj)
Create a BACS bank account with a mandate
bacsbankaccount_obj = BACSBankAccount(None)
bacsbankaccount_obj.nickName("Sally's Barclays Account")
bacsbankaccount_obj.accountHolderName("Sally Barnes")
bacsbankaccount_obj.accountNumber(RandomTokenGenerator().generateNumber())
bacsbankaccount_obj.sortCode("207405")
bacsbankaccount_obj.billingAddressId("7994e959-166f-4e6b-a3c9-21692148fc58")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")
mandates_obj = Mandates(None)
mandates_obj.reference("SUBSCRIP45")
bacsbankaccount_obj.profile(profile_obj)
bacsbankaccount_obj.mandates(mandates_obj)
response_object = self.client.customer_vault_service_handler().create_bacs_bank_account(bacsbankaccount_obj)
Look up a BACS bank account
bacsbankaccount_obj = BACSBankAccount(None)
bacsbankaccount_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

profile_obj = Profile(None)
profile_obj.id("7994e959-166f-4e6b-a3c9-21692148fc58")

bacsbankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().lookup_bacs_bank_account(bacsbankaccount_obj)
Update a BACS bank account
bacsbankaccount_obj = BACSBankAccount(None)
bacsbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")
bacsbankaccount_obj.nickName("Sally's Barclays Account")
bacsbankaccount_obj.merchantRefNum("8hrf983hf89djwjfsdk")
bacsbankaccount_obj.accountHolderName("Sally")
bacsbankaccount_obj.billingAddressId("7994e959-166f-4e6b-a3c9-21692148fc58")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

bacsbankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().update_bacs_bank_account(bacsbankaccount_obj)
Delete a BACS bank account
bacsbankaccount_obj = BACSBankAccount(None)
bacsbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

bacsbankaccount_obj.profile(profile_obj3)

response_object = self.client.customer_vault_service_handler().update_bacs_bank_account(bacsbankaccount_obj)

Managing EFT Bank Accounts

Create an EFT bank account
eftbankaccount_obj = EFTBankAccount(None)
eftbankaccount_obj.nickName("Sally's Bank of Montreal Account")
eftbankaccount_obj.accountHolderName("Sally")
eftbankaccount_obj.accountNumber(RandomTokenGenerator().generateNumber())
eftbankaccount_obj.transitNumber("25039")
eftbankaccount_obj.institutionId("001")
eftbankaccount_obj.billingAddressId("60022f38-fd17-4731-909c-923930d0d5d4")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

eftbankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().create_eft_bank_account(eftbankaccount_obj)
Look up an EFT bank account
eftbankaccount_obj = EFTBankAccount(None)
eftbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

eftbankaccount_obj.profile(profile_obj)
response_object = self.client.customer_vault_service_handler().lookup_eft_bank_account(eftbankaccount_obj)
Update an EFT bank account
eftbankaccount_obj = EFTBankAccount(None)
eftbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")
eftbankaccount_obj.nickName("Sally's Bank of Montreal Account 1")
eftbankaccount_obj.accountHolderName("Sally")
eftbankaccount_obj.transitNumber("25039")
eftbankaccount_obj.institutionId("001")
eftbankaccount_obj.billingAddressId("60022f38-fd17-4731-909c-923930d0d5d4")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

eftbankaccount_obj.profile(profile_obj)
response_object = self.client.customer_vault_service_handler().update_eft_bank_account(eftbankaccount_obj)
Delete an EFT bank account
eftbankaccount_obj = EFTBankAccount(None)
eftbankaccount_obj.id("6a275b7c-6f11-4ed1-ae77-21071724574a")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

eftbankaccount_obj.profile(profile_obj)
response_object = self.client.customer_vault_service_handler().delete_eft_bank_account(eftbankaccount_obj)

Managing SEPA Bank Accounts

Create a SEPA bank account
sepabankaccount_obj = SEPABankAccount(None)
sepabankaccount_obj.nickName("Sally's Account")
sepabankaccount_obj.accountHolderName("Sally Barnes")
sepabankaccount_obj.iban("TN5914207207100707129648")
sepabankaccount_obj.bic("ABNANL2A")
sepabankaccount_obj.billingAddressId("60022f38-fd17-4731-909c-923930d0d5d4")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

sepabankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().create_sepa_bank_account(sepabankaccount_obj)
Create a SEPA bank account with a mandate
sepabankaccount_obj = SEPABankAccount(None)
sepabankaccount_obj.nickName("Sally's Account")
sepabankaccount_obj.accountHolderName("Sally Barnes")
sepabankaccount_obj.iban("TN5914207207100707129648")
sepabankaccount_obj.bic("ABNANL2A")
sepabankaccount_obj.billingAddressId("60022f38-fd17-4731-909c-923930d0d5d4")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

mandates_obj = Mandates(None)
mandates_obj.reference("SUBSCRIP45")

sepabankaccount_obj.profile(profile_obj)
sepabankaccount_obj.mandates(mandates_obj)

response_object = self.client.customer_vault_service_handler().create_sepa_bank_account(sepabankaccount_obj)
Look up a SEPA bank account
sepabankaccount_obj = SEPABankAccount(None)
sepabankaccount_obj.id("60022f38-fd17-4731-909c-923930d0d5d4")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

sepabankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().lookup_sepa_bank_account(sepabankaccount_obj)
Update a SEPA bank account
sepabankaccount_obj = SEPABankAccount(None)
sepabankaccount_obj.id("60022f38-fd17-4731-909c-923930d0d5d4")
sepabankaccount_obj.nickName("Sally's Account")
sepabankaccount_obj.merchantRefNum("8hrf983hf89djwjfsdk")
sepabankaccount_obj.accountHolderName("Sally Barnes")
sepabankaccount_obj.billingAddressId("60022f38-fd17-4731-909c-923930d0d5d4")
sepabankaccount_obj.iban("TN5914207207100707129648");

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

sepabankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().update_sepa_bank_account(sepabankaccount_obj)
Delete a SEPA bank account
sepabankaccount_obj = SEPABankAccount(None)
sepabankaccount_obj.id("60022f38-fd17-4731-909c-923930d0d5d4")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

sepabankaccount_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().delete_sepa_bank_account(sepabankaccount_obj)

Mandates

Create a BACS bank account mandate
mandates_obj = Mandates(None)
mandates_obj.reference(RandomTokenGenerator().generateToken())

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

bacsbankaccount_obj = BACSBankAccount(None)
bacsbankaccount_obj.id("60022f38-fd17-4731-909c-923930d0d5d4")

mandates_obj.profile(profile_obj)
mandates_obj.bacs(bacsbankaccount_obj)

response_object = self.client.customer_vault_service_handler().create_mandates_bacs_bank(mandates_obj)
Create a SEPA bank account mandate
mandates_obj = Mandates(None)
mandates_obj.reference("SUBSCRIPTION105")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

sepabankaccount_obj = SEPABankAccount(None)
sepabankaccount_obj.id("60022f38-fd17-4731-909c-923930d0d5d4")

mandates_obj.profile(profile_obj)
mandates_obj.sepa(sepabankaccount_obj)

response_object = self.client.customer_vault_service_handler().create_mandates_sepa_bank(mandates_obj)
Look up a mandate
mandates_obj = Mandates(None)
mandates_obj.id("e250fdeb-dceb-4953-9268-8305d06b9292")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

mandates_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().lookup_mandates(mandates_obj)
Update a mandate
mandates_obj = Mandates(None)
mandates_obj.id("e250fdeb-dceb-4953-9268-8305d06b9292")
mandates_obj.status("CANCELLED")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

mandates_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().update_mandates(mandates_obj)
Delete a mandate
mandates_obj = Mandates(None)
mandates_obj.id("e250fdeb-dceb-4953-9268-8305d06b9292")

profile_obj = Profile(None)
profile_obj.id("a7b218e7-290a-4434-aea2-a1f985fc26c0")

mandates_obj.profile(profile_obj)

response_object = self.client.customer_vault_service_handler().delete_mandates(mandates_obj)

Process a Payment Using a Payment Token

Process an authorization with a payment token
auth_obj = Authorization(None)
card_obj = Card(None)
auth_obj.merchantRefNum(RandomTokenGenerator().generateToken())
auth_obj.amount("1000")
card_obj.paymentToken("Ca7aO2wuj6xxJVJ")
auth_obj.card(card_obj)
response_object = self.client.card_payments_service_handler().create_authorization(auth_obj)
Verify a card using a payment token
verify_obj = Verification(None)
card_obj = Card(None)
verify_obj.merchantRefNum("rp12jb19igryjqff")
card_obj.paymentToken("C7dEdq9Mcz4nwyy")
verify_obj.card(card_obj)
response_object = self.client.card_payments_service_handler().verify_card(verify_obj)
Did you find this page useful?