Vault Add Credit Card

Overview

The VaultAddCreditCard API call adds a credit card to an existing and active vault. Subsequently, the VaultPayment API call can use the credit card for payments. VaultAddCreditCard will fail for a deleted or inactive vault.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v1.0/stores/[StoreId]/payments/ vault/creditcard/add/[tenderCode].[format]	/v1.0/stores/TMSNA/payments/ vault/creditcard/add/VC.xml	XML	200 + XML Response containing the response status of adding the credit card to the vault.

Request Format

The request is a VaultAddCreditCardRequest message.

<?xml version="1.0" encoding="UTF-8"?>
<VaultAddCreditCardRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
      sessionId="12345">
  <VaultId>123456</VaultId>
  <PaymentAccountUniqueId isToken="false">4111111111111111</PaymentAccountUniqueId>
  <ExpirationDate>2013-09</ExpirationDate>
  <CardSecurityCode>123</CardSecurityCode>
  <CurrencyCode>USD</CurrencyCode>
  <BillingPersonName>
      <Honorific>Mr.</Honorific>
      <LastName>Smith</LastName>
      <MiddleName>Andrew</MiddleName>
      <FirstName>John</FirstName>
   </BillingPersonName>
  <BillingAddress>
      <Line1>123 Main St</Line1>
      <Line2>Building 123</Line2>
      <Line3>4th Floor</Line3>
      <Line4>Apt 12</Line4>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
   </BillingAddress>
   <CustomerPhoneNo>2152227777</CustomerPhoneNo>
   <CustomerEmail>customer@email.com</CustomerEmail>
   <Notes>customer@email.com</Notes>
</VaultAddCreditCardRequest>

Request Elements

Element	Required	Description	Type	Restriction
VaultId	Yes	Unique identifier for the vault.	String	1 to 38 numeric characters
PaymentAccountUniqueId	Yes: either PaymentAccountUniqueId or EncryptedPayment AccountUniqueId must be present	Either a raw PAN (payment account number such as a credit card number) or a token representing a PAN.	String	Max 22 characters
PaymentAccountUniqueId @isToken	Yes (when PaymentAccountUniqueId is present)	Attribute indicates whether the payment account number is tokenized.	String	true or false
EncryptedPaymentAccountUniqueId	Yes: either PaymentAccountUniqueId or EncryptedPayment AccountUniqueId must be present	Client-encrypted PAN. Used for clients who use client-side encryption to encrypt credit card numbers in the JavaScript that runs in their browser. For a webstore that is not PCI compliant, client-side encryption ensures that the webstore never sees raw PANs.	String	Max 1000 characters
ExpirationDate	Yes	Expiration date of the credit card.	String	yyyy-MM (year followed by month)
CardSecurityCode	Yes: either CardSecurityCode or EncryptedCard SecurityCode must be present	CVV2 code on the back of the credit card.	String	3 or 4 digits
EncryptedCardSecurityCode	Yes: either CardSecurityCode or EncryptedCard SecurityCode must be present	Encrypted form of CVV2 code on the back of the credit card.	String	1000 digits
CurrencyCode	Yes	The currency used for the transaction.	Currency code	Currency codes are defined by ISO 4217:2008. Examples: USD, CAD, EUR
BillingPersonName/ Honorific	No	Salutation of the customer.	String	10 characters.
BillingPersonName/ LastName	Yes	Last name of the customer.	String	64 characters.
BillingPersonName/ MiddleName	No	Middle name of the customer.	String	40 characters.
BillingPersonName/ FirstName	Yes	First name of the customer.	String	64 characters.
BillingAddress/ Line1	Yes	Line# components of the billing street address including, if necessary, suite and building identifiers for the physical address. Line1 is required. Other Line# components are optional.	String	Max 70 characters
BillingAddress/ Line2	No		String	Max 70 characters
BillingAddress Line3	No		String	Max 70 characters
BillingAddres Line4	No		String	Max 70 characters
BillingAddress/ City	Yes	The city of the customer's billing address.	String	Max 40 characters
BillingAddress/ MainDivision	Yes	Two- or three-digit postal abbreviation for the state or province. The ISO 3166-2 code is recommended, but not required.	String	Max 30 characters
BillingAddress/ CountryCode	Yes	Two-digit country code. The ISO 3166 alpha 2 code is recommended, but not required.	String	2-40 characters
BillingAddress/ PostalCode	Depends on country. Yes for US and Canada.	String of letters and/or numbers that specifies the delivery area more closely than the city alone (for example, US ZIP code).	String	Max 30 characters
CustomerPhone	Yes	Phone number of the customer making the purchase. Used for realtime fraud checking by API and payment processors.	String	Max 70 characters
CustomerEmail	Yes	Email address of the customer making the purchase. Used for realtime fraud checking by API and payment processors.	String	Max 70 characters
Notes	No	Memo or alias associated with the specific tender, can be changed by the customer.	String	Max 512 characters
sessionId	Yes	Identifies a request message; used to protect against duplicate request processing.	String	Up to 40 Characters

Response Format

The response is a VaultAddCreditCardReply message.

<?xml version="1.0" encoding="UTF-8"?>
<VaultAddCreditCardReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <VaultId>123456</VaultId>
  <VaultTenderId>21645</VaultTenderId>
  <ResponseCode>Success</ResponseCode>
  <Reason>ok</Reason>
</VaultAddCreditCardReply>

Response Elements

Element	Required	Description	Type	Restriction
VaultId	Yes	Vault identifier echoed back from the request message.	String	1 to 38 numeric characters
VaultTenderId	Yes	New vault tender identifier for the credit card added to the vault.	String	1 to 40 characters
ResponseCode	Yes	Response Code returned from Payment Service.	String	Success, Failure
Reason	No	Reason information for success or failure.	String	No restrictions