Transaction Interface

The Transaction Interface is an extension to Payment Page Interface intended for a more modular und seamless integration of the payment process and thus offers a wide variety of functions to process and handle payments. It can be operated in parallel with the Payment Page Interface or alone. It offers the Hosted Entry Form (HEF) to process card payments seamlessly. Please read chapter Iframe Integration and CSS for examples of the different payment forms. This interface can also be used in combination with Secure Card Data to store/tokenize payment data during the payment process.

Apart from the processing of payments via the Hosted Entry from, it also offers various functions to process payments without payer interaction which is for example required when performing recurring payments or one click checkouts. The Transaction Interface can also be used to process payments with PCI certification of the levels SAQ-A EP and higher during which the payment data are collected directly be the merchant’s systems and forwarded to Saferpay.

1. Transaction Initialize
   • Initializes the Payment and generates the RedirectUrl for the iFrame Integration.
2. Open the RedirectUrl inside an HTML-iFrame, to show the hosted card entry form.
3. Return to Return Url depending on the outcome of the 3D Secure procedure. The ReturnUrls are defined in step 1.
4. Transaction Authorize
   • Authorizes the card, which has been gathered in step 2. Up until now, no transaction has been made!
5. Depending on the outcome of step 4 you may
   • Capture/Finalize the Transaction
   • Cancel/Abort the Transaction
6. Transaction is finished.

In contrast to the payment page, credit card payments can be seamlessly integrated into the merchant's shop with the Transaction Interface. The procedure will be described in the following.

The process begins with Transaction Initialize. With this request, you forward all data necessary for the payment to Saferpay. Such as your customer number (CustomerId), the terminal number (Terminal Id), the currency (CurrencyCode), the amount (Value), the internal reference number of the merchant system (OrderId), and the return addresses (ReturnUrls) to which the customer will return, depending on the outcome of the payment.

• ReturnUrls: For security, Saferpay returns no data to return addresses of the shop. The identification of the payment or the returning customers is up to the merchant. We recommend using your own parameters. These can be attached via HTTP GET to the ReturnUrls. When a ReturnUrl is called, Saferpay returns the appended parameter, thus enabling identification of the customer.

• Payment.OrderId: This optinal parameter is important to keep track of all your transactions in later processes. This ID will be forwarded, so it will show up inside the Saferpay Backoffice (As the Reference number!) and on your reconciliation-files. This will help associate all the transactions for your accounting-department.

• Card Verification Value: The Card Verification Value (CVC) is mandatory, when using the Card Entry Form, except for card brand Maestro, which offers cards with and without CVC.

• Strong Consumer Authentication (SCA): If a certain transaction needs SCA (please refer to the PSD2 chapter), you can force SCA, by setting Authentication.ThreeDsChallenge to "FORCE".

• RedirectNotifyUrls:

  These URLs are meant to notify the merchant server, via a server-to-server callback, should the redirect-processes, like 3D Secure be successful, or a failure. Note, that at this point, no transaction has been made. The redirect (see further below in this chapter) only serves the purpose, to perform 3D Secure and DCC. The transaction itself is made, with the execution of the transaction authorize request (see further below in this chapter). The notification URLs are meant to circumvent cases, where the redirect to one of the ReturnUrls has failed, due to the payer losing connection, or closing the browser preemptively, so the merchant server may continue with the next steps, like the authorization.

The notification happens via http-GET and does not carry any data (like the token), except parameters, that have been added to the URL by the merchant-system. It is intended, that the token (see initialize response) is saved by the merchat system and attached to these parameters, so the merchant system can identify the correct token and perform the authorization this way. Otherwise, the notification callback would be an empty request.

It should be noted that, in a best case scenario, the notification takes place in addition to the respective ReturnUrl, due to its redundant nature. Make sure, that your system can handle both calls, so it doesn't interpret them as two separate processes. Moreover, Saferpay expects the merchant server to answer the call with a HTTP status code 200(OK). If no (e.g. a Timeout after 10 seconds), or a different status code (e.g. http 500) is received, Saferpay will re-attempt the notification up to two times more, for a total of three times, to ensure, that the previous error is not caused by a temporal problem.

• Saferpay Fields: When using the Saferpay Fields, you will be provided with a Saferpay Fields token. This token then has to be submitted through transaction/initialize, within the PaymentMeans.SaferpayFields container in order to trigger a transaction. If used, the RedirectUrl directly links to the next step e.g. 3D Secure, thus skipping the Hosted Card Entry Form. Think of it as a different method to capture the card data for initialization.

  "PaymentMeans": {
    "SaferpayFields": {
      "Token": "[YOUR TOKEN]"
    },

• Secure Card Data: With the Initialize Request, it is also possible within Saferpay Secure Card Data to forward saved cards in the form of an alias. For example, this can be the case if the customers card number has been already saved (tokenized), and you do not want her or him to re-enter this data. To use the alias value instead of the actual card data, use the container PaymentMeans. If used, the RedirectUrl directly links to the next step e.g. 3D Secure, thus skipping the Hosted Card Entry Form.

  "PaymentMeans": {
    "Alias": {
      "Id": "[YOUR ALIAS]"
    },

Do you want to capture the CVC for an already saved card? You can eneble this, by submitting:

  "CardForm": {
    "VerificationCode": "MANDATORY"
  },

With this option set, Saferpay will open up the Hosted Entry Form, while displaying the masked card-number. The card holder can then enter his/her CVC, fully secure and PCI compliant.

• Token: The Token refers to the values temporarily stored regarding the Saferpay transaction and is mandatory during subsequent processing of the transaction (for more information, see e.g. Transaction Authorize). The Token should be coupled to the http-GET parameters that were previously attached to the ReturnUrls for identification and then stored inside a database, for further actions to come!

• RedirectUrl: Unlike with the Payment Page, this URL is not intended to be used for a redirect (Though you may do so, if you want to!). Instead, it is embedded in an HTML Iframe. Within this, a form hosted by Saferpay is displayed. This form is also called the Hosted Entry Form. It can be used to capture sensitive card details in a PCI-compliant manner. You can find out more about the Iframe integration in this chapter.

The RedirectUrl should be opened inside an HTML-iFrame embeded in your webshop or application -a fullsize redirect is technically possible, if desired-, to show the hosted card entry form. Please view the chapter Iframe Integration and CSS for more information on the iframe integration and use of CSS to style the hosted entry form.

3-D Secure and DCC

If 3-D Secure and/or DCC are activated on the terminal for the payment method being used, these services are automatically performed for the transaction as soon as the form has been sent. For this, no additional steps are necessary for the merchant.

Once 3-D Secure and/or DCC are completed, the card holder – depending on the outcome – is taken back to one of the ReturnUrls of the shop. Here, the GET parameters can be read and the Token can be assigned to the transaction. With the Token, the payment can be continued to the next step.

With the Payment Page Interface, the authorization of payment is triggered automatically upon completion of 3-D Secure and/or DCC. In contrast, with Transaction Interface it is triggered separately via Authorize Request.

The Transaction Authorize Request offers further possibilities:

• Condition: With the Condition parameter, it can be specified that a payment will only be authorized when a 3-D Secure liability shift is provided by the cardholders bank.

• RegisterAlias: Via the RegisterAlias container, card details from a payment can be stored safely and in conformity with PCI. See the Secure Card Data chapter for more information.

Transaction Authorize Response data In case of success the authorization data is returned with the Transaction Authorize Response. Based on this data, it can be decided how the transaction is to proceed. The following data is interesting in this regard:

• Transaction > ID: The transaction identifier (Id) returned in the container Transaction, is a unique identifier for a transaction. The value is obligatory for further processing steps (Transaction Capture or Capture) and should therefore be saved.

• ThreeDs: This container provides information about whether or not transaction liability shift via 3-D Secure is available or not. It is up to merchants whether or not they want to accept transactions without liability shift. Evaluation of the parameter provides the opportunity for merchants to incorporate appropriate rules here.

• Transaction > Status: As already described here, this status states whether or not a transaction has to be finalized via Capture. If the status is not CAPTURED, the capture must be run in order to finalize the transaction.

Subsequently, the transaction will be finalised via Capture or aborted via Cancel.For this, the transaction identifier Id is required. Please refer to the notes in the payment methods chapter, to check, if and when a Capture is necessary, and whether a Cancel can still be executed. Once these steps have been executed, the transaction is complete. Alternatively, you can also check the Transaction.Status parameter, within the Authorize Response. If the status is AUTHORIZED a Capture needs to be performed. If the status is CAPTURED you do not need to finalize the payment.

Because there are no PCI requirements for direct debits, bank details data can be captured directly. The use of an in-house HTML form and the subsequent payment request are allowed. For this, the bank details must be forwarded to AuthorizeDirect with the BankAccount parameter in the PaymentMeans container.

Click here for a live demo!

Saferpay also offers the possibility to use a custom HTML-form for merchants with the required PCI certification. The basic transaction-flow stays the same.

The form-inputs need to be set up in a specific way, so Saferpay can parse the submitted parameters. Please make sure, that you name the inputs in the following way:

<html>
  <head>
    <title>Credentials-Form</title>
  </head>
  <body>
    <h1>Credentials Form</h1>
    <form method="POST" action= "<%= RedirectUrl %>">
      Card Holder
      <input type="text" name="HolderName" size="20"><br />
      Card Number
      <input type="text" name="CardNumber" size="16"><br />
      Expiration Date
      <input type="text" name="ExpMonth" size="2">
      <input type="text" name="ExpYear" size="2"><br />
      CVC
      <input type="text" name="VerificationCode" size="4"><br />
      <input type="submit" name="submit" value="purchase">
    </form>
  </body>
</html>

$("#myForm").submit(function (e) {
	// prevent normal (non-ajax) formular submission
	e.preventDefault();
 
	var formData = $(this).serializeArray();
	// add flag to ensure AJAX handling on server
	formData.push({ name: "FromAjax", value: true });
 
	$.post($(this).attr("action"), $.param(formData))
		// data has been posted successfully and user can be redirected
		.done(function(data, textStatus, jqXHR) {
			// NOTE: data is a json response
			window.location.href = data.RedirectUrl;
		})
		// validation failed or server error occured
		.fail(function(jqXHR, textStatus, errorThrown) {
      // NOTE: use $.parseJSON(jqXHR.responseText) in order to try to get a json response
		});
});

Success-Response in case of an http-200 response:

Error-Response in case of an http-4xx response:

After the card holder has gone through the 3D Secure and DCC process, he returns to one of the returnUrls. After that an Authorization can be attempted.