Card

Other Features

schedule 90 min read

Welcome to Other Features - a subsection of Credit Card. This section has extented code examples and features that were not covered by the other subsections.

Payment Resource

The payment resource is central to all payment instruments. All operations that target the payment resource directly produce a response similar to the example seen below. The response given contains all operations that are possible to perform in the current state of the payment.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "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"
        },
        "payeeInfo": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo"
        },
        "urls": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "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"
        }
    },
    "operations": [,
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/operation=authorize",
            "rel": "view-authorization",
            "contentType": "application/javascript"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "redirect-authorization",
            "contentType": "text/html"
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "contentType": "application/json"
        },
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
            "rel": "create-capture",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid",
            "rel": "paid-payment",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/failed",
            "rel": "failed-payment",
            "contentType": "application/json"
        }
        
    ]
}
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.
└➔ prices.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.
└➔ description string A 40 character length textual description of the purchase.
└➔ payerReference string(40) The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc.
└➔ userAgent string The user agent string of the payer’s 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 payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
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.

Operations

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

Operation Description
update-payment-abort aborts the payment order before any financial transactions are performed.
redirect-authorization Contains the URI that is used to redirect the payer to the Swedbank Pay Payments containing the card authorization UI.
view-authorization Contains the JavaScript href that is used to embed the card authorization UI directly on the webshop/merchant site
view-payment Contains the URI of the JavaScript to create a Seamless view iframe directly without redirecting the payer to a separate payment page.
create-capture Creates a capture transaction in order to charge the reserved funds from the payer.
create-cancellation Creates a cancellation transaction that cancels a created, but not yet captured payment.
paid-payment Returns the information about a payment that has the status paid.
failed-payment Returns the information about a payment that has the status failed.

Operation paid-payment

The paid-payment operation confirms that the transaction has been successful and that the payment is completed.

A paid-payment operation looks like the following:

1
2
3
4
5
6
{
   "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid",
   "rel": "paid-payment",
   "method": "GET",
   "contentType": "application/json"
}

To inspect the paid payment, you need to perform an HTTP GET request towards the operation’s href field. An example of how the request and response look like is given below.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

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

{
  "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
  "paid": {
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid",
    "number": 1234567890,
    "transaction": {
      "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/",
      "number" : 1234567891
    },
    "payeeReference": "CD123",
    "orderReference": "AB1234",
    "amount": 1500,
    "tokens": [
      {
        "type": "payment",
        "token": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "name": "4925xxxxxx000004",
        "expiryDate" : "mm/yyyy"
      },
      {
        "type": "recurrence",
        "token": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "name": "4925xxxxxx000004",
        "expiryDate" : "mm/yyyy"
      },
      {
        "type": "transactionsOnFile",
        "token": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "name": "4925xxxxxx000004",
        "expiryDate" : "mm/yyyy"
      }
    ],
    "details": {
      "cardBrand": "Visa",
      "MaskedPan": "4925xxxxxx000004",
      "cardType": "Credit",
      "issuingBank": "UTL MAESTRO",
      "countryCode": "999",
      "acquirerTransactionType": "3DSECURE",
      "issuerAuthorizationApprovalCode": "397136",
      "acquirerStan": "39736",
      "acquirerTerminalId": "39",
      "acquirerTransactionTime": "2017-08-29T13:42:18Z",
      "nonPaymentToken" : "12345678-1234-1234-1234-1234567890AB",
      "externalNonPaymentToken" : "1234567890",
      "transactionInitiator" : "MERCHANT"
    }
  }
}
Field Type Description
payment string The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ transaction string The transaction object, containing information about the current transaction.
└─➔ id string The relative URI and unique identifier of the transaction resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└─➔ 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.
└➔ 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.
└➔ orderReference string(50) The order reference should reflect the order reference found in the merchant’s systems.
└➔ 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.
└➔ tokens integer List of tokens generated.
└➔ details integer A human readable and descriptive text of the payment.
└─➔ cardBrand string Visa, MC, etc. The brand of the card.
└─➔ maskedPan string The masked PAN number 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.
└─➔ countryCode string The country the card is issued in.
└─➔ acquirerTransactionType string 3DSECURE or SSL. Indicates the transaction type of the acquirer.
└─➔ acquirerStan string The System Trace Audit Number assigned by the acquirer to uniquely identify the transaction.
└─➔ acquirerTerminalId string The ID of the acquirer terminal.
└─➔ acquirerTransactionTime string The ISO-8601 date and time of the acquirer transaction.
└─➔ nonPaymentToken string Result of our own tokenization of the card used. Activated in POS on merchant or merchant group.
└─➔ externalNonPaymentToken string Result of external tokenization. This value varies depending on cards, acquirer, customer, etc. For ICA cards, the token comes in response from Swedbank. For Mass Transit(SL) it is populated with PAR if it comes in response from the redeemer (Visa). If not, our own token (Mastercard / Amex).

Operation failed-payment

The failed-payment operation means that something went wrong during the payment process, the transaction was not authorized, and no further transactions can be created if the payment is in this state.

A failed-payment operation looks like the following:

1
2
3
4
5
6
{
   "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/failed",
   "rel": "failed-payment",
   "method": "GET",
   "contentType": "application/problem+json"
}

To inspect why the payment failed, you need to perform an HTTP GET request towards the operation’s href field.

Under details you can see the problem message and under problems you can see which problem and the description of the problem with the corresponding error code.

An example of how the request and response look like is given below.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/failed HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
HTTP/1.1 200 OK
Content-Type: application/json

{
   "problem": {
       "type": "https://api.externalintegration.payex.com/psp/errordetail/creditcard/acquirererror",
       "title": "Operation failed",
       "status": 403,
       "detail":  "Unable to complete Authorization transaction, look at problem node!", 
       "problems": [
        {
          "name": "ExternalResponse",
          "description": "REJECTED_BY_ACQUIRER-unknown error, response-code: 51"
        }
        ]
     }
  }
}

Operation aborted-payment

The aborted-payment operation means that the merchant has aborted the payment before the payer has fulfilled the payment process. You can see this under abortReason in the response.

An aborted-payment operation looks like the following:

1
2
3
4
5
6
{
    "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/<paymentId>/aborted",
    "rel": "aborted-payment",
    "method": "GET",
    "contentType": "application/json"
}

To inspect why the payment was aborted, you need to perform an HTTP GET request towards the operation’s href field. An example of how the request and response looks like is given below.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/aborted HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json

{
  "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
  "aborted": {
    "abortReason": "Aborted by consumer"
  }
}

Payment And Transaction States

Both payments and transactions can be in several different states during the course of a purchase. You can find a short description of each state below.

Payment States

  • ready means that the payment has been created successfully, and is now ready for further transaction operations, like authorization, sale or abort.

  • failed means that something went wrong during the payment process, and no further transactions can be created if the payment is in this state. Examples of possible failures are triggering of anti-fraud protection or if the payer reaches the maximum number of attempts for a given payment.

  • aborted means that the merchant has aborted the payment before the payer has fulfilled the payment process. Aborting a payment is done by performing the update-payment-abort operation.

  • pending is the state of a payment when a transaction is in an initialized state. See more below. As long as a payment is pending, no further transactions can be done.

info

If you want to inspect the transactional status of a payment, read about the paid-payment, failed-payment and aborted-payment operations.

Transaction States

  • ìntialized is the transaction state when something unexpected occured, and it is impossible to determine the exact status of the transaction. An example of this can be a network failure. No further actions can be done on a payment with a transaction in this state.

  • completed means that the transaction has reached its intended purpose. An authorization will be completed when the funds have been authorized, a capture will be completed when the funds have been captured and a reversal will be completed when the payer has been refunded.

  • failed means that the transaction has failed. The state is final for that specific transaction, but given that the payment is operational, it is possible to perform more transactions on the same payment, i.e. retry the authorization with another card. If the payer reaches the maximum amount of retries, the payment itself will be set to failed.

  • awaitingActivity is in use for a selection of payment instruments. A transaction reaches this state when a payer is sent away from Swedbank Pay to do a confirmation or verification. Examples of this can be payment apps like Swish, Vipps or MobilePay, or 3-D Secure verifications for card payments.

Payment State

The state field on the authorization does not indicate whether a given transaction was successful or not, it only tells whether the authorization resource itself is operational or not. To figure out the state of i.e. authorization transactions, you have two options:

You can perform a GET request on the authorization. As long as the authorization has been completed, successful or not, you will find the Paid or Failed operation among the operations in the response.

Please note that a authorization where a Failed attempt has been made, but the payer still has attempts left to complete the authorization, you won’t see the Failed operation. It will only appear when all attempts have been made.

Authorization or Sale Transactions

Find the authorization’s list of transactions either by expanding it when retrieving the authorization, or by performing a GET request towards the transactions.id URI.

If you find a transaction with type equal to authorization, with its state equal to Completed, you can be sure that the amount of the authorization has been reserved or withdrawn and that the authorization can be considered successful.

Create Payment

Within the card payments part of the eCommerce API, you can create four kinds of payments (purchase, recurrence, payout and verification) and you can inspect and alter the details of the individual transactions within the payment.

To create a card payment, you perform an HTTP POST against the payments resource.

There are four different kinds of payment that can be created. These are identified with the value of the operation field. Each kind are documented in their own section below.

Request

