Card widget

The card payment widget can be used in either a redirect flow, or embedded in your page.

Widget options

After initiating a card payment Payer will request card information from the customer and handle a potential 3d-secure verification. This is done using the fetched url from direct card payment or recurring card payment. Choose from the following options:

a. Using Redirect (hosted payment window)

Redirect the customer to the url.

b. Using Embedded (iframe)

Load the url in your iframe. For further instructions, see below.

The customer will then provide card data information and may be redirected to 3d-secure for verification.

Then after card input and potential 3d-secure, the customer is redirected to either your redirectOnSuccessURL or redirectOnFailURL depending on the result. If the customer is redirected to redirectOnSuccessURL it is possible to begin capture funds.

Embedded/iframe widget - using an iframe directly

You can embed an <iframe>element on a page, and point its src to the url from the response you got when creating the card payment link.

The card payment widget in the iframe communicates with the parent page through Window.postMessage(). You can then react to the messages sent by the widget in order to trigger events on your side, such as redirecting the user to a success or failure page.

The widget sends three types of messages, the type being indicated by a field in the message object.

The possible types are 'PAYMENT_SUCCEEDED', 'PAYMENT_PENDING_VERIFICATION', 'PAYMENT_CANCELED'

'PAYMENT_SUCCEEDED' is sent when the payment is successful, and contains the redirectOnSuccessURL in the message:

{

  "type": "PAYMENT_SUCCEEDED",

  "message": {

    "redirectUrl": "https://stage-b2b.payer.se/demo/confirmation"

  }

}

'PAYMENT_CANCELED' is sent when the end user clicks the 'Cancel' button. It contains a type and a messagefield. The content of the message field will vary depending on whether the user cancelled without attempting to pay, or cancelled after failing to pay.

When the user cancels without attempting to pay, the value of the message is the backToShopURL set in the payment creation request.

When the user cancels after a failure, the value of the message is the redirectOnFailUrl set in the payment creation request, and an error code denoting the specific error is appended to the url as a query parameter.

// This example shows what the message will look like when the user cancels without attempting to pay

{ 

  "type": "PAYMENT_CANCELED",

  "message": "https://stage-b2b.payer.se/demo" // message value will be backToShopURL

}

// This example shows what the message will look like when the user cancels after failing to pay

{ 

  "type": "PAYMENT_CANCELED",

  "message": "https://stage-b2b.payer.se/fail?errorCode=DECLINED" // message value will be redirectOnFailUrl with an additional errorCode query parameter denoting the specific error that occured.

}

'PAYMENT_PENDING_VERIFICATION' is only sent in those cases where the card provider does not allow the 3D-secure flow to happen inside the widget itself. In these cases, the message will contain an object with information about how the 3D-secure authentication is supposed to be presented:

{

  "type": "PAYMENT_PENDING_VERIFICATION",

  "message": {

    "html": null, // if not null, then url will be null, and this field will contain html to be rendered for the user (rare scenario)

    "url": "https://test3ds.url", // the url to redirect to or present in separate tab/window

    "method": "GET", // either 'GET' or 'POST', if 'GET' then the URL can just be accessed in another tab or window, if 'POST', see below

    "container": "window", // one of "window", "redirect" or "iframe". The type of container where 3DS authentication should occur. This is what we use to determine if the 3DS flow can be displayed in the widget or not

    "parameters": {}, // key-value pairs to be included when the method is 'POST'

    "height": 400, // optimal height for the 3DS-page

    "width": 600, // optimal width for the 3DS-page

    "sizeUnit": "px" // the unit used for the height and width

  }

}

If the method is 'POST', you need to make a POST-request to the URL with the values in the 'parameters'-field as form data, and a content type header of 'multipart/form-data' or 'application/x-www-form-urlencoded' (depending on how the form data is formatted).

Embedded/iframe widget - using the widget SDK

Instead of creating the iframe yourself, and coding logic that reacts to the messages it posts, it is possible to use an SDK we provide that handles some of these aspects.

The widget SDK takes care of the following:

1. Creating the iframe, and setting its src to a URL decoded from a passed client token
2. Handling 3DS messages internally, opening a new window/tab for the 3DS verification if necessary
3. Converting success and cancel messages the iframe posts, and routing them to callbacks passed to the SDK when it's initialized
4. Hiding the iframe if the user cancels the payment

In order to use the widget SDK, a <script> tag is embedded in your page, and pointed towards the URL where we serve the widget SDK for the environment you are using, for instance: