When properly set up in your merchant/webshop site and the payer starts the
purchase process, you need to make a POST request towards Swedbank Pay with
your Purchase information. This will generate a payment object with a unique
paymentID
. You will receive a redirect URL to a Swedbank Pay payment
page.
Step 1: Create A Purchase
A Purchase
payment is a straightforward way to charge the card of the payer.
It is followed up by posting a capture, cancellation or reversal transaction.
An example of an abbreviated POST
request is provided below. Each individual
field of the JSON document is described in the following section. An example of
an expanded POST
request is available in the other features
section.
Callback URL: It is mandatory to set a callbackUrl
in the POST
request creating the payment. When callbackUrl
is set, Swedbank Pay will send
a POST
request to this URL when the payer has fulfilled the payment. Upon
receiving this POST
request, a subsequent GET
request towards the id
of
the payment generated initially must be made to receive the state of the
transaction.
To minimize the risk for
a challenge request (Strong Customer Authentication – “SCA”) on card payments,
it’s recommended that you add as much data as possible to the riskIndicator
object in the request below.
GDPR: GDPR
sensitive data such as email, phone numbers and social security numbers must
not be used directly in request fields such as payerReference
. If it is
necessary to use GDPR sensitive data, it must be hashed and then the hash can be
used in requests towards Swedbank Pay.
Purchase
A Purchase
payment is a straightforward way to charge the card of the payer.
It is followed up by posting a capture
, cancellation
or reversal
transaction. An example of a request is provided below. Each individual field of
the JSON document is described in the following section.
Purchase Operation
Posting a payment (operation Purchase
) returns the options of aborting the
payment altogether or creating an authorization transaction through the
redirect-authorization
hyperlink.
Request
1
2
3
4
5
{
"payment": {
"operation": "Purchase"
}
}
Card Payment Request
Request
1
2
3
POST /psp/creditcard/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
"payment": {
"operation": "Purchase",
"intent": "Authorization",
"currency": "SEK",
"prices": [{
"type": "CreditCard",
"amount": 1500,
"vatAmount": 0
}
],
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"urls": {
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-cancelled",
"callbackUrl": "https://example.com/payment-callback",
"logoUrl": "https://example.com/payment-logo.png",
"termsOfServiceUrl": "https://example.com/payment-terms.pdf",
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "CD1234",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or123",
"subsite": "mySubsite"
},
"payer": {
"payerReference": "AB1234",
},
"cardholder": {
"firstName": "Olivia",
"lastName": "Nyhuus",
"email": "olivia.nyhuus@payex.com",
"msisdn": "+4798765432",
"homePhoneNumber": "+4787654321",
"workPhoneNumber": "+4776543210",
"shippingAddress": {
"firstName": "Olivia",
"lastName": "Nyhuus",
"email": "olivia.nyhuus@payex.com",
"msisdn": "+4798765432",
"streetAddress": "Saltnestoppen 43",
"coAddress": "",
"city": "Saltnes",
"zipCode": "1642",
"countryCode": "NO"
},
},
"riskIndicator": {
"deliveryEmailAddress": "olivia.nyhuus@payex.com",
"deliveryTimeFrameIndicator": "01",
"preOrderDate": "19801231",
"preOrderPurchaseIndicator": "01",
"shipIndicator": "01",
"giftCardPurchase": false,
"reOrderPurchaseIndicator": "01",
"pickUpAddress": {
"name": "Olivia Nyhuus",
"streetAddress": "Saltnestoppen 43",
"coAddress": "",
"city": "Saltnes",
"zipCode": "1642",
"countryCode": "NO"
}
}
}
}
Required | Field | Type | Description |
---|---|---|---|
check | payment |
object |
The payment object |
check | operation |
string |
Determines the initial operation, defining the type of payment order created. |
check | intent |
string |
Authorization . Reserves the amount, and is followed by a Cancel or Capture of funds.AutoCapture . A one phase option that enables the Capture of funds automatically after authorization. |
paymentToken |
string |
If a paymentToken is included in the request, the card details stored in the paymentToken will be prefilled on the payment page. The payer still has to enter the cvc to complete the purchase. This is called a “One Click” purchase. |
|
check | currency |
string |
NOK, SEK, DKK, USD or EUR. |
check | prices |
array |
The prices resource lists the prices related to a specific payment. |
check | type |
string |
Use the value ``.See the prices resource for more information. |
check | amount |
integer |
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. |
check | vatAmount |
integer |
The payment’s VAT (Value Added Tax) amount , entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount . This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged. |
check | description |
string(40) |
A 40 character length textual description of the purchase. |
generatePaymentToken |
boolean |
true or false . Set this to true if you want to create a paymentToken for future use as One Click. |
|
generateRecurrenceToken |
boolean |
true or false . Set this to true if you want to create a recurrenceToken for future use Recurring purchases (subscription payments). |
|
check | userAgent |
string |
The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser. |
check | language |
string |
sv-SE , nb-NO , da-DK , de-DE , ee-EE , en-US , es-ES , fr-FR , lv-LV , lt-LT , ru-RU or fi-FI . |
check︎ | urls |
object |
The object containing URLs relevant for the payment . |
check | completeUrl |
string |
The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET request needs to be performed on the payment to inspect it further. See completeUrl for details. |
check | cancelUrl |
string |
The URL to redirect the payer to if the payment is cancelled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl ; only cancelUrl or paymentUrl can be used, not both. |
paymentUrl |
string |
The paymentUrl represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the <iframe> ) and sent back after completing the payment. paymentUrl is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both cancelUrl and paymentUrl is sent, the paymentUrl will used. |
|
callbackUrl |
string |
The URL that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment. See callback for details. |
|
logoUrl |
string |
The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS. | |
termsOfServiceUrl |
string |
The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement. | |
check | payeeInfo |
object |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
check | payeeId |
string |
This is the unique id that identifies this payee (like merchant) set by Swedbank Pay. |
check | payeeReference |
string |
A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(50) . If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12) . All characters must be digits. |
payeeName |
string |
The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay. | |
productCategory |
string(50) |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. | |
orderReference |
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. | |
subsite |
string(40) |
The subsite field can be used to perform a split settlement on the payment. The different subsite values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown subsite value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of A-Za-z0-9 . |
|
payer |
string |
The payer object, containing information about the payer. |
|
payerReference |
string |
The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if generateRecurrenceToken , RecurrenceToken , generatePaymentToken or paymentToken is true . |
|
metadata |
object |
A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(50) . If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12) . All characters must be digits. |
|
cardholder |
object |
Optional. Cardholder object that can hold information about a buyer (private or company). The information added increases the chance for frictionless flow and is related to 3-D Secure 2.0.. | |
firstName |
string |
Optional (increased chance for frictionless flow if set). If buyer is a company, use only firstName . |
|
lastName |
string |
Optional (increased chance for frictionless flow if set). If buyer is a company, use only firstName . |
|
email |
string |
Optional (increased chance for frictionless flow if set) | |
msisdn |
string |
Optional (increased chance for frictionless flow if set) | |
homePhoneNumber |
string |
Optional (increased chance for frictionless flow if set) | |
workPhoneNumber |
string |
Optional (increased chance for frictionless flow if set) | |
shippingAddress |
object |
Optional (increased chance for frictionless flow if set) | |
firstName |
string |
Optional (increased chance for frictionless flow if set) | |
lastName |
string |
Optional (increased chance for frictionless flow if set) | |
email |
string |
Optional (increased chance for frictionless flow if set) | |
msisdn |
string |
Optional (increased chance for frictionless flow if set) | |
streetAddress |
string |
Optional (increased chance for frictionless flow if set) | |
coAddress |
string |
Optional (increased chance for frictionless flow if set) | |
city |
string |
Optional (increased chance for frictionless flow if set) | |
zipCode |
string |
Optional (increased chance for frictionless flow if set) | |
countryCode |
string |
Optional (increased chance for frictionless flow if set) | |
billingAddress |
object |
Optional (increased chance for frictionless flow if set) | |
firstName |
string |
Optional (increased chance for frictionless flow if set). If buyer is a company, use only firstName . |
|
lastName |
string |
Optional (increased chance for frictionless flow if set). If buyer is a company, use only firstName . |
|
email |
string |
Optional (increased chance for frictionless flow if set) | |
msisdn |
string |
Optional (increased chance for frictionless flow if set) | |
streetAddress |
string |
Optional (increased chance for frictionless flow if set) | |
coAddress |
string |
Optional (increased chance for frictionless flow if set) | |
city |
string |
Optional (increased chance for frictionless flow if set) | |
zipCode |
string |
Optional (increased chance for frictionless flow if set) | |
countryCode |
string |
Optional (increased chance for frictionless flow if set) | |
riskIndicator |
array |
This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelihood of having to prompt for 3-D Secure 2.0 authentication of the payer when they are authenticating the purchase. | |
deliveryEmailAdress |
string |
For electronic delivery, the email address to which the merchandise was delivered. Providing this field when appropriate decreases the likelihood of a 3-D Secure authentication for the payer. | |
deliveryTimeFrameIndicator |
string |
Indicates the merchandise delivery timeframe. 01 (Electronic Delivery) 02 (Same day shipping) 03 (Overnight shipping) 04 (Two-day or more shipping) |
|
preOrderDate |
string |
For a pre-ordered purchase. The expected date that the merchandise will be available. Format: YYYYMMDD
|
|
preOrderPurchaseIndicator |
string |
Indicates whether the payer is placing an order for merchandise with a future availability or release date. 01 (Merchandise available) 02 (Future availability) |
|
shipIndicator |
string |
Indicates shipping method chosen for the transaction. 01 (Ship to cardholder’s billing address) 02 (Ship to another verified address on file with merchant)03 (Ship to address that is different than cardholder’s billing address)04 (Ship to Store / Pick-up at local store. Store address shall be populated in shipping address fields)05 (Digital goods, includes online services, electronic giftcards and redemption codes) 06 (Travel and Event tickets, not shipped) 07 (Other, e.g. gaming, digital service) |
|
giftCardPurchase |
bool |
true if this is a purchase of a gift card. |
|
reOrderPurchaseIndicator |
string |
Indicates whether the cardholder is reordering previously purchased merchandise. 01 (First time ordered) 02 (Reordered). |
|
pickUpAddress |
object |
If shipIndicator set to 04 , then prefill this with the payers pickUpAddress of the purchase to decrease the risk factor of the purchase. |
|
name |
string |
If shipIndicator set to 04 , then prefill this with the payers name of the purchase to decrease the risk factor of the purchase. |
|
streetAddress |
string |
If shipIndicator set to 04 , then prefill this with the payers streetAddress of the purchase to decrease the risk factor of the purchase. Maximum 50 characters long. |
|
coAddress |
string |
If shipIndicator set to 04 , then prefill this with the payers coAddress of the purchase to decrease the risk factor of the purchase. |
|
city |
string |
If shipIndicator set to 04 , then prefill this with the payers city of the purchase to decrease the risk factor of the purchase. |
|
zipCode |
string |
If shipIndicator set to 04 , then prefill this with the payers zipCode of the purchase to decrease the risk factor of the purchase. |
|
countryCode |
string |
If shipIndicator set to 04 , then prefill this with the payers countryCode of the purchase to decrease the risk factor of the purchase. |
Card Payment Response
Response
1
2
HTTP/1.1 200 OK
Content-Type: application/json
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
"payment": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"number": 1234567890,
"instrument": "CreditCard",
"created": "2016-09-14T13:21:29.3182115Z",
"updated": "2016-09-14T13:21:57.6627579Z",
"state": "Ready",
"operation": "Purchase",
"intent": "Authorization",
"currency": "SEK",
"amount": 0,
"remainingCaptureAmount": 1500,
"remainingCancellationAmount": 1500,
"remainingReversalAmount": 0,
"description": "Test Purchase",
"initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"prices": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
"transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
"authorizations": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations" },
"captures": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures" },
"reversals": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
"cancellations": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" },
"urls": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
"payeeInfo": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
"payers": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
"settings": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
},
"operations": [
{
"rel": "update-payment-abort",
"href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"method": "PATCH",
"contentType": "application/json"
},
{
"rel": "redirect-authorization",
"href": "https://ecom.externalintegration.payex.com/creditcard/payments/authorize/5a17c24e-d459-4567-bbad-aa0f17a76119",
"method": "GET",
"contentType": "text/html"
},
{
"rel": "view-authorization",
"href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
"method": "GET",
"contentType": "application/javascript"
},
{
"rel": "view-payment",
"href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
"method": "GET",
"contentType": "application/javascript"
},
{
"rel": "direct-authorization",
"href": "https://api.externalintegration.payex.com/psp/creditcard/confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations",
"method": "POST",
"contentType": "application/json"
}
]
}
Field | Type | Description |
---|---|---|
payment |
object |
The payment object contains information about the specific payment. |
id |
string |
The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
number |
integer |
The payment number , useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, where id should be used instead. |
created |
string |
The ISO-8601 date of when the payment was created. |
updated |
string |
The ISO-8601 date of when the payment was updated. |
state |
string |
Ready , Pending , Failed or Aborted . Indicates the state of the payment, not the state of any transactions performed on the payment. To find the state of the payment’s transactions (such as a successful authorization), see the transactions resource or the different specialized type-specific resources such as authorizations or sales . |
prices |
object |
The prices resource lists the prices related to a specific payment. |
id |
string |
The relative URL and unique identifier of the prices resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
amount |
integer |
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. |
remainingCaptureAmount |
integer |
The available amount to capture. |
remainingCancelAmount |
integer |
The available amount to cancel. |
remainingReversalAmount |
integer |
The available amount to reverse. |
description |
string(40) |
A 40 character length textual description of the purchase. |
userAgent |
string |
The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser. |
language |
string |
sv-SE , nb-NO , da-DK , de-DE , ee-EE , en-US , es-ES , fr-FR , lv-LV , lt-LT , ru-RU or fi-FI . |
urls |
string |
The URL to the urls resource where all URLs related to the payment can be retrieved. |
payeeInfo |
object |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
payers |
string |
The URL to the payer resource where the information about the payer can be retrieved. |
operations |
array |
The array of operations that are possible to perform on the payment in its current state. |
method |
string |
The HTTP method to use when performing the operation. |
href |
string |
The target URL to perform the operation against. |
rel |
string |
The name of the relation the operation has to the current resource. |
When you receive the redirect url from Swedbank Pay, you redirect the payer there to complete the payment. This ensures that card details and other personal information is entered in a secure environment. Swedbank Pay handles all authentication during this phase.
After an attempted payment, Swedbank Pay will redirect the Payer to one of two
specified URLs: completeUrl
or cancelUrl
.
If the payer cancels at any point, the payer will be redirected to the
cancelUrl
. If the payment is followed through completely the payer will
reach the completeUrl
.
Important: Both
successful and rejected payments are labeled as completed
.
This means that when you reach this point, you need to make sure that the
payment has gone through before you let the payer know that the payment was
successful. You do this by doing a GET
request. This request has to include
the payment Id generated from the initial POST
request, so that you can
receive the state of the transaction.
If you have chosen Seamless View, the completeUrl
and cancelUrl
will display
directly inside the iframe.
How It Looks
Transactions in the currency SEK might look like this, with a debit/credit selection available:
Sequence Diagram
sequenceDiagram
participant Payer
participant Merchant
participant SwedbankPay as Swedbank Pay
activate Payer
Payer->>-Merchant: start purchase
activate Merchant
Merchant->>-SwedbankPay: POST /psp/creditcard/payments
activate SwedbankPay
note left of Payer: First API request
SwedbankPay-->>-Merchant: rel: redirect-authorization ①
activate Merchant
Merchant-->>-Payer: Redirect to authorization page
activate Payer
Payer->>-SwedbankPay: Access authorization page
activate SwedbankPay
note left of Payer: redirect to SwedbankPay ②
SwedbankPay-->>-Payer: Display purchase information
activate Payer
Payer->>Payer: Input creditcard information ③
Payer->>-SwedbankPay: Submit creditcard information
opt If 3-D Secure required
note left of Payer: Authentication Challenge ④
SwedbankPay-->>Payer: Redirect to IssuingBank
activate Payer
Payer->>-IssuingBank: 3-D Secure authentication process
activate IssuingBank
IssuingBank-->>-Payer: 3-D Secure authentication process response
activate Payer
Payer->>-SwedbankPay: Access authentication page
activate SwedbankPay
end
SwedbankPay-->>-Payer: Redirect to CompleteUrl ⑤
activate Payer
Payer->>-Merchant: Access CompleteUrl
alt Callback is set
activate SwedbankPay
SwedbankPay->>SwedbankPay: Payment is updated
SwedbankPay->>-Merchant: POST Payment Callback
end
activate Merchant
Merchant->>-SwedbankPay: GET <payment.id> ⑥
activate SwedbankPay
note left of Payer: Second API request
SwedbankPay-->>-Merchant: Payment result
activate Merchant
Merchant-->>-Payer: Display purchase result
Explanations
- ①
rel: redirect-authorization
is the name of one of the operations, sent as a response from Swedbank Pay to the Merchant. Thehref
in this operation is the redirect URL to a Swedbank Pay payment page. - ② The payer is redirected to a secure Swedbank Pay hosted page
- ③ The payment window is presented and the payer can enter card information for authorization.
- ④ If needed, the payer must go through an authorization challenge to verify his or hers identity.
- ⑤ The Payer reaches the CompleteUrl which you defined in the initial POST request. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.
- ⑥ Send a GET request with the
paymentId
to check the state of the transaction. Click the link for a complete list of payment and transaction states.
3-D Secure
No 3-D Secure and card acceptance: There are optional parameters which can be used in relation to 3-D Secure and card acceptance. Most acquiring agreements will demand that you use 3-D 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.
Swedbank Pay will handle 3-D Secure authentication when this is required. When dealing with card payments, 3-D Secure authentication of the cardholder is an essential topic. There are two alternative outcomes of a credit card payment:
- 3-D Secure enabled - by default, 3-D Secure should be enabled, and Swedbank Pay will check if the card is enrolled with 3-D Secure. This depends on the issuer of the card. If the card is not enrolled with 3-D Secure, no authentication of the cardholder is done.
- Card supports 3-D Secure - if the card is enrolled with 3-D Secure, Swedbank Pay 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.