performCancel (Cancel a transaction /Following transaction) [ccb by dsb®

This method cancels previously sent batch methods (Capture, Refund or Bookback). It uses the external id (and depending on the credit card gateway, an external token) to reference the method that should be cancelled.

Whether or not the method will be successful is dependent on if the request has not been sent to the payment processor or not. Once the batch methods have been sent to the payment processor, cancellation will fail. Batch methods are generally sent at the end of a working day but this is entirely payment gateway specific and not controllable by the DSB Credit Card Facade. Therefore, it is recommended to cancel as soon as possible in order for this method to be executed successfully.

Object: /net/dsb/commons/CardTransactionProcessing
Method: performCancel
Version: 1.0.0

Parameter

Name	Type / max. length	mandatory?	Description
cancel-request	XML	M	XML-Fragement zur Ausführung einer Stornierung

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>
      <cancel-request>
        <cc-service-provider>ABCD</cc-service-provider>
        <cc-external-transaction-id>ABC000123456789</cc-external-transaction-id>
      </cancel-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>
         <cancel-request>  
         </cancel-request>
         <response>  
         </response>
      </card-transaction>
   </body>
</message>

Request Structure

The transactions that start a payment are:

capture-request
cancel-request
bookback-request

The following sections will describe how the requests need to be built for each transaction. For more information about transaction types see Appendix.

Structure <capture-request>

The structure of this example start transaction is based upon an ”capture-request”. Change the name of the ”capture-request” to call the other services.

<card-transaction>
	<capture-request>
		<request-id>ABCDEFGHIJK</request-id>
		<!-- General data to control the request -->
		<cc-service-provider></cc-service-provider>
		<cc-external-transaction-id></cc-external-transaction-id>
		<cc-external-transaction-token></cc-external-transaction-token>
		<cc-process-mode></cc-process-mode>
		<cc-return-response></cc-return-response>
		<cc-return-original-interaction></cc-return-original-interaction>
		<!-- Identification of the Merchants -->
		<cc-merchant-id></cc-merchant-id>
		<cc-merchant-description></cc-merchant-description>
		<!-- Identification of the request -->
		<cc-request-source></cc-request-source>
		<cc-merchant-transaction-id></cc-merchant-transaction-id>
		<!-- The data of the transaction -->
		<cc-transaction-amount>
			<!-- Either the total price or the price based upon each item -->
			<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>
	</capture-request>
</card-transaction>

Element Definitions

Field	M = Mandatory O =Optional C = Conditional	Length	Type	Description
card-transaction	M	-	C	Element group for a card transaction
capture-request cancel-request bookback-request	M	-	C	The element group for transaction request data. This can be either one of these elements.
request-id	O	50	AN	Unique id
cc-service-provider	M	4	AN	The service provider code where the transaction should be sent. Is a mandatory field
cc-external-transaction-id	C		AN	An id that has been received from a previous response. This is an id received from the directly from the payment gateway.
cc-external-transaction-token	C		AN	An external token that has been received from a previous response. If the response does not contain one, this field can remain empty. Supported by * Cybersource
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-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-merchant-id	M	32	AN	Merchant-ID which identifies the credit card payment gateway account where the transaction should be sent. e. g. business-case if Wirecard is used
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	An 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-transaction-amount				Data which states the amount involved within the transaction either as a Total amount or as a list of items.
amount	C	16	N	Integer values which contains the amount as the smallest unit of currency. (i.e. 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. (i.e. 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 ”reason for payment” string. 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.

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.