1
2
3
4
5
6
7
8
9
10
11
POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "<operation>",
        "intent": "<intent>",
    }
}
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 The intent of the payment identifies how and when the charge will be effectuated. This determine the type transactions used during the payment process.

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.

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.

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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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",
        "generatePaymentToken": false,
        "generateRecurrenceToken": false,
        "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"
            }, 
            "billingAddress": {
                "firstName": "Olivia",
                "lastName": "Nyhuus",
                "email": "olivia.nyhuus@payex.com",
                "msisdn": "+4798765432",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            },
            "accountInfo": {
                "accountAgeIndicator": "01",
                "accountChangeIndicator": "01",
                "accountPwdChangeIndicator": "01",
                "shippingAddressUsageIndicator": "01",
                "shippingNameIndicator": "01",
                "suspiciousAccountActivity": "01",
                "addressMatchIndicator": "false"
            }
        },
        "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"
            }
        },
        "metadata": {
            "key1": "value1",
            "key2": 2,
            "key3": 3.1,
            "key4": false
        }
    },
    "creditCard": {
        "rejectCreditCards": false,
        "rejectDebitCards": false,
        "rejectConsumerCards": false,
        "rejectCorporateCards": false,
        "no3DSecure": false
    }
}
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 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 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 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 ofthe 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.
  └➔ payerReference string The reference to the payer from the merchant system, like e-mail address, 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 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.
  └─➔ 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. See [completeUrl][completeurl] for details.
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. See paymentUrl for details.
  └─➔ 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 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). 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(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 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 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.
  └➔ 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)
  └─➔ accountInfo object Optional (increased chance for frictionless flow if set).

If cardholder is known by merchant and have some kind of registered user then these fields can be set.
  └──➔ accountAgeIndicator string Optional (increased chance for frictionless flow if set).

Indicates the length of time that the payments account was enrolled in the cardholder’s account with merchant.
01 (No account, guest)
02 (Created during transaction)
03 (Less than 30 days)
04 (30-60 days)
05 (More than 60 days)
  └──➔ accountChangeIndicator string Optional (increased chance for frictionless flow if set).

Length of time since the cardholder’s account information with the merchant was changed. Including billing etc.
01 (Changed during transaction)
02 (Less than 30 days)
03 (30-60 days)
04 (More than 60 days)
  └──➔ accountPwdChangeIndicator string Optional (increased chance for frictionless flow if set).

Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset.
01 (No change)
02 (Changed during transaction)
03 (Less than 30 days)
04 (30-60 days)
05 (More than 60 days)
  └──➔ shippingAddressUsageIndicator string Optional (increased chance for frictionless flow if set).

Indicates when the shipping address used for this transaction was first used with the merchant.
01 (This transaction)
02 (Less than 30 days)
03 (30-60 days)
04 (More than 60 days)
  └──➔ shippingNameIndicator string Optional (increased chance for frictionless flow if set).

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
01 (Account name identical to shipping name)
02 (Account name different than shipping name)
  └──➔ suspiciousAccountActivity string Optional (increased chance for frictionless flow if set).

Indicates whether merchant has experienced suspicious activity (including previous fraud) on the cardholder account.
01 (No suspicious activity has been observed)
02 (Suspicious activity has been observed)
  └──➔ addressMatchIndicator boolean Optional (increased chance for frictionless flow if set)

Allows the 3-D Secure Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
  └─➔ riskIndicator object This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelyhood of having to promt for 3-D Secure 2.0 authentication of the payer when they are authenticating the purchase.
  └➔ 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 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.
  └─➔ 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.
  creditCard object The credit card object.
  └➔ rejectDebitCards boolean true if debit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ rejectCreditCards boolean true if credit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ rejectConsumerCards boolean true if consumer cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ rejectCorporateCards boolean true if corporate cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ no3DSecure boolean true if 3-D Secure should be disabled for this payment in the case a stored card is used; otherwise false per default. To use this feature it has to be enabled on the contract with Swedbank Pay.
  └➔ noCvc boolean true if the CVC field should be disabled for this payment in the case a stored card is used; otherwise false per default. This feature is commonly used when One-Click Payments is enabled. To use this feature it has to be enabled on the contract with Swedbank Pay.

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
61
62
63
64
65
66
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": 0,
        "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"
        },
        {
            "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 URI and unique identifier of the payment resource this transaction belongs to.. 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 this transaction belongs to.. 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 from the merchant system, like e-mail address, mobile number, customer number etc.
└➔ userAgent string The User-Agent string of 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 URI to the urls resource where all URIs related to the payment can be retrieved.
└➔ payeeInfo string The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
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.

CompleteUrl

This URL will be used by Swedbank Pay when a payment is Completed or Failed. If your integration subscribes to the onPaymentCompleted and possibly the onPaymentFailed event, no redirect or use of the completeUrl will take place. But if you do not have any event handler for the onPaymentCompleted event, the Swedbank Pay JavaScript will perform an HTTP redirect in the top frame to the completeUrl. You will still need to do a GET request on the payment resource to find the final status (Completed or Failed).

Description

The description field is a 40 character length textual summary of the purchase. It is needed to specify what payer is actually purchasing. Below you will find an abbreviated Card Payments Purchase request.

As you can see the description field is set to be Test Description in the the code example.

info

Notice that for Redirect, the description will be shown as Test - Reference1583419461, as set in the code example. For the Seamless View scenario, the description is not shown in the payment window, but it is still required in the initial request.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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 Description",
        "generateRecurrenceToken": false,
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls":
            "hostUrls": ["https://example.com"]
        }
}

The description field as presented in Card Payments

Recur

A recur payment is a payment that references a recurrenceToken created through a previous payment in order to charge the same card.

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
POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Recur",
        "intent": "Authorization",
        "recurrenceToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "currency": "NOK",
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Recurrence",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "callbackUrl": "https://example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b"
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "metadata": {          
            "key1": "value1",
            "key2": 2,
            "key3": 3.1,
            "key4": false
        }
    }
}
Required Field Type Description
check payment object The payment object.
check operation object Recur.
check └➔ recurrenceToken string The created recurrenceToken, if operation: Verify, operation: Recur or generateRecurrenceToken: true was used.
check └➔ currency string The currency of the payment order.
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 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 ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check └➔ description string A 40 character length textual description of the purchase.
check └─➔ userAgent string The User-Agent string of the payer’s web browser.
check └─➔ language string sv-SE, nb-NO or en-US.
check └─➔ urls string {he URI to the urls resource where all URIs related to the payment order can be retrieved.
check └─➔ 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.
check └➔ payeeInfo string 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(30) 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.In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
  └➔ receiptReference string(30) A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number.
check └─➔ payeeName string The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
check └─➔ 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.
check └─➔ orderReference String(50) The order reference should reflect the order reference found in the merchant’s systems.
check └─➔ 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 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.In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.

Unscheduled Purchase

warning

This feature is only available for merchants who have a specific agreement with Swedbank Pay.

An unscheduled purchase, also called a Merchant Initiated Transaction (MIT), is a payment which uses a paymentToken generated through a previous payment in order to charge the same card at a later time. They are done by the merchant without the cardholder being present.

unscheduled purchases differ from recur as they are not meant to be recurring, but occur as singular transactions. Examples of this can be car rental companies charging the payer’s card for toll road expenses after the rental period.

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
POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "UnscheduledPurchase",
        "intent": "Authorization",
        "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "currency": "NOK",
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Unscheduled",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "callbackUrl": "https://example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        }
    }
}

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

{
  "payment": {
    "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
    "number": 1234567890,
    "created": "2016-09-14T13:21:29.3182115Z",
    "updated": "2016-09-14T13:21:57.6627579Z",
    "state": "Ready",
    "operation": "Purchase",
    "intent": "Authorization",
    "currency": "NOK",
    "amount": 1500,
    "remainingCaptureAmount": 1500,
    "remainingCancellationAmount": 1500,
    "remainingReversalAmount": 0,
    "description": "Test Unscheduled",
    "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
    "userAgent": "Mozilla/5.0...",
    "language": "nb-NO",
    "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "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" }
  }
}

Payout

Payout to Card is an add-on service which enables you to deposit winnings directly to the winner’s card. This without having to collect card details a second time.

Introduction

  • The only acquirer for this service is Swedbank. You require a separate Swedbank acquiring number to ensure that payout transactions and regular card transactions are kept separate.
  • You need to have the 3-D Secure protocol enabled.
  • The service is available through a Swedbank Pay hosted payment page.
  • The current implementation is only available for gaming transactions ( MCC: 7995).
  • The payout service is not a part of Swedbank Pay Settlement Service.

API requests

The API requests are displayed in the payout flow.  You create a payout by performing a POST creditcard payments with key operation set to payout.

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
POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Payout",
        "intent": "AutoCapture",
        "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "currency": "NOK",
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Payout",
        "userAgent": "Mozilla/5.0",
        "language": "nb-NO",
        "urls": {
            "callbackUrl": "https://example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b"
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        }
    }
}

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

{
  "payment": {
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "number": 1234567890,
    "created": "2016-09-14T13:21:29.3182115Z",
    "updated": "2016-09-14T13:21:57.6627579Z",
    "state": "Ready",
    "operation": "Payout",
    "currency": "NOK",
    "amount": 1500,
    "remainingCaptureAmount": 1500,
    "remainingCancellationAmount": 1500,
    "remainingReversalAmount": 0,
    "description": "Test Recurrence",
    "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
    "userAgent": "Mozilla/5.0...",
    "language": "nb-NO",
    "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "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" }
  }
}

Payout flow

You must set Operation to Payout in the initial POST request.

