ProductsDeveloperSupport
Guides

Data Vault Tokenisation

Suggest Edits

With the Data Vault product you can store sensitive cardholder data in an encrypted database in Fiserv’s data centre to use it for subsequent transactions without the need to store this data within your own systems. If you have ordered this feature, the Web Service API offers you the following functions.

Token Types

The type of token can be defined with the optional element TokenType, which can have 2 possible values: ONETIME or MULTIPAY.

The default value (when no token type gets submitted) is MULTIPAY.

One time token (that are only valid for a specific time span) is an option for merchants, which work with tokens for every transaction, no matter if the consumer registers or prefers to check out as a “guest”.
The following XML document represents an example of a request with included elementTokenType = MULTIPAY:

<?xml version="1.0" encoding="UTF-8"?>
<ns4:IPGApiOrderRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
	<ns2:Transaction> 
		<ns2:CreditCardTxType> 
			<ns2:StoreId>330995001</ns2:StoreId> 
			<ns2:Type>sale</ns2:Type> 
		</ns2:CreditCardTxType> 
		<ns2:CreditCardData> 
			<ns2:CardNumber>4035*****4977</ns2:CardNumber> 
			<ns2:ExpMonth>12</ns2:ExpMonth> 
			<ns2:ExpYear>28</ns2:ExpYear> 
			<ns2:CardCodeValue>XXX</ns2:CardCodeValue> 
		</ns2:CreditCardData> 
		<ns2:Payment> 
			<ns2:ChargeTotal>27.2</ns2:ChargeTotal> 
			<ns2:Currency>INR</ns2:Currency> 
			<ns2:TokenType>MULTIPAY</ns2:TokenType>
		</ns2:Payment> 
		<ns2:TransactionDetails> 
			<ns2:TransactionOrigin>ECI</ns2:TransactionOrigin> 
		</ns2:TransactionDetails> 
	</ns2:Transaction> 
</ns4:IPGApiOrderRequest>

The following XML document represents an example of a request with included element TokenType = ONETIME:

<?xml version="1.0" encoding="UTF-8"?>
<ns4:IPGApiOrderRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
	<ns2:Transaction> 
		<ns2:CreditCardTxType> 
			<ns2:StoreId>330995001</ns2:StoreId> 
			<ns2:Type>sale</ns2:Type> 
		</ns2:CreditCardTxType> 
		<ns2:CreditCardData> 
			<ns2:CardNumber>4035*****4977</ns2:CardNumber> 
			<ns2:ExpMonth>12</ns2:ExpMonth> 
			<ns2:ExpYear>28</ns2:ExpYear> 
			<ns2:CardCodeValue>XXX</ns2:CardCodeValue> 
		</ns2:CreditCardData> 
		<ns2:Payment> 
			<ns2:ChargeTotal>27.2</ns2:ChargeTotal> 
			<ns2:Currency>INR</ns2:Currency> 
			<ns2:TokenType>ONETIME</ns2:TokenType> 
		</ns2:Payment> 
		<ns2:TransactionDetails> 
			<ns2:TransactionOrigin>ECI</ns2:TransactionOrigin> 
		</ns2:TransactionDetails> 
	</ns2:Transaction> 
</ns4:IPGApiOrderRequest>

For cases, where you do not wish to define the token yourselves, but want it to be generated and returned, the element AssignToken should be set to ‘true’ and no HostedDataId needs to be sent in the request.

The following XML document represents an example of a request for getting the token generated by Gateway, with the element AssignToken = true and an example of a response with the token generated in the element HostedDataID:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Header/>
   <soap:Body>
      <ns5:IPGApiOrderRequest 
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1"> 
    <ns2:Transaction>
        <ns2:CreditCardTxType>
            <ns2:StoreId>2209905999</ns2:StoreId>
            <ns2:Type>sale</ns2:Type>
        </ns2:CreditCardTxType>
        <ns2:CreditCardData>
            <ns2:CardNumber>4257******0111</ns2:CardNumber>
            <ns2:ExpMonth>12</ns2:ExpMonth>
            <ns2:ExpYear>27</ns2:ExpYear>
            <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
        </ns2:CreditCardData>
        <ns2:Payment>
            <ns2:ChargeTotal>700.00</ns2:ChargeTotal>
            <ns2:Currency>GBP</ns2:Currency>
            <ns2:AssignToken>true</ns2:AssignToken>
        </ns2:Payment>
        <ns2:TransactionDetails>
            <ns2:TransactionOrigin>MOTO</ns2:TransactionOrigin>
        </ns2:TransactionDetails>
        <ns2:Billing>
            <ns2:Address1>Flat 412a  123 London Rd</ns2:Address1>
            <ns2:City>London</ns2:City>
            <ns2:Zip>CH488AQ</ns2:Zip>
            <ns2:Country>GB</ns2:Country>
        </ns2:Billing>
    </ns2:Transaction>
