Swedbank Pay Card Payments – Direct

warning

Section under review

This section of the Developer Portal is under review and may be incomplete or contain minor errors.

The Direct Card Payment scenario is used by customers that are compliant with PCI-DSS regulations, and is a way to implement Card Payments without using a Swedbank Pay hosted payment page.

info

Note on 3-D Secure Authentication

Although there is no need to redirect to a Swedbank Pay hosted payment page in the Direct Card Payment scenario, consumers will need to be redirected to a 3-D Secure page hosted by the issuing bank if the bank requires it. Whether 3-D Secure authentication is required for every payment is up to each issuing bank and out of Swedbank Pay’s control.

error

PCI-DSS Complicance

The direct integration option requires you to collect the card data on your website, which means it must be PCI-DSS Compliant.

Payment flow

Below is a quick stepwise summary of how the Direct Card Payment scenario works.

  • The payer places an order and you make a Purchase request towards Swedbank Pay with the gathered payment information.
  • The action taken next is the direct-authorization operation that is returned in the first request. You POST the payer’s card data to the URL in the direct-authorization operation.
  • If the issuer requires 3-D Secure authentication, you will then receive an operation called redirect-authentication. You must redirect the payer to this URL to let them authenticate against the issuer’s 3-D Secure page.
    • When the 3-D Secure flow is completed, the payer will be redirected back to the URL provided in completeUrl or cancelUrl, depending on the actions performed by the payer.
    • If the issuer does not require 3-D Secure authentication, the payment will already be Completed after performing the direct-authorization request. Note that Completed just indicates that the payment is in a final state; the financial transaction could be either OK or failed.
  • Finally you make a GET request towards Swedbank Pay with the id of the payment created in the first step, which will return the result of the authorization.

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. An example of an expanded POST request is available in the other features section.

info

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.

Request

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
71
POST /psp/creditcard/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [{
                "type": "CreditCard",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": { 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "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"
        },
        "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, that defines the type card payment created.

Purchase. Used to charge a card. It is followed up by a capture or cancel operation.

Recur.Used to charge a card on a recurring basis. Is followed up by a capture or cancel operation (if not Autocapture is used, that is).

Payout. Used to deposit funds directly to credit card. No more requests are necessary from the merchant side.

Verify. Used when authorizing a card withouth reserveing any funds. It is followed up by a verification transaction.
check └➔ intent string Authorization. Reserves the amount, and is followed by a cancellation or capture of funds.

AutoCapture. A one phase option that enable capture of funds automatically after authorization.
  └➔ paymentToken string If you put in a paymentToken here, the payment page will preload the stored payment data related to the paymentToken and let the consumer make a purchase without having to enter all card data. 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 generic type CreditCard if you want to enable all card brands supported by merchant contract. Use card brands like Visa (for card type Visa), MasterCard (for card type MasterCard) and others if you want to specify different amount for each card brand. If you want to use more than one amount you must have one instance in the prices node for each card brand. You will not be allowed to both specify card brands and CreditCard at the same time in this field. See the Prices resource and prices object types for more information.
check └─➔ amount integer The amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check └─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). Set to 0 (zero) if there is no VAT amount charged.
check └➔ description string(40) A 40 character length textual description of the purchase.
  └➔ payerReference string The reference to the payer (consumer/end user) from the merchant system. E.g mobile number, customer number etc.
  └➔ 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 string of the consumer’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.
  └─➔ hostUrls array The array of URLs valid for embedding of Swedbank Pay Hosted Views. If not supplied, view-operation will not be available.
check └─➔ completeUrl string The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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.
check └─➔ cancelUrl string The URI to redirect the payer to if the payment is canceled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both.
  └─➔ paymentUrl string The URI 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. Only used in Seamless Views. 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. Require https.
  └─➔ termsOfServiceUrl string The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement.