sequenceDiagram
  activate Payer
  Payer->>-Merchant: Start payout
  activate Merchant
  Merchant->>-SwedbankPay: POST [Credit Card Payout]
  activate SwedbankPay
  SwedbankPay-->>-Merchant: Payment resource
  activate Merchant
  Merchant-->>-Payer: Display Payout result

Verify

The Verify operation lets you post verification payments, which are used to confirm the validity of card information without reserving or charging any amount.

Introduction to Verify

This option is commonly used when initiating a subsequent One-click card payment or a recurring card payment flow - where you do not want to charge the payer right away.

info

Please note that all boolean credit card attributes involving the rejection of certain card types are optional and require enabling on the contract with Swedbank Pay.

Verification through Swedbank Pay Payments

  • When properly set up in your merchant/webshop site and the payer initiates a verification operation, you make a POST request towards Swedbank Pay with your Verify information. This will generate a payment object with a unique paymentID. You either receive a Redirect URL to a hosted page or a JavaScript source in response.
  • You need to redirect the payer’s browser to that specified URL, or embed the script source on your site to create a Hosted View in an iframe; so that the payer can enter the card details in a secure Swedbank Pay hosted environment.
  • Swedbank Pay will handle 3-D Secure authentication when this is required.
  • Swedbank Pay will redirect the payer’s browser to - or display directly in the iframe - one of two specified URLs, depending on whether the payment session is followed through completely or cancelled beforehand. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.
  • When you detect that the payer reach your completeUrl, you need to do a GET request to receive the state of the transaction.
  • Finally you will make a GET request towards Swedbank Pay with the paymentID received in the first step, which will return the payment result and a paymentToken that can be used for subsequent One-Click Payments and recurring server-to-server based payments.

Screenshots

You will redirect the payer to Swedbank Pay hosted pages to collect the credit card information.

screenshot of the swedish card verification page

API Requests

The API requests are displayed in the Verification flow below. The options you can choose from when creating a payment with key operation set to Value Verify are listed below.

Please note that not including paymentUrl in the request will generate a redirect-verification operation in the response, meant to be used in the Redirect flow. Adding paymentUrl input will generate the response meant for Seamless View, which does not include the redirect-verification. The request below is the Redirect option.

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
POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Verify",
        "currency": "NOK",
        "description": "Test Verification",
        "payerReference": "AB1234",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "generatePaymentToken": true,
        "generateRecurrenceToken": true,
        "urls": {
            "hostUrls": ["https://example.com", "https://example.net"],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.html"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        }
    },
    "creditCard": {
        "rejectCreditCards": false,
        "rejectDebitCards": false,
        "rejectConsumerCards": false,
        "rejectCorporateCards": false
    }
}

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

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "operation": "Verify",
        "state": "Ready",
        "currency": "NOK",
        "amount": 0,
        "description": "Test Verification",
        "payerReference": "AB1234",
        "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "nb-NO",
        "transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "verifications": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications" },
        "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": [
        {
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH",
            "contentType": "application/json"
        },
        {
            "href": "https://ecom.externalintegration.payex.com/creditcard/payments/verification/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "redirect-verification",
            "method": "GET",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "view-verification",
            "contentType": "application/javascript"
        },
        {
            "method": "POST",
            "href": "https://ecom.externalintegration.payex.com/psp/creditcard/confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications",
            "rel": "direct-verification",
            "contentType": "application/json"
        }
    ]
}

Verification flow

The sequence diagram below shows the two requests you have to send to Swedbank Pay to make a purchase. The links will take you directly to the API description for the specific request. The diagram also shows in high level, the sequence of the process of a complete purchase. When dealing with credit card payments, 3-D Secure authentication of the cardholder is an essential topic. There are three alternative outcome 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.
sequenceDiagram
    participant Payer
    participant Merchant
    participant SwedbankPay as Swedbank Pay
    participant IssuingBank

  activate Payer
  Payer->>+Merchant: start verification
  deactivate Payer
  Merchant->>+SwedbankPay: POST /psp/creditcard/payments(operation=VERIFY)
  deactivate Merchant
  note left of Payer: First API request
  SwedbankPay-->+Merchant: payment resource
  deactivate SwedbankPay
  Merchant-->>+Payer: redirect to verification page
  deactivate Merchant
  Payer->>+SwedbankPay: access verification page
  deactivate Payer
  note left of Payer: redirect to SwedbankPay<br>(If Redirect scenario)
  SwedbankPay-->>+Payer: display purchase information
  deactivate SwedbankPay

  Payer->>Payer: input creditcard information
  Payer->>+SwedbankPay: submit creditcard information
  deactivate Payer
  opt Card supports 3-D Secure
    SwedbankPay-->>Payer: redirect to IssuingBank
    deactivate SwedbankPay
    Payer->>IssuingBank: 3-D Secure authentication process
    Payer->>+SwedbankPay: access authentication page
    deactivate Payer
  end

  SwedbankPay-->>+Payer: redirect to merchant
  deactivate SwedbankPay
  note left of Payer: redirect back to merchant<br>(If Redirect scenario)

  Payer->>+Merchant: access merchant page
  Merchant->>+SwedbankPay: GET <payment.id>
  deactivate Merchant
  note left of Merchant: Second API request
  SwedbankPay-->>+Merchant: rel: redirect-authorization
  deactivate SwedbankPay
  Merchant-->>Payer: display purchase result
  deactivate Merchant

  opt Callback is set
    activate SwedbankPay
    SwedbankPay->>SwedbankPay: Payment is updated
    SwedbankPay->>Merchant: POST Payment Callback
    deactivate SwedbankPay
  end

One-Click Payments

One-Click Payments utilize a previously generated payment token to prefill payment details for credit card or invoice payments pages - which means that the payer don’t need to enter these details for every purchase.

Introduction

For credit card and financing invoice payments the payment flow and implementation varies from your default only being the use of a paymentToken. The details in this section describe explicitly the parameters that must be set to enable one-click purchases.

API Requests To Generate paymentToken

When making the initial purchase request, you need to generate a paymentToken. You can do this either by by setting the generatePaymentToken field to true (see example below) when doing a card purchase, or set the initial operation to Verify.

generatePaymentToken field

1
2
3
{
    "generatePaymentToken": true
}

Finding paymentToken value

When the initial purchase is successful, a paymentToken is linked to the payment. You can return the value by sending a GET request towards the payment resource (expanding either the authorizations or verifications sub-resource), after the payer successfully has completed the purchase. The two examples are provided below.

Request Towards Authorizations Resource

1
2
3
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>

Request Towards Verifications Resource

1
2
3
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>

You need to store the paymentToken from the response in your system and keep track of the corresponding payerReference in your system.

Returning Purchases

When a known payer (where you have attained a payerReference or similar) returns to your system, you can use the paymentToken, using already stored payment data, to initiate one-click payments. You will need to make a standard purchase, following the sequence as specified in the Redirect or Seamless View scenarios for credit card and financing invoice. When creating the first POST request you insert the paymentToken field. This must be the paymentToken you received in the initial purchase, where you specified the generatePaymentToken to true.

See the Other Feature sections for how to create a card and invoice payment.

Abbreviated code example:

Request

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

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119"
    },
    "creditCard": {
        "noCvc": true
    }
}
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 The intent of the payment identifies how and when the charge will be effectuated. This determine the type transactions used during the payment process.

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.
check └➔ paymentToken string The paymentToken value received in GET response towards the Payment Resource is the same paymentToken generated in the initial purchase request. The token allow you to use already stored card data to initiate one-click payments.
  └➔ creditCard object An object that holds different scenarios for card payments.
  └─➔ noCvc boolean true if the CVC field should be disabled for this payment in the case a stored card is used; otherwise false per default. To use this feature it has to be enabled on the contract with Swedbank Pay.
info

When redirecting to Swedbank Pay the payment page will be prefilled with the payer’s card details. See example below.

One click payment page

Delete payment token

If you, for any reason, need to delete a paymentToken you use the Delete payment token request.

warning

Please note that this call does not erase the card number stored at Swedbank Pay. A card number is automatically deleted six months after a successful Delete payment token request. If you want card information removed at an earlier date, you need to contact ehandelsetup@swedbankpay.dk, verkkokauppa.setup@swedbankpay.fi, ehandelsetup@swedbankpay.no or ehandelsetup@swedbankpay.se; and supply them with the relevant transaction reference or payment token.

Request

1
2
3
4
5
6
7
8
9
10
PATCH /psp/creditcard/payments/instrumentData/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "state": "Deleted",
    "tokenType": "PaymentToken",
    "comment": "Comment on why the deletion is happening"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200 OK
Content-Type: application/json

{
    "instrumentData": {
        "id": "/psp/creditcard/payments/instrumentdata/5a17c24e-d459-4567-bbad-aa0f17a76119",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
        "isDeleted": true,
        "isPayeeToken": false,
        "cardBrand": "Visa",
        "maskedPan": "123456xxxxxx1111",
        "expiryDate": "MM/YYYY"
    }
}

Payment Url

For our Seamless Views, the field called paymentUrl will be used when the payer is redirected out of the Seamless View (the iframe). The payer is redirected out of frame when at the 3-D Secure verification for credit card payments.

The URL should represent the page of where the Payment Seamless View was hosted originally, such as the checkout page, shopping cart page, or similar. Basically, paymentUrl should be set to the same URL as that of the page where the JavaScript for the Seamless View was added to in order to initiate the payment process.

info

