performPreAuthorisation (Authorisation queries /Start Transactions) [ccb by dsb®

PreAuthorisation is used for ensuring that credit card data is valid as well as for registering the credit card details so they only need to be sent once (in which case the transaction needs to be marked as an ”Initial transaction”). The next steps in the payment process are usually ”authorisation + capture” or ”purchase”.

Preauthorisation is not supported by all Payment Gateways. When not available preauthorisation is the same as an authorisation with the value of 1 unit of currency (e.g. $1) which has similar semantics.

Supported Gateways:

Wirecard
Object: /net/dsb/commons/CardTransactionProcessing
Method: performPreAuthorisation
Version: 1.0.0

Parameter

Name	Type / max. length	mandatory?	Description
preauthorisation-request	XML	M	The ”response” XML document structure which can be found

Response Element

The response XML document structure, found below

Example Request

<?xml version="1.0" encoding="ISO-8859-1"?> 
<message version="1.0" system="vhs/3" >
  <header>
    <client>4711</client>
    <service-provider>999</service-provider>
  </header>
  <body>
    <card-transaction>
      <preauthorisation-request>
       ..
      </preauthorisation-request>
    </card-transaction>
  </body>
</message>

Example Response

<?xml version="1.0" encoding="ISO-8859-1"?> 
<message version="1.0" system="vhs/3">
   <header>
      <client>4711</client>
      <service-provider>999</service-provider>
   </header>
   <body>
      <card-transaction>
         <preauthorisation-request>  
         </preauthorisation-request>
         <response>  
         </response>
      </card-transaction>
   </body>
</message>

Request Structure

Structure <authorisation-request>

The structure of this example start transaction is based upon an authorisation-request. The ”authorisation-request” tag needs to be changed to call other services.

<card-transaction>
	...
	<authorisation-request>
		<request-id>ABCDEFGHIJK</request-id>
		<!--General data to control the transaction -->
		<cc-service-provider></cc-service-provider>
		<cc-process-type></cc-process-type>
		<cc-process-mode></cc-process-mode>
		<cc-commerce-type></cc-commerce-type>
		<cc-return-request></cc-return-request>
		<cc-return-original-interaction></cc-return-original-interaction>
		<!--Reference by the processing type = Repeating -->
		<cc-repeating-transaction>
			<cc-repeating-transaction-id></cc-repeating-transaction-id>
		</cc-repeating-transaction>
		<!-- Identification of the Merchant -->
		<cc-merchant-id></cc-merchant-id>
		<cc-merchant-description></cc-merchant-description>
		<!-- Request identification -->
		<cc-request-source></cc-request-source>
		<cc-merchant-transaction-id></cc-merchant-transaction-id>
		<!-- Business partner XML fragment -->
		<!-- see the description in the document -->
		<!-- WSI-CoreAVS3-XML-Description_en.pdf or -->
		<!-- WSI-CoreVHS3-XML-Description_en.pdf -->
		<cc-business-partner>...</cc-business-partner>
		<!-- Transaction data -->
		<cc-transaction-amount>
			<!-- Either the total amount or an item list -->
			<amount>
			</amount>
			<item>
				<item-sku></item-sku>
				<item-quantity></item-quantity>
				<item-price></item-price>
			</item>
		</cc-transaction-amount>
		<cc-transaction-currency-code></cc-transaction-currency-code>
		<cc-transaction-country-code></cc-transaction-country-code>
		<cc-transaction-usage>
			<cc-usage-string></cc-usage-string>
		</cc-transaction-usage>
		<cc-data>
			<cc-number></cc-number>
			<cc-cv2></cc-cv2>
			<cc-number-masked></cc-number-masked>
			<cc-cardholder-name></cc-cardholder-name>
			<cc-start-year></cc-start-year>
			<cc-start-month></cc-start-month>
			<cc-expiration-year></cc-expiration-year>
			<cc-expiration-month></cc-expiration-month>
			<cc-issue-number></cc-issue-number>
			<cc-company-code></cc-company-code>
			<cc-type></cc-type>
		</cc-data>
	</authorisation-request>
</card-transaction>

Element Definitions

Field	M = Mandatory O =Optional C = Conditional	Length	Type	Description
card-transaction	M	-	C	The element group for a card transaction
authorisation-request preauthorisation-request purchase-request refund-request	M	-	C	The element group for transaction request data.
request-id	O	50	AN	Unique id
cc-service-provider	C	4	AN	The ID of the Payment Gateway where the request should be sent
cc-process-mode	O	4	AN	Identifies if the transaction is a demo or test transaction. Valid values are: live (Default) : Real transaction demo : Test transaction Note: This tag does not decide if the request will be executed within a production environment or not. The tag only decides if a real transaction will take place. This feature is not support by all payment providers. Supported by: Wirecard
cc-process-type	M	10	AN	Defines the type of processing. Valid values are: Single: Does not return a reference to reuse the credit card data. Use per default. Initial: Returns a reference to reuse the credit card data. Repeating : Make the tag cc-repeating-transaction-id required to be able to reference the credit card details.
cc-commerce-type	O	23	AN	States which type of payment is being sent. Possible Values: eCommerce : via Internet MOTO : via Mail, Phone CustomerPresent : via card terminal (not implemented)
cc-return-request	O	-	B	Controls if the request sent should be echoed within the response. Possible values are: true = yes false = no (default)
cc-return-original-interaction	O	-	B	Controls if the response should include the original request and responses that were sent to the Payment Gateway. Possible values are: true = yes false = no (default)
cc-repeating-transaction	C	-	C	Element group (Collection) , used by transactions that are repeated. When this group is filled cc-process-type should be set to ”Repeating”.
cc-repeating-transaction-id	M	50	AN	Unique external transaction id provided received within a response from a previously sent ”Initial” transaction.
cc-merchant-id	M	32	AN	Merchant-ID which identifies the credit card payment gateway account where the transaction should be sent.
cc-merchant-description	O	50	AN	Description of the merchant.
cc-request-source	M	32	AN	A description from which system the transaction came – for example, the name of the System, the system environment, client, test or production environment.
cc-merchant-transaction-id	M	32	AN	A id that is used to identify the transaction for the system that is sending a request. The maximum length is dependent on the payment gateway.
cc-business-partner	C	-	XML	The XML fragment business-partner. For more information see the documentation for WSI-Core from AVS/3 and VHS/3. This fragment is only needed for processing types ”Initial” and ”Single”.
cc-transaction-amount				Data which states the amount involved within the transaction either as a Total amount or as a list of items. Should not be sent during a Preauthorization. A minimum default value of units will be sent.
amount	C	16	N	Integer values which contains the amount as the smallest unit of currency. (ie EUR 10,00 ⇒ 1000 cent)
list→item-sku	C	13	AN	Article number.
list→item-quantity	C	5	N	Quantity of items
list→item-price	C	16	N	Integer values which contains the amount as the smallest unit of currency. (ie EUR 10,00 ⇒ 1000 cent)
cc-transaction-currency-code	M	3	AN	Transaction currency using the codes described in the ISO 4217 standard.
cc-transaction-country-code	M	2	AN	States the country in which the transaction takes place. The value is a country code using the ISO 3166-1 standard. This element should be sent with all ”Single” and ”Initial” transactions.
cc-transaction-usage	M	-	C	Element that contains an element that describes the transaction usage which the business partner should see on their bank statement. Supported by: Wirecard
cc-usage-string	O	256	AN	The dynamic soft descriptor which states the reason for payment. Note that this field is not supported by all Acquirers or payment Gateways. The length of the information is also dependent on the acquirer and the payment Gateway.
cc-data	C	-	C	Element group for credit card transactions.\\This element is needed only for processing-types ”Single” and ”Initial”.
cc-number	C	256	A	Credit Card Number. Is mandatory if cc-number-masked is not filled.
cc-number-masked	C	20	A	Masked credit card number. E.g. 444433******1111. Used for communication with customers when there are payment problems. Is mandatory if cc-number is not filled.
cc-cv2	C	4	N	3 or 4 digit Credit Card Check Digit Validation that is on the back of a credit card. Has a length of 4 for American Express, otherwise has a length of 3. This is a mandatory field unless it has a recurring type of ”Repeating” (which would therefore reference a previously used credit card details). Not to be used when using the function Refund.
cc-cardholder-name	M	50	AN	Name of the card owner.
cc-start-year	O	4	N	Year, since the card was valid (only needed for specific cards).
cc-start-month	O	2	N	Month, since the card was valid (only needed for specific cards).
cc-expiration-year	M	4	N	Year of the expiry date of the credit card.
cc-expiration-month	M	2	N	Month of the expiry date of the credit card.
cc-issue-number	O	2	N	Credit card issue number (only needed for some card types)
cc-company-code	M	4	AN	Credit Card Institute
cc-type	O	3	AN	Credit card type (e.g. DEL for Visa Delta, ELC for VISA Electron)

Response Structure

Structure <card-transaction> response

<card-transaction>
	<!-- The original request that led to this response. This is -->
	<!-- returned only when cc-return-request is set to ”true” -->
	<...-request>
	</...-request>
	<!-- Response to the request -->
	<response>
		<cc-merchant-id></cc-merchant-id>
		<cc-payment-operation></cc-payment-operation>
		<cc-service-provider></cc-service-provider>
		<!-- Result of the request Requests -->
		<cc-result-status></cc-result-status>
		<cc-result-code></cc-result-code>
 
		<cc-result-message></cc-result-message>
		<cc-result-advice></cc-result-advice>
		<cc-result-timestamp></cc-result-timestamp>
 
		<cc-result-amount></cc-result-amount>
 
		<cc-result-currency></cc-result-currency>
 
		<!-- Reference ids -->
		<cc-dsb-transaction-id></cc-dsb-transaction-id>
		<cc-external-transaction-id></cc-external-transaction-id>
		<cc-external-transaction-token></cc-external-transaction-token>
		<cc-reconciliation-transaction-id></cc-reconciliation-transaction-id>
		<!-- Repeating transactions -->
		<cc-repeating-transaction-id></cc-repeating-transaction-id>
		<!-- Authorisation payment Code -->
		<cc-authorisation-code></cc-authorisation-code>
		<cc-authorisation-timestamp></cc-authorisation-timestamp>
		<cc-data>
			<cc-number></cc-number>
			<cc-cardholder-name></cc-cardholder-name>
			<cc-expiration-year></cc-expiration-year>
			<cc-expiration-month></cc-expiration-month>
			<cc-company-code></cc-company-code>
		</cc-data>
		<dsb-extensions>...</dsb-extensions>
	</response>
	<!-- Original request sent to the payment gateway -->
	<cc-original-request></cc-original-request>
	<!-- Original response received from the payment gateway -->
	<cc-original-response></cc-original-response>
</card-transaction>

Element Definitions

Field	M = Mandatory O =Optional C = Conditional	Length	Type	Description
card-transaction	M	-	C	Element group for a card transaction
…-request	C	-	C	The request that was sent to DSB is echoed back if cc-return-request was set to true.
response	M	-	C	The response to the request sent.
cc-merchant-id	M	4	AN	The merchant-id where the request was sent.
cc-payment-operation	M	4	AN	The payment operation made. Possible values: AUTHORIZE PREAUTHORIZE PURCHASE REFUND CAPTURE BOOKBACK CANCEL
cc-service-provider	M	4	AN	The ID of the Payment Gateway where the request should be sent
cc-result-status	M	10	AN	This element shows the result code of the transaction. Possible values are: OK Transaction was functionally ok and has been processed NOTOK Transaction had a problem and was not processed.
cc-result-code	M	10	AN	The return code of the DSB Web-Services.
cc-result-message	O	1024	AN	Failure message or info message.
cc-result-advice	O	1024	AN	Advice on what the problem is to correct the failure.
cc-result-timestamp	M	19	DT	Timestamp of the result in the format of YYYY-MM-DDTHH:MI:SS
cc-result-amount	M	16	N	The amount that was processed in the request
cc-result-currency	M	3	AN	The currency that the amount is represents.

cc-dsb-transaction-id	M	36	AN	This element must used by the sender and included within a subscription order or a mail-order order so that it can be accounted for within the invoice.
cc-external-transaction-id	M	n. a.	AN	Unique id within the system that identifies the processed transaction.
cc-external-transaction-token	C	n. a.	AN	An external token sent by the payment gateway. It is a payment gateway specific value that identifies the sent transaction so that follow on transaction (e.g. capture) can be made upon it. Required by: Cybersource GlobalCollect
cc-reconciliation-transaction-id	C	n.a	AN	Is returned when a Capture, Refund or Bookback is executed

cc-repeating-transaction-id	C	n. a.	AN	A unique id that reference credit card details that were sent in the request (which had the transaction type of ‘Initial’). This ID can then be used in place of the credit card details so they only need to be sent once.
cc-authorisation-code	C	n. a.	AN	An authorisation code: A numeric or alphanumeric code that is sent to prove that the transaction was authorised. When a failure occurs this tag has no value.
cc-authorisation-timestamp	C	n.a	AN	The time that authorisation was said to have occurred at the payment provider.
cc-data	C		XML	The credit card details
cc-number				The return masked credit card number.
cc-cardholder-name				The credit card holder
cc-expiration-year				The expiry year of the card
cc-expiration-month				The expiry month of the card
cc-company-code				The company code of the card. E.g. VISA, AMEX
cc-original-request	C	n. a.	XML	A #CDATA element which contains the original request that was sent to the payment gateway. Only to be used for internal testing and returned by retrieval methods.
cc-original-response	C	n. a.	XML	A #CDATA element which contains the original response that was retrieved from the payment gateway. Only to be used for internal testing and returned by retrieval methods.
dsb-extensions	C	n. a.	XML	This tag is used to communicate information that has no direct relation to a payment transaction but needed for the back-end system to finish processing the payment.