After the payment is confirmed, the payer will be redirected from the Swish app to the completeUrl set in the create payment request. You need to retrieve payment status with GET Sales transaction before presenting a confirmation page to the payer.

Options After Posting A Payment

  • If CallbackURL is set: Whenever changes to the payment occur a Callback request will be posted to the callbackUrl, which was generated when the payment was created.
  • You can create a reversal transactions by implementing the Reversal request. You can also access and reverse a payment through your merchant pages in the Merchant portal.

Swish Transactions

All Swish transactions are described below. Please note that Swish does not support Merchant Initiated Transactions for the time being.

List Sales Transactions

The sales resource lists the sales transactions (one or more) on a specific payment.

Request

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

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

Transaction List Response

Response

1
2
HTTP/1.1 200 OK
Content-Type: application/json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "sales": { 
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
        "saleList": [{
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "swishPaymentReference": "8D0A30A7804E40479F88FFBA26111F04",
            "swishStatus": "PAID",
            "transaction": {
                "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                "created": "2016-09-14T01:01:01.01Z",
                "updated": "2016-09-14T01:01:01.03Z",
                "type": "Sale",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}
Field Type Required
paymentOrder string The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
id string The relative URL and unique identifier of the sales resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
{{ transaction }}List array The array of sale transaction objects.
{{ transaction }}List[] object The sale transaction object described in the sale resource below.
id string The relative URL and unique identifier of the transaction resource . Please read about URL Usage to understand how this and other URLs 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 or failed. If a partial sale has been done and further transactions are possible, the state will be awaitingActivity.
number integer 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 transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
description string A 40 character length textual description of the purchase.
payeeReference string A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. 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.

Create Sales Transactions

In browser solutions the payer’s msisdn (mobile number) is required. This is managed either by sending a POST request as seen below, or by redirecting the payer to the hosted payment page. The msisdn is only required for browser solutions. With in-app solutions, the payer uses the device that hosts the Swish app to manage the purchase, making msisdn optional.

Browser Request

Browser Request

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

{
    "transaction": {
        "msisdn": "+46739000001"
    }
}

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

{
    "payment": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "sale": {
        "date": "23.10.2017 08:39:37 +00:00",
        "paymentRequestToken": "LhXrK84MSpWU2RO09f8kUP-FHiBo-1pB",
        "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2017-10-23T08:39:35.6478733Z",
            "updated": "2017-10-23T08:39:37.3788733Z",
            "type": "Sale",
            "state": "AwaitingActivity",
            "number": 992309,
            "amount": 1500,
            "vatAmount": 0,
            "description": "Test Purchase",
            "payeeReference": "Postman1508747933",
            "isOperational": true,
            "operations": []
        }
    }
}

In-app Request

In-app Request

1
2
3
4
5
6
7
8
9
POST /psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
    }
}

In-app Response

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

{
    "payment": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "sale": {
        "date": "23.10.2017 08:39:37 +00:00",
        "paymentRequestToken": "LhXrK84MSpWU2RO09f8kUP-FHiBo-1pB",
        "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2017-10-23T08:39:35.6478733Z",
            "updated": "2017-10-23T08:39:37.3788733Z",
            "type": "Sale",
            "state": "AwaitingActivity",
            "number": 992309,
            "amount": 1500,
            "vatAmount": 0,
            "description": "Test Purchase",
            "payeeReference": "Postman1508747933",
            "isOperational": true,
            "operations": [
                {
                    "href": "swish://paymentrequest?token=<swishtoken>&callbackurl=<completeUrl>",
                    "method": "GET",
                    "rel": "redirect-app-swish"
                }
            ]
        }
    }
}

The operation redirect-app-swish is only returned when using in-app flows.

The payment now contains a sale transaction with the status (state) AwaitingActivity, meaning we are awaiting a response from Swish. When the payer confirms the payment a callback request will follow from Swedbank Pay.

Reversals

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

Reversal Sequence Diagram

A reversal transcation need to match the Payee reference of a completed sales transaction.

sequenceDiagram
  activate Merchant
  Merchant->>- SwedbankPay: POST <Swish reversal>
  activate  SwedbankPay
  SwedbankPay-->>-Merchant: transaction resource

Create Reversal Transaction

A reversal transaction can be created after a completed authorization by performing a request to the create-reversal operation. A callback request will follow from Swedbank Pay.

Reversal Request

Request

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

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 0,
        "description" : "Test Reversal",
        "payeeReference": "ABC123"
    }
}
Required Field Type Description
check transaction object The transaction object, containing information about this reversal.
check amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check description string A textual description of this reversal.
check payeeReference string A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits.

Reversal Response

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

Capture Response

Response

1
2
3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0
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
{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversal": {
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Reversal",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "ABC123", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/swish/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-reversal",
                    "method": "PATCH"
                }
            ]
        }
    }
}
Field Type Description  
paymentOrder string The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.  
id string The relative URL and unique identifier of the reversal resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.  
itemDescriptions object The object representation of the itemDescriptions resource.  
id string The relative URL and unique identifier of the itemDescriptions resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.  
transaction object The object representation of the generic transaction resource, containing information about the current transaction.  
id string The relative URL and unique identifier of the transaction resource . Please read about URL Usage to understand how this and other URLs 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 or failed. If a partial reversal has been done and further transactions are possible, the state will be awaitingActivity.  
number integer 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 transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.  
description string A 40 character length textual description of the purchase.  
payeeReference string A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
receiptReference string A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.  
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.  

Abort

To abort a payment, perform the update-payment-abort operation that is returned in the payment request.

Abort Request

Request

1
2
3
4
PATCH /psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
1
2
3
4
5
6
{
  "payment": {
    "operation": "Abort",
    "abortReason": "CancelledByConsumer"
  }
}

Abort Response

The response will be the payment resource with its state set to Aborted.

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

{
    "payment": {
        "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 70100130293,
        "created": "2019-01-09T13:11:28.371179Z",
        "updated": "2019-01-09T13:11:46.5949967Z",
        "instrument": "Swish",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Aborted",
        "currency": "SEK",
        "prices": {
            "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "amount": 0,
        "description": "swish Test",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "sv-SE",
        "urls": {
            "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "payeeInfo": {
            "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
        },
        "payers": {
           "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "metadata": {
            "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"
        }
    },
    "operations": []
}

Capture

Swish does not support capture as it is a one-phase payment method all completed payments are captured.

Cancel

Swish does not support cancel as cancel can only be used on two-phase payments before they are captured or reversed.

Recurring

Swish does not support recurring payments.