Please note that the paymentUrl must be able to invoke the same JavaScript URL from the same Payment as the one that initiated the payment process originally, so it should include some sort of state identifier in the URL. The state identifier is the ID of the order, shopping cart or similar that has the URL of the Payment stored.

With paymentUrl in place, the retry process becomes much more convenient for both the integration and the payer.

paymentUrl is used by the Seamless View flow and must be used for WebView-based app implementations. Some payment instruments only work when owning the full browser page (no use of <iframe>), this will be solved by doing a full browser (top frame) redirect out of the Seamless View. 3-D Secure requires this, for example.

For mobile flows, some payment instruments work best when app-to-app switching is enabled and handled automatically (Swish, Vipps etc). To solve this, it is important that the third party app or site understand where to redirect the payer back to after the flow on their end is completed.

The paymentUrl is the URL Swedbank Pay will provide to the third party for handling the redirect back to your site or app. When receiving the payer back on the paymentUrl either in an app or web page, it is important to restore the Seamless View to let the payment finalize the flow. For in-app it is important that you either implement the onPaymentCompleted event or let the Seamless View redirect to the completeUrl before intercepting the WebView. If you intercept the WebView when the payer’s device is redirected to the paymentUrl it can lead to issues. If you want to handle payment errors in your own code, you should also subscribe to other events provided by the Seamless View JavaScript and shut down the Seamless View if any of these events occur.

Events to subscribe to for full control over the payment flow are can be found in Seamless View Events.

When implementing the Seamless View flow into a WebView in your mobile app, you should use a custom scheme or Universal Link in the paymentUrl for handling automatic switching between your app and the payment app on the mobile device.

Callback

When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform a callback to inform the payee (merchant) about this update.

Providing a callbackUrl in POST requests is mandatory. Below we provide three example scenarios of why this is important:

  1. If the payer closes the payment window, the merchant will never know what happened to the payment if callbackUrl is not implemented.
  2. If the payer stops up in a payment app such as Vipps or Swish, the payer will never come back to the merchant. This means that the merchant won’t know what happened to the payment unless callbackUrl is implemented.
  3. If a payer experiences a network error or something else happens that prevents the payer from being redirected from Swedbank Pay back to the merchant website, the callbackUrl is what ensures that you receive the information about what happened with the payment.
  • When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform an asynchronous server-to-server callback to inform the payee (merchant) about this update.
  • It is important to know that the callback is asynchronous, and not real-time. As we can’t guarantee when you get the callback, there could be a delay between when the payer is returned back to the merchant and when the callback arrives. If the merchant chooses to wait for the callback, the payer might be left at the merchant’s page until the response comes.
  • Swedbank Pay will make an HTTP POST to the callbackUrl that was specified when the payee (merchant) created the payment.
  • When the callbackUrl receives such a callback, an HTTP GET request must be made on the payment or on the transaction. The retrieved payment or transaction resource will give you the necessary information about the recent change/update.
  • The callback will be retried if it fails. Below are the retry timings, in seconds from the initial transaction time:
    • 30 seconds
    • 60 seconds
    • 360 seconds
    • 432 seconds
    • 864 seconds
    • 1265 seconds
  • The callback is sent from the following IP address: 82.115.146.1
  • A callback should return a 200 OK response.

To understand the nature of the callback, the type of transaction, its status, etc., you need to perform a GET request on the received URI and inspect the response. The transaction type or any other information can not and should not be inferred from the URI. See URI usage for more information.

Payment Instrument Callback

1
2
3
4
5
6
7
8
9
10
{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 222222222
    },
    "transaction": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "number": 333333333
    }
}

When performing an HTTP GET request towards the URI found in the transaction.id field of the callback, the response is going to look something like the abbreviated example provided below.

The created authorization resource contains information about the authorization transaction made against a creditcard payment.

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

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "maskedPan": "123456xxxxxx1234",
        "expireDate": "mm/yyyy",
        "panToken": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "cardBrand": "Visa",
        "cardType": "Credit Card",
        "issuingBank": "UTL MAESTRO",
        "countryCode": "999",
        "acquirerTransactionType": "3DSECURE",
        "acquirerStan": "39736",
        "acquirerTerminalId": "39",
        "acquirerTransactionTime": "2017-08-29T13:42:18Z",
        "authenticationStatus": "Y",
        "itemDescriptions": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Authorization",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/creditcard/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-authorization",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Field Type Description  
payment string The relative URI and unique identifier of the payment resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
authorization string The current authorization transaction resource.  
└➔ id string The relative URI and unique identifier of the authorization resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
└➔ paymentToken string The payment token created for the card used in the authorization.  
└➔ maskedPan string The masked PAN number of the card.  
└➔ expireDate string The month and year of when the card expires.  
└➔ panToken string The token representing the specific PAN of the card.  
└➔ 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.  
└➔ countryCode string The country the card is issued in.  
└➔ acquirerTransactionType string 3DSECURE or SSL. Indicates the transaction type of the acquirer.  
└➔ acquirerStan string The System Trace Audit Number assigned by the acquirer to uniquely identify the transaction.  
└➔ acquirerTerminalId string The ID of the acquirer terminal.  
└➔ acquirerTransactionTime string The ISO-8601 date and time of the acquirer transaction.  
└➔ authenticationStatus string Y, A, U or N. Indicates the status of the authentication.  
└➔ itemDescriptions object The object representation of the itemDescriptions resource.  
└─➔ id string The relative URI and unique identifier of the itemDescriptions resource this authorization belongs to.. 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 this authorization belongs to.. 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 Indicates the state of the transaction, usually initialized, completed orfailed. If a partial authorization has been done and further transactionsare possible, the state will be awaitingActivity.  
└─➔ 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, where id should be used instead.  
└─➔ 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.  
└─➔ 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 ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.  
└─➔ 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.In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
└─➔ receiptReference string A unique reference for the transaction. This reference is used as an invoice/receipt number.  
└─➔ 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.  

The sequence diagram below shows the HTTP POST you will receive from Swedbank Pay, and the two GET requests that you make to get the updated status.

sequenceDiagram
    Participant Merchant
    Participant SwedbankPay as Swedbank Pay

    activate SwedbankPay
    SwedbankPay->>+Merchant: POST <callbackUrl>
    deactivate SwedbankPay
    note left of Merchant: Callback by Swedbank Pay
    Merchant-->>+SwedbankPay: HTTP response
    Merchant->>+SwedbankPay: GET creditcard payment
    deactivate Merchant
    note left of Merchant: First API request
    SwedbankPay-->>+Merchant: payment resource
    deactivate SwedbankPay

The implementation sequence for this scenario is a variant of the purchase sequence. The payer is not redirected to the Payments directly but will instead receive a payment link via mail/SMS. When the payer clicks on the link, a payment window opens.

Introduction

The Payment Link can be implemented for payment instruments listed below, using the Redirect platform and Swedbank Pay hosted payment page.

When the payer starts the purchase process in your merchant or webshop site, you need to make a POST request towards Swedbank Pay with your Purchase information. You receive a Payment Link (same as redirect URL) in response.

You have to distribute the Payment Link to the payer through your order system, using channels like e-mail or SMS.

info

When sending information in e-mail/SMS, it is strongly recommended that you add information about your terms and conditions, including purchase information and price. See recommendations in the next section.

When the payer clicks on the Payment Link, the Swedbank Pay payment page will open, letting him or her enter the payment details (varying depending on payment instrument) in a secure Swedbank Pay hosted environment.

When paying with credit card and if required, Swedbank Pay will handle 3-D Secure authentication.

After completion, Swedbank Pay will redirect the browser back to your merchant/webshop site.

If callbackURL is set the merchant system will receive a callback from Swedbank Pay, enabling you to make a GET request towards Swedbank Pay with the id of the payment received in the first step, which will return the purchase result.

E-mail And SMS Recommendations

When you as a merchant sends an e-mail or SMS to the payer about the Payment Link, it is recommended to include contextual information which helps him or her understand what will happen when clicking the Payment Link. We recommend that you include the following:

  • The name of the merchant/shop initiating the payment
  • An understandable product description, describing what kind of service the payer will pay for.
  • Some order-id (or similar) that exists in the merchant’s order system.
  • The price and currency.
  • Details about shipping method and expected delivery (if physical goods will be sent to the payer).
  • A link to a page with the merchant’s terms and conditions (such as return policy) and information about how the payer can contact the merchant.
  • Details informing that the payer accepts the Terms & Conditions when clicking on the Payment Link.

Receipt Recommendations

We recommend that you send an e-mail or SMS confirmation to the payer with a receipt when the payment has been fulfilled.

API Requests

The API requests depend on the payment instrument you are using when implementing the Payment Link scenario, see purchase flow. One-phase payment instruments will not implement capture, cancellation or reversal. The options you can choose from when creating a payment with key operation set to Purchase are listed below.

Screenshots

When clicking the payment link, the payer will be directed to a payment page similar to the examples below, where payment information can be entered.

screenshot of the redirect card payment page

Options

All valid options when posting a payment with operation Purchase, are described in each payment instrument’s respective API reference. Please see the general sequence diagrams for more information about payments in one-phase (e.g. Swish and credit card with autocapture) and two-phase (e.g. Card, MobilePay Online, Vipps).

Authorization

When using two-phase payment instruments you reserve the amount with an authorization, and you will have to specify that the intent of the purchase is Authorize. The amount will be reserved but not charged. You have to make a Capture or Cancel request later (i.e. when you are ready to ship the purchased products).

Capture