check └➔ payeeInfo string The payeeInfo object, containing information about the payee (the recipient of the money).
check └─➔ payeeId string This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
check └─➔ payeeReference string(50*) A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
  └─➔ payeeName string The payee name (like merchant name) that will be displayed to consumer when redirected to Swedbank Pay.
  └─➔ productCategory string 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 split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used.
  └➔ metadata object The keys and values that should be associated with the payment. Can be additional identifiers and data you want to associate with the payment.
  └➔ 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 promt for 3-D Secure 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 likelyhood 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 payer is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
  └➔ 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.
  └─➔ 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.

Response

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "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": 1500,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "payerReference": "AB1234",
        "initiatingSystemUserAgent": "PostmanRuntime/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" },
        "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"
        }
    ]
}
Field Type Description
payment object The payment object contains information about the specific payment.
└➔ id string The relative URI and unique identifier of the payment resource . Please read about URI Usage to understand how this and other URIs 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, for that 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 URI and unique identifier of the prices resource . Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ amount integer The amount (including VAT, if any) to charge the payer, 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.
└➔ payerReference string The reference to the payer (consumer/end-user) from the merchant system, like e-mail address, mobile number, customer number etc.
└➔ userAgent string The User-Agent string of the consumer’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 URI to the urls resource where all URIs related to the payment can be retrieved.
└➔ payeeInfo string The URI to the payeeinfo resource where the information about the payee of the payment can be retrieved.
operations array The array of possible operations to perform
└─➔ method string The HTTP method to use when performing the operation.
└─➔ href string The target URI to perform the operation against.
└─➔ rel string The name of the relation the operation has to the current resource.
link

Callback URL

It is mandatory to set a callbackUrl in the POST request creating the payment. If callbackUrl is set, Swedbank Pay will send a POST request to this URL when the consumer 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.

report_problem

Step 2 is to create an authorization transaction. Implement only Step 2a if 3-D Secure authentication is enabled. Note that if the issuer does not require 3-D Secure authentication, implement only Step 2b. You will see that the requests are the same for both steps. The difference is in the operations, where Step 2a has the redirect-authentication operation in its response. This is needed for the payer to be redirected to complete the 3-D Secure authentication.

Step 2a: Create authorization without 3-D Secure authentication

The direct-authorization operation creates an authorization transaction directly.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "cardNumber": "4925000000000004",
        "cardExpiryMonth": "12",
        "cardExpiryYear": "22",
        "cardVerificationCode": "749",
        "cardholderName": "Olivia Nyhuus",
        "chosenCoBrand": "visa"
    }
}
Required Field Type Description
check transaction object The transaction object.
check └➔ cardNumber string Primary Account Number (PAN) of the card, printed on the face of the card.
check └➔ cardExpiryMonth integer Expiry month of the card, printed on the face of the card.
check └➔ cardExpiryYear integer Expiry year of the card, printed on the face of the card.
  └➔ cardVerificationCode string Card verification code (CVC/CVV/CVC2), usually printed on the back of the card.
  └➔ cardholderName string Name of the cardholder, usually printed on the face of the card.

