Direct Card Payments


The direct payment scenario is used by customers that are compliant with PCI-DSS regulations, and is a way to implement card payments without using PayEx Hosted payment pages.  

The direct integration option requires you to collect the card data on your website, which means it must be PCI-DSS Compliant.
  • The payer places an order and you make a POST request towards PayEx with gathered Purchase information. The action taken next is the direct-authorization operation that is returned in the first request. 
  • You  POSTthe payer's card data to the URL in the direct-authorization operation.
  • If 3D-secure authentication is required, you will then receive a URL where you will have to redirect the payer.
  • When the payment is completed, the payer needs to be redirected back to your merchant/webshop site.
  • Finally you make a GET request towards PayEx with the paymentID received in the first step, which will return the purchase result.

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.


  • 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 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 outcomes 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 purchase payment

  • If the payment shown above is done as a two-phase (Authorization), 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