Capture can only be performed on a payment with a successfully authorized transaction. It is possible to do a part-capture where you only capture a smaller amount than the authorized amount. You can do more captures on the same payment up to the total authorization amount later.

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 card will be charged and you don’t need to do any more financial operations to this purchase.

Cancel

Cancel can only be done on an authorized transaction. If you cancel after doing a part-capture you will cancel the difference between the captured amount and the authorized amount.

Reversal

Reversal can only be done on a payment where there are some captured amount not yet reversed.

General

When implementing the Payment Link scenario, it is optional to set a callbackURL in the POST request. If callbackURL is set Swedbank Pay will send a request to this URL when the payer has completed the payment. See the Callback API description here.

Purchase flow

The sequence diagrams display the high level process of the purchase, from generating a Payment Link to receiving a Callback.

This in a generalized flow as well as a specific 3-D Secure enabled credit card scenario.

info

Please note that the the callback may come either before, after or in the same moment as the payer is redirected to the status page at the merchant site when the purchase is fulfilled. Don’t rely on the callback being timed at any specific moment.

When dealing with card payments, 3-D Secure authentication of the cardholder is an essential topic. There are three alternative outcomes of a 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 authentication mechanism that is decided by the issuing bank. Normally this will be done using BankID or Mobile BankID.
sequenceDiagram
    activate Payer
    Payer->>-MerchantOrderSystem: payer starts purchase
    activate MerchantOrderSystem
    MerchantOrderSystem->>-Merchant: start purchase process
    activate Merchant
    Merchant->>-SwedbankPay: POST [payment] (operation=PURCHASE)
    activate SwedbankPay
    note left of Merchant: First API request
    SwedbankPay-->>-Merchant: payment resource with payment URL
    activate Merchant
    Merchant-->>-MerchantOrderSystem: Payment URL sent to order system
    activate MerchantOrderSystem
    MerchantOrderSystem-->>-Payer: Distribute Payment URL through e-mail/SMS
    activate Payer
    note left of Payer: Payment Link in e-mail/SMS
    Payer->>-SwedbankPay: Open link and enter payment information
    activate SwedbankPay

    
        opt Card supports 3-D Secure
        SwedbankPay-->>-Payer: redirect to IssuingBank
        activate Payer
        Payer->>IssuingBank: 3-D Secure authentication process
        Payer->>-SwedbankPay: access authentication page
        activate SwedbankPay
        end
    

    SwedbankPay-->>-Payer: redirect to merchant site
    activate Payer
    note left of SwedbankPay: redirect back to merchant
    Payer->>-Merchant: access merchant page
    activate Merchant
    Merchant->>-SwedbankPay: GET [payment]
    activate SwedbankPay
    note left of Merchant: Second API request
    SwedbankPay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Payer: display purchase result

Options after posting a payment

  • If the payment enable a two-phase flow (Authorize), you will need to implement the Capture and Cancel requests.
  • It is possible to “abort” the validity of the Payment Link. See the Abort description here.
  • For reversals, you will need to implement the Reversal request.
  • When implementing the Payment Link scenario, it is optional to set a callbackURL in the POST request. If callbackURL is set Swedbank Pay will send a postback request to this URL when the payer has completed the payment. See the Callback API description here.

Transactions

A payment contains sub-resources in the form of transactions. Most operations performed on a payment ends up as a transaction resource. The different types of operations that alter the state of the payment by creating a transaction is described below.

The transactions resource will list the transactions (one or more) on a specific payment.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The transaction resource contains information about the transaction transaction made against a creditcard payment. You can return a specific transaction transaction by performing a GET request towards the specific transaction’s id.

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

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transactions": { 
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions",
        "transactionList": [{
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                "created": "2016-09-14T01:01:01.01Z",
                "updated": "2016-09-14T01:01:01.03Z",
                "type": "Transaction",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}
Field Type Required
payment string The relative URI and unique identifier of the payment resource this transactions belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
transactions object The current transactions resource.
└➔ id string The relative URI and unique identifier of the transactions resource this transactions belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ transactionList array The array of transaction transaction objects.
└➔ transactionList[] object The transaction transaction object described in the transaction resource below.
└─➔ id string The relative URI and unique identifier of the transaction resource this transactions belongs to.. 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 Indicates the state of the transaction, usually initialized, completed orfailed. If a partial transaction has been done and further transactionsare possible, the state will be awaitingActivity.
└─➔ 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, where id should be used instead.
└─➔ 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.
└─➔ 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 ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
└─➔ 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.In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
└─➔ 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.

Transaction

The transaction resource contains the generic details of a transaction on a specific payment.

When a transaction is created it will have one of three states:

  • Initialized - if there is some error where the source is undeterminable (network failure, etc), the transaction will remain Initialized. The corresponding state of the payment order will in this case be set to pending. No further transactions can be created.
  • Completed - if everything went ok the transaction will follow through to completion.
  • Failed - if the transaction has failed (i.e. a denial from the acquiring bank) it is possible to retry (i.e the payer tries using another card) up to a maximum amount of retries (in that case which the payment order gets the state failed as well).

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transaction": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "created": "2016-09-14T01:01:01.01Z",
        "updated": "2016-09-14T01:01:01.03Z",
        "type":  "Capture", 
        "state": "Initialized",
        "number": 1234567890,
        "amount": 1000,
        "vatAmount": 250,
        "description": "Test transaction",
        "payeeReference": "AH123456",
        "failedReason": "",
        "isOperational": true,
        "operations": []
    }
}

Transaction Problems

In the event that a transaction is failed, the transaction response will contain a problem property as seen in the example below. To view all the problems that can occur due to an unsuccesful transaction, head over to the problems section.

The created transaction resource contains information about the transaction transaction made against a creditcard payment.

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

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transaction": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "maskedPan": "123456xxxxxx1234",
        "expireDate": "mm/yyyy",
        "panToken": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "cardBrand": "Visa",
        "cardType": "Credit Card",
        "issuingBank": "UTL MAESTRO",
        "countryCode": "999",
        "acquirerTransactionType": "3DSECURE",
        "acquirerStan": "39736",
        "acquirerTerminalId": "39",
        "acquirerTransactionTime": "2017-08-29T13:42:18Z",
        "authenticationStatus": "Y",
        "itemDescriptions": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Transaction",
            "state": "Failed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/creditcard/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
        }
    }
}

Field Type Description  
payment string The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
transaction string The current transaction transaction resource.  
└➔ id string The relative URI and unique identifier of the transaction resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
└➔ paymentToken string The payment token created for the card used in the authorization.  
└➔ maskedPan string The masked PAN number of the card.  
└➔ expireDate string The month and year of when the card expires.  
└➔ panToken string The token representing the specific PAN of the card.  
└➔ 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.  
└➔ countryCode string The country the card is issued in.  
└➔ acquirerTransactionType string 3DSECURE or SSL. Indicates the transaction type of the acquirer.  
└➔ acquirerStan string The System Trace Audit Number assigned by the acquirer to uniquely identify the transaction.  
└➔ acquirerTerminalId string The ID of the acquirer terminal.  
└➔ acquirerTransactionTime string The ISO-8601 date and time of the acquirer transaction.  
└➔ authenticationStatus string Y, A, U or N. Indicates the status of the authentication.  
└➔ itemDescriptions object The object representation of the itemDescriptions resource.  
└─➔ id string The relative URI and unique identifier of the itemDescriptions resource this transaction belongs to.. 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 this transaction belongs to.. 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 Indicates the state of the transaction, usually initialized, completed orfailed. If a partial transaction has been done and further transactionsare possible, the state will be awaitingActivity.  
└─➔ 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, where id should be used instead.  
└─➔ 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.  
└─➔ 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 ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.  
└─➔ 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.In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
└─➔ receiptReference string A unique reference for the transaction. This reference is used as an invoice/receipt number.  
└─➔ 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.  

Card authorization transaction

The authorization resource contains information about an authorization transaction made towards a payment. To create a new authorization transaction, perform a POST towards the URI obtained from the payment.authorization.id from the payment resource below. The example is abbreviated for brevity.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "authorizations": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations"
        },
    }
}

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"
    }
}

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
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
  "authorization": {
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
    "paymentToken" : "5a17c24e-d459-4567-bbad-aa0f17a76119",
    "recurrenceToken" : "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "maskedPan" : "123456xxxxxx1234",
    "expiryDate" : "mm/yyyy",
    "panToken" : "ec2a9b09-601a-42ae-8e33-a5737e1cf177"
    "cardBrand": "Visa",
    "cardType": "Credit",
    "issuingBank": "UTL MAESTRO",
    "countryCode": "999",
    "acquirerTransactionType": "3DSECURE",
    "issuerAuthorizationApprovalCode": "397136",
    "acquirerStan": "39736",
    "acquirerTerminalId": "39",
    "acquirerTransactionTime": "2017-08-29T13:42:18Z",
    "authenticationStatus": "Y",
    "nonPaymentToken" : "",
    "externalNonPaymentToken" : "",
    "transaction": {
      "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
      "created": "2016-09-14T01:01:01.01Z",
      "updated": "2016-09-14T01:01:01.03Z",
      "type": "Authorization",
      "state": "Initialized",
      "number": 1234567890,
      "amount": 1000,
      "vatAmount": 250,
      "description": "Test transaction",
      "payeeReference": "AH123456",
      "failedReason": "ExternalResponseError",
      "failedActivityName": "Authorize",
      "failedErrorCode": "REJECTED_BY_ACQUIRER",
      "failedErrorDescription": "General decline, response-code: 05",
      "isOperational": "TRUE",
      "activities": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/activities" },
      "operations": [
        {
          "href": "https://api.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
          "rel": "edit-authorization",
          "method": "PATCH"
        }
      ]
    }
  }
}
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 card holder, usually printed on the face of the card.
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 this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ nonPaymentToken string Result of our own tokenization of the card used. Activated in POS on merchant or merchant group.
└➔ externalNonPaymentToken string Result of external tokenization. This value varies depending on cards, acquirer, customer, etc. For ICA cards, the token comes in response from Swedbank. For Mass Transit(SL) it is populated with PAR if it comes in response from the redeemer (Visa). If not, our own token (Mastercard / Amex).
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URI and unique identifier of the transaction resource this transaction belongs to.. 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.