Response

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "direct": true,
        "cardBrand": "Visa",
        "cardType": "Credit",
        "maskedPan": "492500******0004",
        "expiryDate": "12/2022",
        "panToken": "eb488c77-8118-4c9f-b3b3-ff134936df64",
        "panEnrolled": false,
        "issuerAuthorizationApprovalCode": "L99099",
        "acquirerTransactionType": "SSL",
        "acquirerStan": "99099",
        "acquirerTerminalId": "86",
        "acquirerTransactionTime": "2020-04-07T22:35:26Z",
        "nonPaymentToken": "ed4683a8-6d2a-4a14-b065-746a41316b8f",
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2020-04-07T20:35:24.8344431Z",
            "updated": "2020-04-07T20:35:26.3472343Z",
            "type": "Authorization",
            "state": "Completed",
            "number": 99100557070,
            "amount": 4201,
            "vatAmount": 0,
            "description": "Books & Ink",
            "payeeReference": "cyrusLibrary1586291679",
            "isOperational": false,
            "operations": [
                {
                    "method": "PATCH",
                    "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "update-authorization-overchargedamount"
                }
            ]
        }
    }
}
Field Type Description
payment object The payment object.
authorization object The authorization object.
└➔ direct string The type of the authorization.
└➔ cardBrand string Visa, MC, etc. The brand of the card.
└➔ cardType string Credit Card or Debit Card. Indicates the type of card used for the authorization.
└➔ issuingBank string The name of the bank that issued the card used for the authorization.
└➔ paymentToken string The payment token created for the card used in the authorization.
└➔ maskedPan string The masked PAN number of the card.
└➔ expiryDate string The month and year of when the card expires.
└➔ panToken string The token representing the specific PAN of the card.
└➔ panEnrolled string  
└➔ acquirerTransactionTime string 3DSECURE or SSL. Indicates the transaction type of the acquirer.
└➔ nonPaymentToken string Swedbank Pay’s tokenization of the card used; identifies the card, but can not be used for payment transactions. Needs to be activated by Swedbank Pay before use.
└➔ id string The relative URI and unique identifier of the itemDescriptions resource . Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ transaction object The object representation of the generic transaction resource.
└─➔ id string The relative URI and unique identifier of the transaction resource . Please read about URI Usage to understand how this and other URIs should be used in your solution.
└─➔ created string The ISO-8601 date and time of when the transaction was created.
└─➔ updated string The ISO-8601 date and time of when the transaction was updated.
└─➔ type string Indicates the transaction type.
└─➔ state string Initialized, Completed or Failed. Indicates the state of the transaction.
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, for that id should be used instead.
└─➔ amount integer Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
└─➔ vatAmount integer If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
└─➔ description string A 40 character length textual description of the purchase.
└─➔ payeeReference string A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
└─➔ failedReason string The human readable explanation of why the payment failed.
└─➔ isOperational bool true if the transaction is operational; otherwise false.
└─➔ operations array The array of operations that are possible to perform on the transaction in its current state.

If the issuer does not require 3-D Secure authentication, the payment will be completed after the direct-authorization request and the state of the transaction will be set to Completed. If the issuer requires 3-D Secure authentication, read step 2b below for how to complete the authorization.

info

Completed means final, not successful.

Note that Completed 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.

Step 2b: Create authorization with 3-D Secure authentication

If the issuer requires 3-D Secure authentication, the response from the authorization request will contain a redirect-authentication operation and the state of the transaction will be AwaitingActivity. This means that the payer will have to be redirected to the issuer to complete the 3-D Secure authentication. See the request and response examples below.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "cardNumber": "4547781087013329",
        "cardExpiryMonth": "12",
        "cardExpiryYear": "22",
        "cardVerificationCode": "749",
        "cardholderName": "Olivia Nyhuus",
        "chosenCoBrand": "visa"
    }
}
Required Field Type Description
check transaction object The transaction object.
check └➔ cardNumber string Primary Account Number (PAN) of the card, printed on the face of the card.
check └➔ cardExpiryMonth integer Expiry month of the card, printed on the face of the card.
check └➔ cardExpiryYear integer Expiry year of the card, printed on the face of the card.
  └➔ cardVerificationCode string Card verification code (CVC/CVV/CVC2), usually printed on the back of the card.
  └➔ cardholderName string Name of the cardholder, usually printed on the face of the card.