</ns5:IPGApiOrderRequest>
   </soap:Body>
</soap:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ipgapi:IPGApiOrderResponse 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
         <ipgapi:ApprovalCode>Y:609287:8383366115:PPXP:006295</ipgapi:ApprovalCode>
         <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
         <ipgapi:Brand>VISA</ipgapi:Brand>
         <ipgapi:Country>ESP</ipgapi:Country>
         <ipgapi:CommercialServiceProvider>CARDNET</ipgapi:CommercialServiceProvider>
         <ipgapi:OrderId>A-0dd18b32-bc19-40ea-8173-80537093b18f</ipgapi:OrderId>
         <ipgapi:IpgTransactionId>8383366115</ipgapi:IpgTransactionId>
         <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
         <ipgapi:ProcessorApprovalCode>609287</ipgapi:ProcessorApprovalCode>
         <ipgapi:ProcessorCCVResponse>P</ipgapi:ProcessorCCVResponse>
         <ipgapi:ProcessorReferenceNumber>702514006295</ipgapi:ProcessorReferenceNumber>
         <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
         <ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
         <ipgapi:TDate>1485354544</ipgapi:TDate>
         <ipgapi:TDateFormatted>2017.01.25 15:29:04 (MEZ)</ipgapi:TDateFormatted>
         <ipgapi:TerminalID>IPGCNP00</ipgapi:TerminalID>
         <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
         <ipgapi:TransactionTime>1485354544</ipgapi:TransactionTime>
         <ipgapi:HostedData>
            <ipgapi:HostedDataID>7F98D913-85CF-4B88-B994-B59CB0D4AEB2</ipgapi:HostedDataID>
         </ipgapi:HostedData>
      </ipgapi:IPGApiOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Store or update payment information during transaction processing

Additionally send the parameter HostedDataID together with the transaction data as a unique identification for the payment information in this transaction. Depending on the payment type, credit card number and expiry date or account number and bank code will be stored under this ID. In cases where the submitted HostedDataID already exists for your store, the stored payment information will be updated.

<ipgapi:IPGApiOrderRequest 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
		<v1:Transaction>
			<v1:CreditCardTxType>
				<v1:Type>sale</v1:Type>
			</v1:CreditCardTxType>
			<v1:CreditCardData>
				<v1:CardNumber>4111********1111</v1:CardNumber>
				<v1:ExpMonth>12</v1:ExpMonth>
				<v1:ExpYear>27</v1:ExpYear>
			</v1:CreditCardData>
			<v1:Payment>
				<v1:HostedDataID>HDID customer1234567</v1:HostedDataID>
				<v1:ChargeTotal>19.00</v1:ChargeTotal>
				<v1:Currency>978</v1:Currency>
			</v1:Payment>
		</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

Store payment information from an approved transaction

Payment information can also be stored referring to a previously approved transaction

 <ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
            <ns2:Action>
                <ns2:StoreHostedData>
                    <ns2:DataStorageItem>
                        <ns2:OrderId>1234567890</ns2:OrderId>
                        <ns2:HostedDataID>4e72021b-d155-4062-872a-30228c0fe023</ns2:HostedDataID>
                    </ns2:DataStorageItem>
                </ns2:StoreHostedData>
            </ns2:Action>
</ns4:IPGApiActionRequest>

This action stores the payment information of the transaction with the order id 1234567890. The transaction must be an approved transaction, otherwise this action fails.

Initiate payment transactions using stored data

If you stored cardholder information using the Data Vault product, you can perform transactions using the HostedDataID without the need to pass the credit card or bank account data again.

❗️

Please note, that it is not allowed to store the card code (in most cases on the back of the card) so that for credit card transactions, the cardholder still needs to enter this value

For the checkout process in your webshop, we recommend that you also store the last four digits of the credit card number on your side and display it when it comes to payment. In that way the cardholder can see which of his maybe several cards has been registered in your shop and will be used for this payment transaction.

<ipgapi:IPGApiOrderRequest 
	xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
	<v1:Transaction>
		<v1:CreditCardTxType>
			<v1:Type>sale</v1:Type>
		</v1:CreditCardTxType>
		<v1:Payment>
			<v1:HostedDataID>HDIDcustomer1234567</v1:HostedDataID>
			<v1:ChargeTotal>19.00</v1:ChargeTotal>
			<v1:Currency>978</v1:Currency>
		</v1:Payment>
	</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

Store payment information without performing a transaction

Besides the possibility to store new records when performing a payment transaction, you can store payment information using an Action Request. In that way it is also possible to upload multiple records at once.