PayeeInfo

The payeeinfo resource contains information about the payee (i.e. a merchant, a corporation etc) related to a specific payment.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "payeeInfo": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo",
        "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
        "payeeReference": "EN1234",
        "payeeName": "TestMerchant1",
        "productCategory": "EF1234",
        "orderReference": "or-123456"
    }
}
Field Type Description
payment string The relative URI and unique identifier of the payment resource this payeeInfo belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ id string The relative URI and unique identifier of the payeeInfo resource this payeeInfo belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ payeeId string This is the unique id that identifies this payee (like merchant) set by Swedbank Pay
└➔ 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 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. You therefore need to ensure that the value given here is valid in the settlement.
└➔ orderReference string(50) The order reference should reflect the order reference found in the merchant’s systems.

Payee Reference

The payeeReference given when creating transactions and payments has some specific processing rules depending on specifications in the contract.

  • It must be unique for every operation, used to ensure exactly-once delivery of a transactional operation from the merchant system.
  • Its length and content validation is dependent on whether the transaction.number or the payeeReference is sent to the acquirer.
    1. If you select Option A in the settlement process (Swedbank Pay will handle the settlement), Swedbank Pay will send the transaction.number to the acquirer and the payeeReference must be in the format of characters A-Za-z0-9 (including -) and string(30).
    2. If you select Option B in the settlement process (you will handle the settlement yourself), Swedbank Pay will send the payeeReference to the acquirer and it will be limited to the format of string(12) and all characters must be digits.

Prices

The prices resource lists the prices related to a specific payment.

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "prices": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices",
        "priceList": [
            {
                "type": "VISA",
                "amount": 2350,
                "vatAmount": 0
            },
            {
                "type": "MasterCard",
                "amount": 2350,
                "vatAmount": 0
            }
        ]
    }
}
Field Type Description
payment string The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
prices object The prices resource.
└➔ id string The relative URI and unique identifier of the prices resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ priceList array The array of price objects. Note: Even if you specifiy CreditCard in the input message the system will return all your configured card brands instead when you expan the priceList.
└─➔ type string The type of the price object.
└─➔ 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.
└─➔ 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 ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.

Prices Object Types

Each payment instrument have one or more prices object types. This is most relevant when using card based payments as each type correspond to a card brand or bank respectively.

Card Payments

The generic type CreditCard enables all card brands, supported by merchant contract.

Type Description
Visa Visa
MasterCard MasterCard
Amex American Express
Dankort Dankort can only be used with DKK currency
Diners Diners Club
Finax Finax
Jcb JCB
IkanoFinansDK Ikano Finans Denmark
Maestro MasterCard Maestro

Transaction on file

warning

This feature is only available for merchants who have a specific agreement with Swedbank Pay.

In rare use cases it can be useful for Merchants that operate with payment tokens (recurring, one-click, etc) to be able to submit subsequent transactions via file transfer rather than using the regular operations in our API. Reasons for this could be that the subsequent transactions are triggered from an older system that do not support real-time API communication. For those use cases Swedbank Pay offer a service called Transaction on File. As this is a somewhat unmodern way to complete transactions, we strongly recommend to consider usage of regular API operations and only use transactions on file where it is the only option.

For further information on this service, please contact our integration support.

Screenshots

You will redirect the payer to Swedbank Pay hosted pages to collect the credit card information.

screenshot of the swedish card verification page

API Requests

The API requests are displayed in the flow below. The token generated will be returned in parameter ‘transactionOnFileToken’. For more information regarding the flow, see Verify.

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
POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Verify",
        "currency": "NOK",
        "description": "Create TransactionOnFileToken",
        "payerReference": "AB1234",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "generateTransactionOnFileToken": true,
        "urls": {
            "hostUrls": ["https://example.com", "https://example.net"],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.html"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        }
    }
}

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

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "operation": "Verify",
        "state": "Ready",
        "currency": "NOK",
        "amount": 0,
        "description": "Test Verification",
        "payerReference": "AB1234",
        "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "nb-NO",
        "transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "verifications": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications" },
        "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": [
        {
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH",
            "contentType": "application/json"
        },
        {
            "href": "https://ecom.externalintegration.payex.com/creditcard/payments/verification/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "redirect-verification",
            "method": "GET",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "view-verification",
            "contentType": "application/javascript"
        },
        {
            "method": "POST",
            "href": "https://ecom.externalintegration.payex.com/psp/creditcard/confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications",
            "rel": "direct-verification",
            "contentType": "application/json"
        }
    ]
}

3-D Secure 2

When dealing with card payments, 3-D Secure authentication of the cardholder is an essential topic. 3-D Secure 2 is an improved version of the old protocol, now allowing frictionless payments where transactions can be completed without input from the cardholder. Therefore, there are certain fields that should be included when implementing 3-D Secure 2. These are listed below and can be seen in the abbreviated request example 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
POST /psp/creditcard/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SEK",
        "description": "Test Purchase",
        "urls": {
            "hostUrls": ["https://example.com"]
        }, 
        "cardholder": {
            "firstName": "Olivia",
            "lastName": "Nyhuus",
            "email": "olivia.nyhuus@payex.com",
            "msisdn": "+4798765432",
            "homePhoneNumber": "+4787654321",
            "workPhoneNumber": "+4776543210",
            "shippingAddress": {
                "addressee": "Olivia 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"
        }
    }
}
Field Type Description
payment object The payment object.
└➔ cardholder object Cardholder object that can hold information about a buyer (private or company). The information added increases the chance for frictionless 3-D Secure 2 flow.
└➔ firstname string Payer’s first name.
└➔ lastname string Payer’s last name.
└➔ email string Payer’s registered email address. The field is related to 3-D Secure 2.
└➔ msisdn string Payer’s registered mobile phone number. The field is related to 3-D Secure 2.
└➔ homePhoneNumber string Payer’s registered home phone number. The field is related to 3-D Secure 2.
└➔ workPhoneNumber string Payer’s registered work phone number. The field is related to 3-D Secure 2.
└─➔ shippingAddress object The shipping address object related to the payer. The field is related to 3-D Secure 2.
└─➔ addresse string The name of the addressee – the receiver of the shipped goods.
└─➔ coAddress string Payer’ s c/o address, if applicable.
└─➔ streetAddress string Payer’s street address
└─➔ zipCode string Payer’s zip code
└─➔ city string Payer’s city of residence
└─➔ countryCode string Country Code for country of residence.
└➔ riskIndicator object This 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 ndicates 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).

Co-badge Card Choice for Dankort

Due to new EU regulations from 2016-06-09 regarding cards that have more than one payment application, we have developed support for the end users of Dankort to be able to choose their preferred payment application on the Swedbank Pay payment page. If you are a Dankort user, read more about this feature at Dankort.

As a merchant you can set a priority selection of payment application by contacting Swedbank Pay Support. The payer will always be able to override this priority selection on the payment page.

If you want more information about Co-badge Card Choice for Dankort users, please contact Swedbank Pay Support. The example below shows the payment window where the payer can choose between Dankort or Visa before completing the payment.

Co-badge Dankort cards with option to choose between Dankort and Visa before paying

Metadata

Metadata can be used to store data associated to a payment that can be retrieved later by performing a GET on the payment. Swedbank Pay does not use or process metadata, it is only stored on the payment so it can be retrieved later alongside the payment. An example where metadata might be useful is when several internal systems are involved in the payment process and the payment creation is done in one system and post-purchases take place in another. In order to transmit data between these two internal systems, the data can be stored in metadata on the payment so the internal systems do not need to communicate with each other directly. The usage of metadata field is shown in the abbreviated Purchase 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
POST /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
  "payment": {
    "operation": "Purchase",
    "intent":  "Authorization", 
    "currency": "SEK",
    "description": "Test Purchase",
    "payerReference": "AB1234",
    "userAgent": "Mozilla/5.0...",
    "language": "sv-SE",
    "urls": {
      "hostUrls": ["https://example.com"],
      "completeUrl": "https://example.com/payment-completed"
    },
    "payeeInfo": {
      "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
      "payeeReference": "CD1234",
    },
    "metadata": {
        "key1": "value1",
        "key2": 2,
        "key3": 3.1,
        "key4": false
    },
    "prefillInfo": {
        "msisdn": "+4798765432"
    }
  }
}
Parameter Type
metadata string, boolean, integer,decimal

Request

1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
HTTP/1.1 200 OK
Content-Type: application/json

{
  "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
  "metadata": {
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata",
    "key1": "value1",
    "key2": 2,
    "key3": 3.1,
    "key4": false
 }
}

Settlement and Reconciliation

Reconciliation is an important step in an economic transaction. When a payment is reconciled, captured amounts for the payment are matched against the corresponding settlement.

