Card Payment Pages in Mobile Apps

The implementation sequence for this scenario is identical to the standard Redirect scenario, but also includes explanations of how to include this redirect in mobile apps or in mobile web pages.

Introduction

  • When properly set up in your merchant/webshop site and the payer starts the purchase process in your merchant/webshop site, you need to make a POST request towards PayEx with your Purchase information. This will generate a payment object with a unique paymentID. You either receive a redirect URL to a hosted page or a JavaScript source in response. 
  • You need to redirect the payer to the Redirect payment page or embed the script source on you site to create a Hosted View in an iFrame;  so that she can enter credit card details in a secure PayEx hosted environment. 
  • PayEx will handle 3D-secure authentication when this is required. 
  • PayEx will redirect the payer's browser to - or display directly in  the iFrame - one of two specified URLs, depending on whether the payment session is followed through completely or cancelled beforehand. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.
  • When you detect that the payer reach your completeUrl , you need to do a GET request, containing the paymentID generated in the first step, to receive the state of the transaction.

Payment Url

For our hosted view, the URL property called paymentUrl will be used if the consumer is redirected out of the hosted view frame through our Credit Card API. The consumer is redirected out of frame when at the 3d secure verification for credit card payments. The URL should represent the page of where the payment hosted view was hosted originally, such as the checkout page, shopping cart page, or similar. Basically, paymentUrl should be set to the same URL as that of the page where the JavaScript for the hosted payment view was added to in order to initiate the payment. Please note that the paymentUrl must be able to invoke the same JavaScript URL from the same Payment as the one that initiated the payment originally, so it should include some sort of state identifier in the URL. The state identifier is the ID of the order, shopping cart or similar that has the URL of the Payment stored.

With paymentUrl in place, the retry process becomes much more convenient for both the integration and the payer.

Screenshots

You will redirect the consumer/end-user to PayEx hosted pages to collect the credit card information.

1551693930590-433.png

API-requests

The API requests are displayed in the purchase flow. The options you can choose from when creating a payment with key operation set to Value Purchase are listed below. The general REST based API model is described in the technical reference.

Options before posting a payment

All valid options when posting in a payment with operation equal to Purchase, are described in the technical reference.

Type of authorization (Intent).

  • PreAuthorization: If you specify that the intent of the purchase is PreAuthorization, it's almost the same as an authorization, except that no money will be reserved from the consumers credit card, before you finalize the transaction
  • Authorization (two-phase): If you want the credit card to reserve the amount, you will have to specify that the intent of the purchase is Authorization. The amount will be reserved but not charged. You will later (i.e. when you are ready to ship the purchased products) have to make a Capture or Cancel request.

Type of capture (Intent)

  • AutoCapture (one-phase): If you want the credit card to be charged right away, you will have to specify that the intent of the purchase is AutoCapture. The credit card will be charged and you don't need to do any more financial operations to this purchase.

General

  • No 3D Secure and card acceptance: There are optional paramers that can be used in relation to 3d-secure and card acceptance. By default, most credit card agreements with an acquirer will require that you use 3D-Secure for card holder authentication. However, if your agreement allows you to make a card payment without this authentication, or that specific cards can be declined, you may adjust these optional parameters when posting in the payment. This is specified in the technical reference section for creating credit card payments  - you will find the link in the sequence diagram below.
  • Defining CallbackURL: When implementing a scenario, it is optional to set a CallbackURL in the POST request. If callbackURL is set PayEx will send a postback request to this URL when the consumer has fulfilled the payment. See the Callback API description here.

Purchase flow

The sequence diagram below shows a high level description of a complete purchase, and the two requests you have to send to PayEx. The links will take you directly to the corresponding API description.

When dealing with credit card payments, 3D-Secure authentication of the cardholder is an essential topic. There are three alternative outcome of a credit card payment:

  • 3D-Secure enabled - by default, 3D-secure should be enabled, and PayEx will check if the card is enrolled with 3D-secure. This depends on the issuer of the card. If the card is not enrolled with 3D-Secure, no authentication of the cardholder is done.
  • Card supports 3D-Secure - if the card is enrolled with 3D-Secure, PayEx will redirect the cardholder to the autentication mechanism that is decided by the issuing bank. Normally this will be done using BankID or Mobile BankID. 
  • No 3D-Secure - if this is specified in the request (see options above), no authentication is requested.

Detailed Sequence Diagram enabing 3D-secure authentication

Options after posting a payment

  • If the payment shown above is done as a two-phase (Authorize), you will need to implement the Capture and Cancel requests.
  • Abort: It is possible to abort a payment if the payment has no successful transactions.
  • For reversals, you will need to implement the Reversal request.
  • If you did a PreAuthorization, you will have to send a Finalize to the transaction using PATCH on the Authorization.
  • Callback from PayEx: Whenever changes to the payment occur  a Callback request will be posted to the callbackUrl, generated when the payment was created.

Capture Sequence

Capture can only be done on a authorized transaction. It is possible to do a part-capture where you only capture a smaller amount than the authorization amount. You can later do more captures on the sam payment upto the total authorization amount.

Cancel Sequence

Cancel can only be done on a authorized transaction. If you do cancel after doing a part-capture you will cancel the different between the capture amount and the authorization amount.

Reversal Sequence

Reversal can only be done on a payment where there are some captured amount not yet reversed.

Created by Fredrik Köhler on 2018/10/03 14:56