Response

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "direct": true,
        "cardBrand": "Visa",
        "cardType": "Credit",
        "issuingBank": "Utl. Visa",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "maskedPan": "454778******3329",
        "expiryDate": "12/2020",
        "panToken": "cca2d98d-8bb3-4bd6-9cf3-365acbbaff96",
        "panEnrolled": true,
        "acquirerTransactionTime": "0001-01-01T00:00:00Z",
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2020-03-10T13:15:01.9586254Z",
            "updated": "2020-03-10T13:15:02.0493818Z",
            "type": "Authorization",
            "state": "AwaitingActivity",
            "number": 70100366758,
            "amount": 4201,
            "vatAmount": 0,
            "description": "Test transaction",
            "payeeReference": "1583846100",
            "isOperational": true,
            "operations": [
                {
                    "method": "GET",
                    "href": "https://api.externalintegration.payex.com/psp/creditcard/confined/payments/authorizations/authenticate/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "redirect-authentication"
                }
            ]
        }
    }
}
Field Type Description
payment object The payment object.
authorization object The authorization object.
└➔ direct string The type of the authorization.
└➔ cardBrand string Visa, MC, etc. The brand of the card.
└➔ cardType string Credit Card or Debit Card. Indicates the type of card used for the authorization.
└➔ issuingBank string The name of the bank that issued the card used for the authorization.
└➔ paymentToken string The payment token created for the card used in the authorization.
└➔ maskedPan string The masked PAN number of the card.
└➔ expiryDate string The month and year of when the card expires.
└➔ panToken string The token representing the specific PAN of the card.
└➔ panEnrolled string  
└➔ acquirerTransactionTime string 3DSECURE or SSL. Indicates the transaction type of the acquirer.
└➔ id string The relative URI and unique identifier of the itemDescriptions resource . Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ transaction object The object representation of the generic transaction resource.
└─➔ id string The relative URI and unique identifier of the transaction resource . Please read about URI Usage to understand how this and other URIs should be used in your solution.
└─➔ created string The ISO-8601 date and time of when the transaction was created.
└─➔ updated string The ISO-8601 date and time of when the transaction was updated.
└─➔ type string Indicates the transaction type.
└─➔ state string Initialized, Completed or Failed. Indicates the state of the transaction.
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, for that id should be used instead.
└─➔ amount integer Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
└─➔ vatAmount integer If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
└─➔ description string A 40 character length textual description of the purchase.
└─➔ payeeReference string A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
└─➔ failedReason string The human readable explanation of why the payment failed.
└─➔ isOperational bool true if the transaction is operational; otherwise false.
└─➔ operations array The array of operations that are possible to perform on the transaction in its current state.

When you find the redirect-authentication operation in the response from the authorization request, you will have to perform an HTTP redirect of the payer to the URI of the href to complete the authorization by performing a 3-D Secure authentication with the issuer.

When the 3-D Secure flow is completed, the payer will be redirected back to the URL provided in completeUrl or cancelUrl, depending on the actions performed by the payer.

The sequence diagram below shows a high level description of a complete purchase, and the requests you have to send to Swedbank Pay.

sequenceDiagram
    participant Payer
    participant Merchant
    participant SwedbankPay as Swedbank Pay
    participant IssuingBank as Issuing Bank
    activate Payer
    Payer->>Merchant: Start purchase
    activate Merchant
    Merchant->>SwedbankPay: POST /psp/creditcard/payments
    activate SwedbankPay
    note left of Merchant: First API request
    SwedbankPay->>Merchant: Payment resource
    deactivate SwedbankPay
    Merchant->>Payer: Credit card form
    deactivate Merchant
    Payer->>Merchant: Submit credit card form
    activate Merchant
    Merchant->>SwedbankPay: POST rel:direct-authorization
    activate SwedbankPay
    note left of Merchant: Second API request
    SwedbankPay->>Merchant: Authorization resource
    deactivate SwedbankPay
        alt No 3DSecure required
            Merchant->>Payer: Redirected to merchant's completeUrl
        else 3DSecure required
            Merchant->>Payer: Redirect to rel:redirect-authentication
            deactivate Merchant
            note left of Payer: redirect to card issuing bank
            Payer->>IssuingBank: Perform 3-D Secure authentication
            activate IssuingBank
            IssuingBank->>Payer: Redirected to merchant's completeUrl
            deactivate IssuingBank
        end
    note left of Payer: redirect back to merchant
    Payer->>Merchant: Access merchant's completeUrl
    activate Merchant
    Merchant->>SwedbankPay: GET <payment.id>
    activate SwedbankPay
    note left of Merchant: Third API request
    SwedbankPay-->Merchant: Payment resource
    deactivate SwedbankPay
    Merchant->>Merchant: Inspect payment status
    Merchant-->>Payer: Display purchase result
    deactivate Merchant
    deactivate Payer

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.
  • Callback from Swedbank Pay: Whenever changes to the payment occur a Callback request will be posted to the callbackUrl, generated when the payment was created.