The information needed to reconcile captured funds - the balance report and transactions list - are available for all merchants using Swedbank Pay.

  • By default, the settlement files will be sent to you by via e-mail.
  • We also have the option to send it via SFTP as well, if this is something you would like then you need to state this to your sales representative, so they can inform the setup team when the time is ready.
  • The settlement frequency is defined in the agreement and you will receive it (per default) once a month, or once a week.
  • You do not need to subscribe, the files will be delivered by default.

Contact omni.client@swedbankpay.se for further inquiries regarding this.

Settlement

There are two main alternatives for settlement - either we handle the settlement process for you, or you handle the process yourself :

Swedbank Pay handles the settlement process

Swedbank Pay handles the settlement process on your behalf, (called “Redovisningsservice”). Swedbank Pay transfers the net amount to you directly.

Swedbank Pay Checkout

When choosing Swedbank Pay Checkout we always handle the settlement process for you, gathering all your eCommerce payments in one place. Straighforward and time efficient.

You handle the settlement process yourself

If you will handle the settlement yourself, then Swedbank Pay will send you an invoice with the relevant fees, in addition to the report and transactions lists. Your acquirer will transfer settled funds to you.

Balance Report

The Balance Report (a .pdf file) specifies the total sales for a specific period, including fees and VAT. The report contains three parts: a payment summary and specifications for sales and for fees.

Payment Summary

Provides a summary of the Amount sold, Fees and VAT. If Swedbank Pay handles the settlement process, the Transferedamount - shown in the balance report summary is equivalent to the disbursement on the bank statement (the remaining total amount after fees).

Sales specification

Provides a specification over sales for the given period. The sales total is specified per payment area (CreditCard, Invoice) and underlying payment instruments. Each sales row specify Quantity, Sum sales and Amount to pay out, the last one is only eligble if Swedbank Pay handles the Settlement process.

Fees specification

Provides a specification over fees for the given period. The fees total is specified per payment area (CreditCard, Invoice) and underlying payment instruments. Each fees row specify Quantity (sales), Amount (sales), Unit price, Provision and fee Amount. If you handle the settlement process yourselves you will receive a separat invoice for fees.

Transactions List

The Transaction List (provided in .xlsx and .xml formats) specifies all transactions for a specific period, including a summary of transactions grouped by payment instrument. Both formats contain the same information, but the xml file is meant for computer processing while the excel workbook is meant for human interaction.

The first row contains the name of the Swedbank Pay company (e.g. Swedbank Pay Solutions AB) that the merchant has the contract with, and the balance report number. The header fields contain a summary of the transactions displayed in the body.

Header fields

Field Type Description
Prefix String The Prefix used for transactions, only eligible if merchant uses prefix.
Currency ISO 4217 Settlement currency (e.g. SEK, NOK, EUR).
ServiceType String The service type of the service used (e.g. Creditcard).
Service String The service used (e.g. Creditcard).
NoOfDebet Decimal Total number of debit transactions for the given service.
NoOfCredit Decimal Total number of credit transactions for the given service.
Amount Decimal Total amount for the given service (e.g 100.00).
FromDate ISO 8601 The earlistest transaction date, YYYY-MM-DD.
ToDate ISO 8601 The latest transaction date, YYYY-MM-DD.

Body fields

Field Type Description
Swedbank Pay Batch Number Decimal A batch number common to all types of transactions processed by Swedbank Pay.
Transaction Number Decimal A unique identifier of the transaction, can be traced in Swedbank Pay Admin user interface.
Order id String A unique identifier of the order, as sent from the merchant to Swedbank Pay. Transactions that are related to the same order are associated with this ID.
Date Created ISO 8601 Transaction capture date/time. YYYY-MM-DD hh:mm:ss.
Date Modified ISO 8601 Transaction settle date/time. YYYY-MM-DD hh:mm:ss.
Provider String The service provider (e.g. Babs, Swedbank).
Type String The service type of the related transaction (e.g. Creditcard).
Amount Decimal Total amount of the related transaction (e.g 100.00).
Currency ISO 4217 Settlement currency (e.g. SEK, NOK, EUR).
Product Number String A product number, as sent by merchant to Swedbank Pay.
Description String A textual description of the transaction, as sent by merchant to Swedbank Pay.
VAT Amount Decimal VAT Amount for the given transaction (e.g 100.00).
VAT Percentage Decimal VAT Percentage for the given transaction.
Credit Card Batch Number Decimal The reference number from the credit card processor.
Reference Decimal The transaction reference from processor.
Swedbank Pay Account Number Decimal The Account number given, shown in Swedbank Pay admin.
Referenced Transaction Number Decimal Transaction number for the Authoriation transaction for a two-stage transaction or the number of the debit transaction if it is a credit transaction.
Sales Channel String The channel through which the transaction was sent to Swedbank Pay (e.g Transaction via eCommerce APIs).
Brand String If eligible, Branding information as sent by merchant to Swedbank Pay.
Point Of Sale String If eligible, POS information as sent by merchant to Swedbank Pay.

Reconciliation

To do the reconciliation, you need to match the information in your system against the information provided by Swedbank Pay in the balance report and transaction list. Below is a sequence diagram detailing the interaction.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

    activate Merchant
    activate SwedbankPay
    Merchant-->>SwedbankPay: Online payment transactions
    deactivate Merchant

    deactivate SwedbankPay

    activate Merchant

    SwedbankPay->>Merchant: Balance Report (PDF-file)
    note left of Merchant: files are sent by e-mail or file transfer
    SwedbankPay->>Merchant: Transaction list (XLSX-file)
    SwedbankPay->>Merchant: Transaction list (XML-file)
    deactivate Merchant

There are two ways for you to match the information from your system with the information given in the reconciliation files from Swedbank Pay:

  1. You can use information generated by your system (you will have to set a unique payeeReference when you make the transaction), or
  2. You can use the transaction number generated by Swedbank Pay (this is called transaction number and is returned from Swedbank Pay after you have created the transaction).

A credit card transaction is made when you either make a capture or a reversal. In the input data for making a capture, you will set the payeeReference. The unique value of this field is the same as the field called OrderID in the reconciliation file.

1
2
3
4
5
6
7
8
{
    "transaction": {
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Reversal",
        "payeeReference": "ABC123"
    }
}

When you receive the response from Swedbank Pay, the response will include transaction.number. This is the same as the field called TransactionNo in the reconciliation file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Capture",
            "state": "Initialized",
            "number": 1234567890,
            "amount": 1500,
            "vatAmount": 250,
            "description": "Test Capture",
            "payeeReference": "ABC123",
            "failedReason": "",
            "isOperational": false,
            "operations": []
        }
    }
}
  • payeeReference sent to Swedbank Pay is equal to OrderId in the reconciliation file.
  • capture.transaction.number returned from Swedbank Pay is equal to TransactionNo in reconciliation file.

Below you will see the API mapping tables to the fields in the settlement report for Capture and Reversal.

Capture

API XLSX XML  
  Swedbank Pay Batch Number SwedbankbatchNo  
transaction.number Transaction Number TransactionNo  
transaction.payeeReference Order id OrderId  
transaction.created Date Created DateCreated  
  Date Modified DateModified  
  Provider Provider  
  Type Type  
transaction.amount Amount Amount  
  Currency Currency  
  Product Number MerchantProductNo  
transaction.description Description Description  
transaction.vatAmount VAT Amount VATAmount  
  VAT Percentage VatoPercentage  
  Credit Card Batch Number CreditCardBatchNo  
transaction.number if DirectDebit Direct Debit Bank Reference DirectDebitbankRef  
transaction.number if DirectDebit Reference Reference  
  Swedbank Account Number SwedbankAccountNo  
transaction.number if reversed later Referenced Transaction Number ReferencedTransaction  
  Sales Channel SalesChannel  
  Brand    
  Point Of Sale    

Reversal

API XLSX XML  
  Swedbank Pay Batch Number SwedbankbatchNo  
transaction.number Transaction Number TransactionNo  
transaction.payeeReference Order id OrderId  
transaction.created Date Created DateCreated  
  Date Modified DateModified  
  Provider Provider  
  Type Type  
transaction.amount Amount Amount  
  Currency Currency  
  Product Number MerchantProductNo  
transaction.description Description Description  
transaction.vatAmount VAT Amount VATAmount  
  VAT Percentage VatoPercentage  
  Credit Card Batch Number CreditCardBatchNo  
transaction.number if DirectDebit Direct Debit Bank Reference DirectDebitbankRef  
transaction.number if DirectDebit Reference Reference  
  Swedbank Account Number SwedbankAccountNo  
  Referenced Transaction Number ReferencedTransaction  
  Sales Channel SalesChannel  
  Brand    
  Point Of Sale    

Samples

The content of the files depends on the type of agreement you have made with Swedbank Pay. For some payment instruments, only option A is available, while for other payment instruments, only option B is available. The sample files can be downloaded below.

Option A: Swedbank Pay handles the settlement process

Option B: You will handle the settlement process yourself

Split Settlement

The prefix split is the easy way of doing settlements for companies with multiple sub merchants. With only a few easy steps, you can make the settlement process more efficient with regards to invoicing, payouts and setup for both your sub merchants and yourself.

In short, it is a settlement feature where a company with a website or an app can attach specific prefix numbers to sub merchants selling their goods or services through the company. The prefix number is used to match the transactions and the merchant, so the settlement is automatically split between the sub merchants. If you run a site selling tickets to concerts, theatres, sporting events etc., each venue gets its own prefix number. If you run a funeral home, the sub merchants can be everything from flower delivery to charities.

