Mobile Integration

Payments done via a smartphone through a mobile app are becoming more and more important. Saferpay offers the tools needed to be integrated by a mobile app. The following guide is an extension to the standard integration methods for the transaction interface and Secure Alias Store.

Credit Card Process

General process:

alt text

1. The app sends a message to your backend server to make a payment.

2. The server calls Saferpay, doing either a Transaction Initialize, or Alias Insert.

3. Saferpay responds with a token and the RedirectUrl.

4. The server saves the token and forwards the RedirectUrl to the app.

5. The app opens up a native card form.

6. The card holder enters his card details and submits the form.

7. The card details are posted to Saferpay directly, using the RedirectUrl as the endpoint.

8. Saferpay responds with a new RedirectUrl for 3D Secure and DCC, if applicable.

9. The app either opens the Url inside a WebView, or by using the phone's browser.

10. The user may authenticate him-/herself through 3DS and perform DCC.

11. Once the external process is completed, the card holder gets redirected to the ReturnUrl.Url

12. The app intercepts the redirect through a WebView-handler

13. The app opens up the in-app return page instead, while asking the server for the final outcome.

14. The server executes the Authorization and forwards the result to the app.

15. The app confirms the receipt of the result, so the server may finalize and capture the payment, while the app either displays a success, or a failure message to the customer.

Do not implement calls to Saferpay directly in your app! While technically possible, this would mean that you'd store the authentication credentials (user name and password, or certificate) in the app itself. Those credentials can be extracted and then used for mailicious actions on your account. ALWAYS implement the server-client model described above.

Note, that this example assumes a native in-app card form.

This is allowed under PCI, as the form is hosted on the card holders device and the data is sent to Saferpay.

Hosting a native form on your own server and displaying said form in a web-view, or browser and/or posting the card-data anywhere else, but Saferpay directly -e.g. first to your server and then to Saferpay-, falls under PCI and needs special certification.

Request and response of a Card-Post

Request

The following parameters need to be posted from the app to the RedirectUrl (See step 7 above):

Parameter	Type	Usage	Description
RedirectUrl	URL	mandatory	Endpoint where the card details are posted to
HolderName	String	mandatory	Card holder name
CardNumber	String	mandatory	Card number (PAN)
ExpMonth	String	mandatory	Expiration month
ExpYear	String	mandatory	Expiration year
VerificationCode	String	mandatory	Card Verification Code (CVC)
FromAjax	Boolean	optional	Must be set to "true" in order to receive a JSON response

Response

The response will be a JSON object.

Success response in case of an http-200 response:

Parameter	Type	Usage	Description
RedirectUrl	URL	mandatory	Url to open up inside a WebView

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

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, if available. For example, if the ErrorName=VALIDATION_FAILED, the ErrorDetail contains a list of the invalid input-fields (“CardNumber”, “ExpYear”, “ExpMonth”, etc.)

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 POST-requests towards one RedirectUrl multiple times.

This saves on requests and also avoids unwanted behavior, especially in cases, where the connection is lost during re-initialization.

3rd Party Payment Methods

All 3rd party payment methods are exclusively provided via the Payment Page, since they mostly require web-based redirects to be processed.

3rd party payment methods process:

alt text

1. The app sends a message to your backend server to make a payment.

2. The server calls Saferpay, doing a Payment Page Initialize request.

3. Saferpay responds with a token and the RedirectUrl.

4. The server saves the token and forwards the RedirectUrl to the app.

5. The app opens the URL in a Web-View.

6. The customer performs the payment.

7. Afterwards, Saferpay will redirect the customer back to one of the corresponding Return URLs (see #11), while also notifying the server.

8. The server executes the Payment Page Assert request to gather the payment data.

9. Saferpay responds with the payment data, which then gets saved on the server.

10. The server forwards the result and any additional data to the app.

11. It is also possible to intercept the redirect, so the app may perform a web-to-app switch.

12. The app displays a success or failure message to the customer, while the server finalizes (Capture etc.) the payment.

At this moment, Apple Pay does not support the Web-View integration. Only the Safari browser itself is supported.

Google Pay also does not support the Web-View integration.

An exception from this process is Bancontact, which offers an alternative payment process.