The following example shows the upload for a record with credit card data as well as the direct debit data. Please note that also in this case, existing records will be updated if the HostedDataID is the same. The result for a successful storage contains the HostedDataID.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
    <soapenv:Header/>
    <soapenv:Body>
        <ipg:IPGApiActionRequest>
            <a1:Action>
                <a1:StoreHostedData>
								<a1:StoreId>120992233</a1:StoreId>
                <a1:DataStorageItem>
			          <a1:DE_DirectDebitData>                     
		        	     <v1:IBAN>DE**34*************1604</v1:IBAN>                           
           		    	<v1:MandateReference>12/12/19</v1:MandateReference>
                 </a1:DE_DirectDebitData>
                 <a1:AssignToken>true</a1:AssignToken>
                 <a1:BillingName>Test User</a1:BillingName>
                </a1:DataStorageItem>
                <a1:DataStorageItem>
                 <a1:CreditCardData>
                          <v1:CardNumber>5426******4979</v1:CardNumber>
                          <v1:ExpMonth>12</v1:ExpMonth>
                          <v1:ExpYear>27</v1:ExpYear>
                          <v1:CardCodeValue>XXX</v1:CardCodeValue>
                 </a1:CreditCardData>
                 <a1:AssignToken>true</a1:AssignToken>
                </a1:DataStorageItem>
                </a1:StoreHostedData>
            </a1:Action>
        </ipg:IPGApiActionRequest>
    </soapenv:Body>
</soapenv:Envelope>

<ipgapi:IPGApiActionResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
            <ipgapi:DataStorageItem>
                <a1:DE_DirectDebitData>
                    <v1:BIC>PBNKDEFFXXX</v1:BIC>
                    <v1:IBAN>DE**34*******1604</v1:IBAN>
                    <v1:BankCode>50010060</v1:BankCode>
                    <v1:AccountNumber>32121604</v1:AccountNumber>
                </a1:DE_DirectDebitData>
                <a1:HostedDataID>0EFC3495-4F4F-4A1B-BCA5-C81F80D834C0</a1:HostedDataID>
            </ipgapi:DataStorageItem>
            <ipgapi:DataStorageItem>
                <a1:CreditCardData>
                    <v1:CardNumber>5426******4979</v1:CardNumber>
                    <v1:ExpMonth>12</v1:ExpMonth>
                    <v1:ExpYear>27</v1:ExpYear>
                    <v1:Brand>MASTERCARD</v1:Brand>
                </a1:CreditCardData>
                <a1:HostedDataID>136DFF32-5BE3-4FCE-A537-6F491DA31039</a1:HostedDataID>
            </ipgapi:DataStorageItem>
        </ipgapi:IPGApiActionResponse>

Example of Request to store the data under given hostedDataID and a result for a successful storage which contains the value true for the parameter <ns4:successfully>:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
            <ns2:Action>
              <ns2:StoreHostedData>
                <ns2:DataStorageItem>
                    <ns2:CreditCardData>
														<ns3:CardNumber>4035******4977</ns3:CardNumber>
                            <ns3:ExpMonth>12</ns3:ExpMonth>
                            <ns3:ExpYear>27</ns3:ExpYear>
                        </ns2:CreditCardData>
 										<ns2:HostedDataID>2a356872-54c7-4d09-800c-0be221e72edb</ns2:HostedDataID>
                    </ns2:DataStorageItem>
                    <ns2:DataStorageItem>
                        <ns2:DE_DirectDebitData>
                            <ns3:BankCode>50010060</ns3:BankCode>
                            <ns3:AccountNumber>32121604</ns3:AccountNumber>
                        </ns2:DE_DirectDebitData>
                        <ns2:HostedDataID>6f6de992-e484-4a68-a520-5f3a32e46fad</ns2:HostedDataID>
                        <ns2:Billing>Name>Test Owner</ns2:BillingName>
                    </ns2:DataStorageItem>
                </ns2:StoreHostedData>
            </ns2:Action>
        </ns4:IPGApiActionRequest>
    </SOAP-ENV:Body>	
</SOAP-ENV:Envelope>


<ns4:IPGApiActionResponse 
		xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
		xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" 
		xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
	<ns4:successfully>true</ns4:successfully>
</ns4:IPGApiActionResponse>

In cases where one or more records have not been stored successfully, the corresponding Hosted Data IDs are marked in the result:

<ns4:IPGApiActionResponse 
		xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" 
		xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" 
		xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
	<ns4:successfully>true</ns4:successfully>
	<ns2:Error Code="SGSDAS-020300">
		<ns2:ErrorMessage>
			Could not store the hosted data id:
691c7cb3-a752-4d6d-abde-83cad63de258.
Reason: An internal error has occured while processing your request
		</ns2:ErrorMessage>
	</ns2:Error>
</ns4:IPGApiActionResponse>

Example of response in case of missing mandatory parameter:

