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 Swedbank Pay admin portal.
Swish transactions
All Swish transactions are described below. Please note that Swish does not support Merchant Initiated Transactions for the time being.
Sales
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
.
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"sales": {
"id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales",
"saleList": [{
"id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"swishPaymentReference": "8D0A30A7804E40479F88FFBA26111F04",
"swishStatus": "PAID",
"transaction": {
"id": "/psp/swish/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": "Sale",
"state": "Completed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"isOperational": false,
"operations": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URL and unique identifier of the payment resource this sales belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution. |
sales |
object |
The current sales resource. |
└➔ id
|
string |
The relative URL and unique identifier of the sales resource this sales belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution. |
└➔ saleList
|
array |
The array of sale transaction objects. |
└➔ saleList[]
|
object |
The sale transaction object described in the sale resource below. |
└─➔ id
|
string |
The relative URL and unique identifier of the transaction resource this sales belongs to. 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 orfailed . If a partial sale 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 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. 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. |
Create Sales transaction
In browser based solutions the payers 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 based solutions. With mobile app based solutions, the payer uses the
device that hosts the Swish app to manage the purchase, making msisdn
optional.
Browser-based 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-based 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
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
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
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
Request
1
2
3
4
GET /psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
The reversal
resource contains information about the
reversal
transaction made against a swish payment. You can
return a specific reversal
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
27
28
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"reversals": {
"id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals",
"reversalList": [{
"id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"swishPaymentReference": "8D0A30A7804E40479F88FFBA26111F04",
"swishStatus": "PAID",
"transaction": {
"id": "/psp/swish/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": "Reversal",
"state": "Completed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"isOperational": false,
"operations": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URL and unique identifier of the payment resource this reversals belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution. |
reversals |
object |
The current reversals resource. |
└➔ id
|
string |
The relative URL and unique identifier of the reversals resource this reversals belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution. |
└➔ reversalList
|
array |
The array of reversal transaction objects. |
└➔ reversalList[]
|
object |
The reversal transaction object described in the reversal resource below. |
└─➔ id
|
string |
The relative URL and unique identifier of the transaction resource this reversals belongs to. 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 orfailed . If a partial reversal 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 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. 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. |
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.
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(35) |
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. |
The created reversal
resource contains information about the
reversal
transaction made against a swish
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"reversal": {
"id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"itemDescriptions": {
"id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
},
"transaction": {
"id": "/psp/swish/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": "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/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"rel": "edit-reversal",
"method": "PATCH"
}
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URL and unique identifier of the payment resource this reversal belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution. |
|
reversal |
string |
The current reversal transaction resource. |
|
└➔ id
|
string |
The relative URL and unique identifier of the reversal resource this reversal belongs to. 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 this reversal belongs to. 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. | |
└─➔ id
|
string |
The relative URL and unique identifier of the transaction resource this reversal belongs to. 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 orfailed . If a partial reversal 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 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. 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. |
Abort
To abort a payment, perform the update-payment-abort
operation that is
returned in the payment request.
You need to include the following HTTP body:
Request
1
2
3
4
5
6
7
8
9
10
11
PATCH /psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"payment": {
"operation": "Abort",
"abortReason": "CancelledByConsumer"
}
}
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": []
}
The response will be the payment
resource with its state
set to Aborted
.
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.