Step 1: Initiate session for consumer identification
The payer will be identified with the consumers
resource and will be
persisted to streamline future Payment Menu processes. Payer identification
is done through the initiate-consumer-session
operation.
Guest Checkout
Note: If the payer is using the Payment Menu as a guest, you can go directly to step 3, which you will find on the next page.
Request
1
2
3
4
5
6
7
8
9
10
11
POST /psp/consumers HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"operation": "initiate-consumer-session",
"language": "sv-SE",
"shippingAddressRestrictedToCountryCodes" : ["NO", "SE", "DK"],
"requireShippingAddress": true
}
Required | Field | Type | Description |
---|---|---|---|
check | operation |
string |
initiate-consumer-session , the operation to perform. |
check | language |
string |
Selected language to be used in Checkin. Supported values are sv-SE , nb-NO or en-US . |
shippingAddressRestrictedToCountryCodes |
string |
List of supported shipping countries for merchant. Using ISO-3166 standard. This is required unless requireShippingAddress is set to false. |
|
requireShippingAddress |
bool |
Defaults to true. If set to false we will not collect a shipping address from the consumer. |
When the request has been sent, a response containing an array of operations that can be acted upon will be returned:
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"token": "7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
"operations": [
{ // Deprecated operation. Do not use!
"method": "GET",
"rel": "redirect-consumer-identification",
"href": "https://ecom.externalintegration.payex.com/consumers/sessions/7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
"contentType": "text/html"
},
{
"method": "GET",
"rel": "view-consumer-identification",
"href": "https://ecom.externalintegration.payex.com/consumers/core/scripts/client/px.consumer.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
"contentType": "application/javascript"
}
]
}
Field | Type | Description |
---|---|---|
token |
string |
A session token used to initiate Checkout UI. |
operations |
array |
The array of operation objects to choose from, described in detail in the table below. |
└➔ rel
|
string |
The relational name of the operation, used as a programmatic identifier to find the correct operation given the current state of the application. |
└➔ method
|
string |
The HTTP method to use when performing the operation. |
└➔ contentType
|
string |
The HTTP content type of the target URI. Indicates what sort of resource is to be found at the URI, how it is expected to be used and behave. |
└➔ href
|
string |
The target URI of the operation. |
Step 2: Display Swedbank Pay Checkin module
The response from the POST
of consumer information contains a few operations.
The combination of rel
, method
and contentType
should give you a clue how
the operation should be performed.
The view-consumer-identification
operation
and its application/javascript
content type gives us a clue that the
operation is meant to be embedded in a <script>
element in an HTML document.
In our example we will focus on using the
view-consumer-identification
solution.
The redirect-consumer-identification
method redirects
the user to Swedbank’s own site to handle the checkin
and is used in other implementations.
redirect-consumer-identification
should only be used in
test enviroments. It is not suitable for the production
environment as there is no simple way of retrieving the
consumerProfileRef
.
HTML
1
2
3
4
5
6
7
8
9
10
11
12
<!DOCTYPE html>
<html>
<head>
<title>Swedbank Pay Checkout is Awesome!</title>
</head>
<body>
<div id="checkin"></div>
<div id="payment-menu"></div>
<!-- Here you can specify your own javascript file -->
<script src="<Your-JavaScript-File-Here>"></script>
</body>
</html>
The Checkin and Payment
Menu components (the two <iframe>
elements) must be separate
(one must not replace the other).
In the HTML, you only need to add two <div>
elements to place the
check-in and payment menu inside of. The JavaScript will handle the rest when
it comes to handling the check-in and payment menu.
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
var request = new XMLHttpRequest();
request.addEventListener('load', function () {
// We will assume that our own backend returns the
// exact same as what SwedbankPay returns.
var response = JSON.parse(this.responseText);
var script = document.createElement('script');
// This assumes that the operations from the response of the POST from the
// payment order is returned verbatim from the server to the Ajax:
var operation = response.operations.find(function (o) {
return o.rel === 'view-consumer-identification';
});
script.setAttribute('src', operation.href);
script.onload = function () {
payex.hostedView.consumer({
// The container specifies which id the script will look for
// to host the checkin component
container: 'checkin',
onConsumerIdentified: function onConsumerIdentified(consumerIdentifiedEvent) {
// consumerIdentifiedEvent.consumerProfileRef contains the reference
// to the identified consumer which we need to pass on to the
// Payment Order to initialize a personalized Payment Menu.
console.log(consumerIdentifiedEvent);
},
onShippingDetailsAvailable: function onShippingDetailsAvailable(shippingDetailsAvailableEvent) {
console.log(shippingDetailsAvailableEvent);
}
}).open();
};
// Appending the script to the head
var head = document.getElementsByTagName('head')[0];
head.appendChild(script);
});
// Place in your own API endpoint here.
request.open('POST', '<Your-Backend-Endpoint-Here>', true);
request.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
// In this example we'll send in all of the information mentioned before,
// in the request to the endpoint.
request.send(JSON.stringify({
operation: 'initiate-consumer-session',
language: 'sv-SE',
shippingAddressRestrictedToCountryCodes: ['NO', 'SE']
}));
Note that we add the script at the end of the body. This ensures that
every element (like the container <div>
elements) has loaded in before we try to
access them with our script.
With the scripts loading in after the entire page is loaded, we can access the
<div>
container that the Checkin will be hosted in.
After that has all loaded, you should see something like this:
As you can see, the payer’s information is pre-filled as provided by the
initial POST
.
From here, there are a three ways forward, depending on the consumer. If he or she is already registered with a profile at Swedbank Pay, the information already provided will be sufficient. The consumer can simply click proceed, and the profile will appear on the page (with sensitive data masked).
If Swedbank Pay detects that the consumer hasn’t registered any personal details, two options are provided: Store details for future purchases or proceed without storing details.
If he or she chooses to store details, the next step is to enter their SSN.
Once a valid SSN has been provided, a page for address details appears. When the consumer has entered their address, the profile box shown above will be displayed.
If the consumer opts out of storing their details, they will be sent directly to the page for address details to enter their shipping address. This info is not stored for future purchases. Please note that this is not the same as shopping as a guest.
With a consumerProfileRef
safely tucked into our pocket,
the Checkin is complete and we can move on to Payment Menu.
A complete overview of how the process of identifying the payer through Checkin is illustrated in the sequence diagram below.
sequenceDiagram
participant Consumer
participant Merchant
participant SwedbankPay as Swedbank Pay
rect rgba(238, 112, 35, 0.05)
note left of Consumer: Checkin
Consumer ->>+ Merchant: Start Checkin
Merchant ->>+ SwedbankPay: POST /psp/consumers
deactivate Merchant
SwedbankPay -->>+ Merchant: rel:view-consumer-identification ①
deactivate SwedbankPay
Merchant -->>- Consumer: Show Checkin on Merchant Page
Consumer ->>+ Consumer: Initiate Consumer Hosted View (open iframe) ②
Consumer ->>+ SwedbankPay: Show Consumer UI page in iframe ③
deactivate Consumer
SwedbankPay ->>- Consumer: Consumer identification process
activate Consumer
Consumer ->>+ SwedbankPay: Consumer identification process
deactivate Consumer
SwedbankPay -->>- Consumer: show consumer completed iframe
activate Consumer
Consumer ->> Consumer: EVENT: onConsumerIdentified (consumerProfileRef) ④
deactivate Consumer
end
If a browser refresh is performed after the payer has checked in, the payment
menu must be shown even though onConsumerIdentified
is not invoked.
Additional events during Checkin can also be implemented in the configuration
object, such as onConsumerIdentified
, onShippingDetailsAvailable
and
onBillingDetailsAvailable
. Read more about these in the Checkin
events section.
Note on consumer data
During this stage, some consumer data is stored. Read more about our Data Protection Policy for details on which information we store and its duration.