Transaction Interface
Last updated
Last updated
Before you start integrating this any of these flows, make sure, you have read the following Chapters:
Payment Methods for your desired payment method
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.
Alternatively, you can also use the Saferpay Fields, for an even more flexible and integrated solution. The choice is yours.
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.
Please consider our license-chapter, to determine, if all the desired features are available for you.
The JSON API can be used in various ways to cover the most diverse processes. For this reason, only the standard processes are discussed below. For other possible uses, or for questions about the standard procedures, please contact the Saferpay Integration Team.
Payment Initialization: The payer arrives at the checkout and the shop initializes the payment.
Transaction Initialize Initializes the Payment and generates the RedirectUrl for the iFrame Integration.
Capturing of the card details/Redirect: Open the RedirectUrl inside an HTML-iFrame, or a Lightbox. Depending on whether you have provided the card details (Through an Alias or a Saferpay Fields Token), the following may happen:
The Redirecturl opens a card form, to capture the card data.
The form is skipped, so the next step may be executed.
3D Secure and DCC: Saferpay automatically performs3-D Secure and DCC, if activated on the terminal.
Afterwards, the user is redirected back to the shop. This is also the point, where Saferpay calls the NotificationUrl.
Exectuion of the payment. The shop executes the payment itself.
Transaction Authorize Authorizes the cardwhich has been gathered in step 2, using the token from step 1. Up until now, no transaction has been made. Depending on the outcome of the request, the shop displays a failure, or a success to the payer.
Depending on the outcome of step 4 you may
Capture: You want to accept the transaction and transfer the money. For that, you have to execute the Transaction Capture request. Only if the Capture has been successful, the money will be transferred.
Cancel: You do not want to acceppt the transaction (E.g. due to a lack of LiabilityShift.). For that, you have to execute the Transaction Cancel request. The Cancel will release the money again, so the payer may have access to it again.
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.
The following parameters are either mandatory and/or have special significance within the Saferpay gateway.
Via the ReturnUrl, the customer is returned to the shop after the transaction. For security reasons, Saferpay returns no data to return addresses. 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 ReturnUrl. When a ReturnUrl is called, Saferpay returns the appended parameter, thus enabling identification of the customer/transaction. The ReturnUrl is ALWAYS called through the clients Browser.
We strongly advice against using a session cookie for identifying the customer upon redirect to this URL!
Sessions can be lost during the redirect process, especially, if Saferpay has to redirect to external sites (e.g. PayPal, Sofort etc.).
Also certain browsers -specifically known is Safari- can prove a problem here, due to them discarding 3rd party cookies, especially inside iFrames. Browser behavior can also change with an update, introducing problems, without you being prepared.
Saferpay advices you to use GET-parameters, attached to the ReturnUrl, in order to identify the returning customer!
If you intent on using Dynamic Currency Conversion (DCC), it is highly recommended to set the Abort Url, even though optional!
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.
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.
If a certain transaction needs SCA (please refer to the PSD2 chapter), you can force SCA, by setting Authentication.ThreeDsChallenge to "FORCE".
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 circumvent cases, where the redirect to the ReturnUrl 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 then linked to these parameters -e.g. a sessionId-, 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 five times more, for a total of six times, to ensure, that the previous error is not caused by a temporal problem.
The timespan between each try is increased, after each failure, to a maximum of 1 day. That ensures, that also a longer lasting issue can be circumvented.
The usage of the Notification URLs is strongly recommended! Only leave it out, if your system cannot recieve external requests!
The notification also does not return any data to the merchants application, except your own parameters (See ReturnUrls above!) via GET!
Any type of authentication (e.g. basic authentication, or certificates) towards your system, is currently not supported!
If you need the outgoing IP-addresses and/or ports, you can find them here.
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.
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.
Do you want to capture the CVC for an already saved card? You can eneble this, by submitting:
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.
Some data-points may be submitted towards the Saferpay gateway, either for 3D Secure compliance, or to speed up the process for the payer and reduce friction during checkout (e.g. by preventing a 3D Secure Challenge.).
Please make sure, that you have read the 3-D Secure chapter on this matter.
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!
Unlike with the Payment Page, this URL is not intended to be used for a full-size 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.
In cases, where a redirect is not necessary, the parameter RedirectRequired will be false and no RedirectUrl will be provided. In this case, you can go ahead and proceed with Step #4 - Transaction Authorize.
If an alias, or Hosted Fields token is forwarded in the initalize request (See the step above!), the display of the form will be skipped. Furthermore, the parameter Redirect.PaymentmeansRequired will be false, indicating, that the necessary means of payment already have been provided.
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.
Saferpay does not recommend the usage of a Client-Side Session (Cookie), for customer identification, due to restrains emposed by browser manufacturers! Those can cause the Session getting lost, during the payment process, thus causing the shop to not being able to identify the returning user. We recommend using GET-parameters, as described above (See parameter-description for Initialize)!
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/the RedirectUrl has been opened. For this, no additional steps are necessary for the merchant.
If you want to minimize the number of 3DS redirects and thusly the friction with your customers, we recommend sending additional-data with the Transaction Initialize.
Once 3-D Secure and/or DCC are completed, the card holder is taken back to the ReturnUrl.Url 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, where the payment, or authorization itself will be performed.
Under certain circumstances, it may happen, that the redirect to the shop happens more, than once. This can be due to the payer trying to go back, by clicking on the back-button in their browser, or accessing their history etc.
These events cannot be handled by Saferpay, as the user sometimes has already left our sites and can have serious impact on your shop, if you do not handle them correctly.
For instance, it could trigger the transaction processing twice, which could lead to errors -see Notification below for instance-. These errors could then lead to the shop assuming, that the transaction has failed, even though it did not.
Once you have received a definite response from the Transaction Authorize you must mark the transaction as "Processed" on your end, so that the shop does not process the transaction twice.
This is also the point, when Saferpay calls the NotificationUrls.
Handling the notification correctly is very important, though it does present some challenges.
Ideally, both -the notification and the redirect- happen roughly at the same time, though note, that they are asynchronous, meaning, that one can happen before, or after the other, depending on the connection. So relying on them being called in a specific order is not recommended.
There are multiple ways of tackling this, though we highly recommend to not use one over the other. They are both intended to work in tandem to and suppliment each other. In any case, both should be able to trigger the next processing steps.
The following things may be done to handle this correctly:
Let both trigger the next steps. With the Transaction Interface, the Transaction Authorize triggers the actual transaction, though it may only happen once. So if a second call attempts to authorize this specific transaction, the API will throw the following error:
Write both calls into a queue on your end, so you can process them after each other, instead of in parallel. This way, you can make sure, that the process only runs once on your end. Make sure, that you mark your process as completed at the end, so that if the second call comes up in the queue, the system sees, that this transaction has already been processed successfully and then skips this item.
It is important, that you do not handle both calls as separate transactions. Both calls are part of the same transaction and, in the best case, happen both, as both calls were able to reach your system.
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 the Authorize Request.
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.
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.
A card will be registered only after a successful authorization.
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.
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.
Accepting transaction without LiabilityShift happens at the merchants own risk.
As already described here, this status states whether or not a transaction has to be finalized via Capture. If the status is AUTHORIZED, the capture must be run in order to finalize the transaction.
You can also call Transaction Authorize, if the Fail-or AbortUrl has been called. It will then return a JSON-Object, containing information about the failed transaction, like the reason (If available!) and error-code from the processor itself! Note, that the http-status will be != 200, indicating a failed transaction!
If the payment has been rejected, the Transaction Authorize request will throw an http status != 200 and a JSON error-message, containing more information about the rejection.
More information about errors and error-handling can be found over here.
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.
Keep in mind that you cannot cancel a transaction, once it is captured! At that point, a refund has to be executed, if available -please check the respective payment methods chapter-! So please make sure, that you really want to finalize the transaction and initiate the money transfer, to avoid confusion with your customers!
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.
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, just the way, how the card data is captured, changes.
As mentioned before: DO NOT PROCEED, if you do not have the necessary PCI certification (SAQ-A EP) in order to use your own form! Worldline will not take any kind of responsibility in case of a noncompliance! We highly urge you, to use the Saferpay Hosted Fields instead!
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:
This example will automatically send the Form data, recieve the 3D Secure/DCC rediretUrl and redirect your customer to the respective page.
You do not need to re-initialize the API, if you get an error-response (Like invalid card details etc.). You can re-use and perform multiple AJAX-Posts towards one RedirectUrl multiple times.
This saves on requests and also avoids unwanted behavior.
Parameter
Type
Usage
Description
RedirectUrl
URL
M
The redirectUrl you get through Transaction Initialize or Alias Insert. It has to be set as the form action. The form-method will be POST!
HolderName
String
M
Input for the card-holder name.
CardNumber
String
M
Input for the card-number (PAN).
ExpMonth
String
M
Input for the expiration-month.
ExpYear
String
M
Input for the expiration-year.
VerificationCode
String
M
Input for the Card Verification Code (CVC).
FromAjax
Boolean
O
Set to true, if the form-submission shall be done via AJAX. When used, Saferpay returns validation-messages through a JSON-response, which can be catched with JavaScript!
Parameter
Type
Usage
Description
RedirectUrl
URL
mandatory
RedirectUrl to which to redirect your customer to!
Parameter
Type
Usage
Description
ErrorName
String
mandatory
Description, or ID of the error
Behavior
String
mandatory
Further details on how to proceed (RETRY_LATER, RETRY, ABORT...).
ErrorDetail
String
optional
Further details on the error itself, if available. For example, if the ErrorName=VALIDATION_FAILED, the ErrorDetail contains a list of the invalid input-fields (“CardNumber”, “ExpYear”, “Ex-pMonth”, etc.)