What we need from you as a company

  • Send us a KYC form for each sub merchant you want to include. We will also do a KYC check on your sub merchants, providing extra security for you.
  • Give every sub merchant who sells goods/services at your website or in your app a unique prefix number. This needs to be included in the KYC form you send to us. We recommend using the same customer number they have in your system.
  • Attach the prefix number to all the goods/services the sub merchant sells through your website or app, so the goods/services can be matched to the correct merchant in our back office system.
  • A partner agreement is needed for the automatic deduction of revenue cuts and fees.

How it works

  1. We set up the sub merchant prefix in our systems.
  2. The prefix number is added in the subsite field in the API call when you create the payment for the goods or service.
  3. The customer selects payment instrument and completes the payment.
  4. The payment goes into the client funds account.
  5. Swedbank Pay matches the transaction and the merchant using the prefix number.
  6. The settlement is split and connected to the correct merchant.
  7. Revenue cuts for the super merchant and fees from Swedbank Pay are deducted automatically.
  8. Payout to the sub merchant is done.

The upsides

  • Since the sub merchants are connected to Swedbank Pay through the super merchant instead of having separate setups, this means that you:
  • Only need one agreement for credit card, Vipps, Swish, MobilePay Online, invoice and payment gateway.
  • Only need one acquiring agreement.
  • Only need one Vipps/Swish certificate.
  • Can add more payment instruments easily, as it only has to be done once.
  • Can set up new sub merchants quickly, as the only thing needed is a KYC form and a prefix number. This shortens the setup time for both you and us to a matter of hours.
  • The automatic settlement split and deduction of fees and revenue cuts minimizes the work for your accounting department, as you do not have to invoice your sub merchants.
  • The prefix split is available with all the payment instruments we offer on our eCom platform.

Good to know

With regards to admin functions, we offer a full integration towards our admin system. This way, you do not have to log in to Swedbank Pay Admin to perform these operations.

Captures and cancels

Captures and cancels are done by the super merchant the same way as any other normal flow.

Reversals

In cases where you need to do reversals, this will be performed by the super merchant. The reversal amount will be charged from the sub merchants prefix. If the sub merchants balance is 0 (zero), the super merchant will be invoiced. The super merchant will in turn have to invoice this amount to the sub merchant.

Problems

When performing operations against a resource in the Swedbank Pay API Platform, it will respond with a problem message that contain details of the error type if the request could not be successfully performed. Regardless of why the error occurred, the problem message will follow the same structure as specified in the Problem Details for HTTP APIs (RFC 7807) specification.

We generally use the problem message type and status code to identify the nature of the problem. The problems array contains objects with name and description that will often help narrow down the specifics of the problem, usually to the field in the request that was missing or contained invalid data.

The structure of a problem message will look like this:

Problem Example

1
2
3
4
5
6
7
8
9
10
11
12
{
    "type": "https://api.payex.com/psp/errordetail/<resource>/inputerror",
    "title": "There was an input error",
    "detail": "Please correct the errors and retry the request",
    "instance": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
    "status": 400,
    "action": "RetryNewData",
    "problems": [{
        "name": "CreditCardParameters.Issuer",
        "description": "minimum one issuer must be enabled"
    }]
}
Field Type Description
type string The URI that identifies the error type. This is the only field usable for programmatic identification of the type of error! When dereferenced, it might lead you to a human readable description of the error and how it can be recovered from.
title string The title contains a human readable description of the error.
detail string A detailed, human readable description of the error and how you can recover from it.
instance string The identifier of the error instance. This might be of use to Swedbank Pay support personnel in order to find the exact error and the context it occurred in.
status integer The HTTP status code that the problem was served with.
action string The action indicates how the error can be recovered from.
problems array The array of problem detail objects.
└➔ name string The name of the field, header, object, entity or likewise that was erroneous.
└➔ description string The human readable description of what was wrong with the field, header, object, entity or likewise identified by name.

Common Problems

All common problem types will have a URI in the format https://api.payex.com/psp/errordetail/<error-type>. The URI is an identifier that you can hard-code and implement logic around. It is currently not not possible to dereference this URI, although that might be possible in the future.

Type Status Description
inputerror 400 The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax, size to large, invalid request).
forbidden 403 The request was valid, but the server is refusing the action. The necessary permissions to access the resource might be lacking.
notfound 404 The requested resource could not be found, but may be available in the future. Subsequent requests are permissible.
systemerror 500 A generic error message.
configurationerror 500 A error relating to configuration issues.

Card Problems

There are a few problems specific to the creditcard resource that you may want to guard against in your integrations. All credit card problem types will have the following URI structure:

https://api.payex.com/psp/errordetail/creditcard/<error-type>

Contractual Problem Types

Type Status Description
cardbranddisabled 403 The card brand is disabled.
accountholdertyperejected 403 The account holder type is rejected.
cardtyperejected 403 The card type is rejected.
3dsecurerequired 403 The transaction was rejected by 3-D Secure.
authenticationstatusrejected 403 The authentication status was rejected.
frauddetected 403 The transaction was fraudulent.
3dsecuredeclined 403 3-D Secure declined the transaction.
velocitycheck 429 Indicates that the limit for how many times a card or different cards can be used for attempting a purchase has been reached.

Acquirer and 3-D Secure Problem Types

Type Status Description
3dsecureerror 400 3D Secure not working, try again some time later
cardblacklisted 400 Card blacklisted, the payer needs to contact their Card-issuing bank
paymenttokenerror 403 There was an error with the payment token.
carddeclined 403 The card was declined.
acquirererror 403 The acquirer responded with a generic error.
acquirercardblacklisted 403 Card blacklisted, the payer needs to contact their Card-issuing bank
acquirercardexpired 403 Wrong expire date or Card has expired and payer needs to contact their Card-issuing bank
acquirercardstolen 403 Card blacklisted, the payer needs to contact their Card-issuing bank
acquirerinsufficientfunds 403 Card does not have sufficient funds, the payer needs to contact their Card-issuing bank.
acquirerinvalidamount 403 Amount not valid by aquirer, contact support.ecom@payex.com
acquirerpossiblefraud 403 Transaction declined due to possible fraud, the payer needs to contact their Card-issuing bank.
3dsecureusercanceled 403 Transaction was Cancelled during 3DSecure verification
3dsecuredeclined 403 Transaction was declined during 3DSecure verification
frauddetected 403 Fraud detected, the payer needs to contact their Card-issuing bank.
badrequest 500 Bad request, try again after some time
internalservererror 500 Server error, try again after some time
3dsecureacquirergatewayerror 502 Problems reaching 3DSecure verification, try again after some time.
badgateway 502 Problems reaching the gateway, try again after some time
acquirergatewayerror 502 Problems reaching acquirers gateway, try again after some time
acquirergatewaytimeout 504 Problems reaching acquirers gateway, try again after some time

Seamless View Events

During operation in the Seamless View, several events can occur. They are described below.

info

Event Overrides

Adding an event handler to one of the following events overrides the default event handler, meaning your custom event handler will have to do what the default event handler did. If you don’t, the behaviour of the event is going to be undefined. Just adding an event handler for logging purposes is therefore not possible, the event handler will have to perform some functionality similar to the event handler you are overriding.

onPaymentPending

This events triggers when a payment enters a paying state ( Sale, Authorize, Canceletc). The onPaymentPending event will be followed by either onPaymentCompleted, onPaymentFailed or onPaymentTransactionFailed based on the result of the payment. Read more about these events below.

onPaymentPending event object

1
2
3
{
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1"
}
Field Type Description
id string The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.

onPaymentCompleted

This event triggers when a payment has completed successfully. The onPaymentCompleted event is raised with the following event argument object:

onPaymentCompleted event object

1
2
3
4
{
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "redirectUrl": "https://example.com/complete"
}
Field Type Description
id string The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
redirectUrl string The URI the user will be redirect to after a completed payment.

onPaymentCanceled

This event triggers when the user cancels the payment. The onPaymentCanceled event is raised with the following event argument object:

onPaymentCanceled event object

1
2
3
4
{
    "id": "/psp/creditcardpayments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "redirectUrl": "https://example.com/canceled"
}
Field Type Description
id string The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
redirectUrl string The URI the user will be redirect to after a canceled payment.

onPaymentFailed

This event triggers when a payment has failed, disabling further attempts to perform a payment. The onPaymentFailed event is raised with the following event argument object:

onPaymentFailed event object

1
2
3
4
{
    "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "redirectUrl": "https://example.com/failed"
}
Field Type Description
id string The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
redirectUrl string The URI the user will be redirect to after a failed payment.

onPaymentTermsOfService

This event triggers when the user clicks on the “Display terms and conditions” link. The onPaymentTermsOfService event is raised with the following event argument object:

onPaymentTermsOfService event object

1
2
3
4
{
    "origin": "owner",
    "openUrl": "https://example.com/terms-of-service"
}
Field Type Description
origin string owner, merchant. The value is always merchant unless Swedbank Pay hosts the view.
openUrl string The URI containing Terms of Service and conditions.

onError

This event triggers during terminal errors or if the configuration fails validation. The onError event will be raised with the following event argument object:

onError event object

1
2
3
4
5
{
    "origin": "creditcard",
    "messageId": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
    "details": "Descriptive text of the error"
}
Field Type Description
origin string creditcard, identifies the system that originated the error.
messageId string A unique identifier for the message.
details string A human readable and descriptive text of the error.