Card Payment Pages

The basic redirect purchase scenario is the most common way to implement card payments.

Introduction

  • When properly set up in your merchant/webshop site and the payer starts the purchase process, 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's browser to that specified URL, or embed the script source on your site to create a Hosted View in an iFrame; so that she can enter the 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 to receive the state of the transaction, 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 payer to PayEx hosted pages to collect the credit card information.

1551693452568-441.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 se, are described in the technical reference.

Type of authorization - Intent

  • PreAuthorization: A purchase with PreAuthorization intent is handled in a similar manner as the ordinary authorization procedure. The notable difference is that the funds are put on hold for 30 days (for an ordinary authorization the funds are reserved for 7 days). Also, with a PreAuthorization, the captured amount can be higher than the preauthorized amount. The amount captured should not be higher than 20% of the original amount, due to card brand rules. You complete the purchase by finalizing 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.

Co-brand Visa/Dankort

Not yet supported

Purchase flow

The sequence diagram below shows a high level description of a complete purchase, and the 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.

Options after posting a payment

  • Abort: It is possible to abort the process, if the payment has no successful transactions. See the PATCH payment description.
  • If the payment shown above is done as a two phase (Authorization), you will need to implement the Capture and Cancel requests.
  • For reversals, you will need to implement the Reversal request.
  • If you did a PreAuthorization, you will have to send a Finalize request to finalize the transaction.
  • If CallbackURL is set: Whenever changes to the payment occur a Callback request will be posted to the callbackUrl, which was 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 part of the authorization amount. You can later do more captures on the same payment up to 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.

Technical reference

You find the full technical reference here.

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