<ipgapi:IPGApiActionResponse 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
 <a1:Error>
      <a1:ErrorMessage>Billing Name is mandatory while creating hosted data for SEPA direct debit.</a1:ErrorMessage>
</a1:Error>
<ipgapi:IPGApiActionResponse>

Example of response in case where hosted data has not been stored successfully

<ipgapi:IPGApiActionResponse xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
            <a1:Error>
                <a1:ErrorMessage>hosted data id: E99F19BB9D4F4503B8908D9F86C183F8. Invalid expiration date: CreditCard [cardNumber=492181...2311, expirationMonth=3, expirationYear=2020, trackData=(masked), trackOneData=(masked), trackTwoData=(masked), cardCodeValue=(len:null, isChipCard=null, enrichedCreditCard=EnrichedCreditCard [typeString=null, issuername=null, country=null, binCreditCardTypes=[], creditCardInformationList=[], creditCardType=null, cardFunction=null, commercialCardType=null]]
								</a1:ErrorMessage>
            </a1:Error>
        </ipgapi:IPGApiActionResponse>

Avoid duplicate cardholder data for multiple records

To avoid customers using the same cardholder data for multiple user accounts, the additional tag DeclineHostedDataDuplicates can be sent along with the request. The valid values for this tag are true/false. If the value for this tag is set to true and the cardholder data in the request is already found to be associated with another hosteddataid, the transaction will be declined. Existing records can be displayed using the action Display:

7. Display stored records

Existing records can be displayed using the action Display. The response contains the stored information. For security reasons, only the first 6 and last 4 digits of credit card numbers are being sent back.

<ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
		<ns3:Action>
			<ns3:StoreHostedData>
				<ns3:DataStorageItem>
					<ns3:Function>display</ns3:Function>
					<ns3:HostedDataID>d56feaaf-2d96-4159-8fd6-887e07fc9052</ns3:HostedDataID>
				</ns3:DataStorageItem>
			</ns3:StoreHostedData>
		</ns3:Action>
</ns4:IPGApiActionRequest>

<ns4:IPGApiActionResponse 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
		<ns4:successfully>true</ns4:successfully>
		<ns4:DataStorageItem>
			<ns2:CreditCardData>
				<ns3:CardNumber>4035*****4977</ns3:CardNumber>
				<ns3:ExpMonth>12</ns3:ExpMonth>
				<ns3:ExpYear>27</ns3:ExpYear>
			</ns2:CreditCardData>
			<ns2:HostedDataID>d56feaaf-2d96-4159-8fd6-887e07fc9052</ns2:HostedDataID>
		</ns4:DataStorageItem>
</ns4:IPGApiActionResponse>

If the Hosted Data ID does not exist, the API response indicates an error:

<ns4:IPGApiActionResponse 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
		<ns4:successfully>true</ns4:successfully>
		<ns2:Error Code="SGSDAS-020301">
			<ns2:ErrorMessage>Hosted data id:6c814261-a843-49fb-bacd-1411d3780286 not found.</ns2:ErrorMessage>
		</ns2:Error>
</ns4:IPGApiActionResponse>

The value successfully contains false, only if the data vault can’t determined because the request finished in an error.

Delete existing record

The action Delete allows you to remove data records that are no longer needed: 

<ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
	<ns3:Action>
		<ns3:StoreHostedData>
			<ns3:DataStorageItem>
				<ns3:Function>delete</ns3:Function>
				<ns3:HostedDataID>9605c2d1-428c-4de2-940e-4bec4737ab5d</ns3:HostedDataID>
			</ns3:DataStorageItem>
		</ns3:StoreHostedData>
	</ns3:Action>
</ns4:IPGApiActionRequest>

A successful deletion will be confirmed with the following response:

<ns4:IPGApiActionRequest 
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
	<ns3:Action>
		<ns3:StoreHostedData>
			<ns3:DataStorageItem>
				<ns3:Function>delete</ns3:Function>
				<ns3:HostedDataID>9605c2d1-428c-4de2-940e-4bec4737ab5d</ns3:HostedDataID>
			</ns3:DataStorageItem>
		</ns3:StoreHostedData>
	</ns3:Action>
</ns4:IPGApiActionRequest>

Updated 3 months ago

API Products

Point of Sale

Developer

Resources

Contact Cookies Privacy Notice Legal

Copyright© 2024 Fiserv. All rights reserved.

First Data Europe Limited, is a subsidiary of Fiserv, Inc. and is trading as Fiserv. First Data Europe Limited, is a private limited company incorporated in England (Company Number 02012925) with a registered address at Janus House, Endeavour Drive, Basildon, Essex, SS14 3WF. First Data Europe Limited is authorised and regulated by the UK Financial Conduct Authority (FCA Register No. 582703; CCA No. 739230). All trademarks, service marks, and trade names referenced in this material are the property of their respective owners.

v1.11

Want a quick overview?