Swish

Introduction

This method initiates a Swish payment request. A typical user flow:

A user selects to pay with Swish at the checkout or cashier at the merchant's website.
Depending on the merchant integration, the user scans a QR code, opens Swish, or enters their mobile phone number.
Once the user is in the Swish app, the user is requested to authorize the payment with Mobile BankID.
Following successful payment authorization, the user is redirected back to the merchant.
There is no Trustly Checkout (frontend) involved. Swish is offered as a pure API integration and the UX is controlled by the merchant.

Request Parameters

Data	Description	Required	Type	Example
Username	The Username	Yes	Text	"joe"
Password	API password	Yes	Text	"secret"
NotificationURL	The URL to which notifications for this payment should be sent to. This URL should be hard to guess and not contain a ? ("question mark").	Yes	Text	"https://www.trustly.com/Trustly/Notify/a2b63j23dj23883jhfhfh"
EndUserID	ID, username, hash or anything uniquely identifying the end-user requesting the deposit. Preferably the same ID/username as used in the merchant's own backoffice in order to simplify for the merchant's support department.	Yes	Text	"123123"
MessageID	Your unique ID for the deposit.	Yes	Text	"12345678"
Attributes	Attributes for this method.	Yes	Object

Attributes

Attributes	Description	Required	Type	Example
MerchantSwishNumber	The Swish number of the payee.	Yes	Text	"1231181189"
UseMobile	Used to decide what the return message should include. I.e Order id, QR code and/or URL.	No	Text	"0" for false "1" for true
SuccessURL	The URL to which the end-user should be redirected after a successful deposit. Do not put any logic on that page since it's not guaranteed that the end-user will in fact visit it.	No	Text	"https://trustly.com/thank_you.html"
FailURL	The URL to which the end-user should be redirected after a failed deposit. Do not put any logic on that page since it's not guaranteed that the end-user will in fact visit it.	No	Text	"https://trustly.com/payment_error.html"
Amount	The amount of money to pay. The amount cannot be less than 0.01 SEK and not more than 999999999999.99 SEK. Valid value has to be all numbers or with 2-digit decimal separated by a period.	Yes	Text	"103.50"
Currency	The currency to use. The only currently supported value is SEK.	Yes	Text	"SEK"
Message	Merchant supplies a message about the payment/order. Max 50 characters. Common allowed characters are the letters a-ö, A-Ö, the numbers 0-9, and special characters !?(),.-:;	M-com flow: No E-com flow : Yes	Text	"Payment"
MobilePhone	The registered cellphone number of the person that makes the payment. It can only contain numbers and has to be at least 8 and at most 15 numbers. It also needs to match the following format in order to be found in Swish: country code + cell phone number (without leading zero).	No	Text	"46712345678"
NationalIdentificationNumber	The end-user's social security number / personal number / birth number / etc.12 digit format.	No	Text	"197901311234"
AgeLimit	Minimum age (in years) that the individual connected to the payerAlias has to be in order for the payment to be accepted. Value has to be in the range of 1 to 99.	No	Text	"18"

Swish payment flows

Swish has two payment flows, m-commerce and e-commerce. Trustly supports both payment flows.

The m-commerce flow is where the merchant receives a token that needs to be delivered either to the user's Swish app to start the payment or displayed in a QR code that the user scans with the Swish app. The user does not have to fill in any phone number to start the payment and it allows the Swish app to be opened directly and automatically return the user to the website.

The e-commerce flow needs a user's phone number to start a payment and then the user opens the app manually to complete the payment and the user cannot be automatically returned to the website.

👍
Trustly recommends using the m-commerce flow as it provides a better user experience resulting in higher conversion.

To trigger the m-commerce flow in the API you on:

MOBILE - set the parameter UseMobile==1 and don’t send a mobilePhone and Trustly on success returns a Swish payment request token (swish://paymentrequest=token&callbackurl=merchantappcallbackurl) and a QR Code in a base64 String.
DESKTOP- set UseMobile==0 and don’t send a mobilePhone and Trustly on Success returns a QR Code in a base64 String.

To trigger the e-commerce flow you set UseMobile== 0 and send the mobilePhone and Trustly will return an OK response and an order id.

Detailed flow diagram

Request and Response examples

Requests

{  
   "method":"Swish",
   "params":{  
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Attributes":{  
            "MerchantSwishNumber":"1231181189",
            "UseMobile":"1",
            "Amount":"25.00",
            "Currency":"SEK",
            "Message":"Pay for Merchant",
            "NationalIdentificationNumber":"790131-1234",
            "AgeLimit":"18"
         },
         "MessageID":"your_unique_order_id",
         "EndUserID":"unique_end_user_id",
         "NotificationURL":"https://URL_to_your_notification_service",
         "Password":"merchant_password",
         "Username":"merchant_username"
      }
   },
   "version":"1.1"
}

{  
   "method":"Swish",
   "params":{  
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Attributes":{  
            "MerchantSwishNumber":"1231181189",
            "UseMobile":"0",
            "Amount":"25.00",
            "Currency":"SEK",
            "Message":"Pay for Merchant",
            "MobilePhone":"46712345678",
            "NationalIdentificationNumber":"790131-1234",
            "AgeLimit":"18"
         },
         "MessageID":"your_unique_order_id",
         "EndUserID":"unique_end_user_id",
         "NotificationURL":"https://URL_to_your_notification_service",
         "Password":"merchant_password",
         "Username":"merchant_username"
      }
   },
   "version":"1.1"
}

Responses

{  
   "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA==",
   "method":"Swish",
   "uuid":"258a2184-2842-b485-25ca-293525152425",
   "data":{  
       "orderid": "2190971587",
        "url": "swish://paymentrequest?token={paymentToken}&callbackurl=successURL",
        "qrcode": "base64_qr_code_image"
   }
}

{  
   "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA==",
   "method":"Swish",
   "uuid":"258a2184-2842-b485-25ca-293525152425",
   "data":{  
       "orderid": "2190971587"
   }
}

Swish Notifications

Credit

Once the Swish request has been successfully processed, a credit notification is sent.

Parameters

Data	Description	Type	Example
notificationid	Unique ID for this notification. Each notification must only be handled once in your system.	Text	"1234567890"
messageid	Your unique ID of the transaction.	Text	"98348932"
enduserid	The ID of the end-user in your system.	Text	"32123"
orderid	Unique ID of the order returned when creating the charge.	Text	"87654567"
amount	The amount set when creating the API call	Text	"98.02"
currency	The currency set when creating the API call	Char(3)	"SEK"
timestamp	The time of the transaction and the GMT offset (+01 means GMT + 1 hours).	Text	"2010-01-20 14:42:04.675645+01"
attributes		Hash/Object

Attributes

Attribute	Description	Type	Example
reference	Payment reference, from the bank, of the payment that occurred based on the Payment request. Only available if status is PAID.	Text	"1E2FC19E5E5E4E18916609B7F8911C12"
payerAlias	Swish mobile phone of the payer.	Text	"467123476"

Example

{
    "method": "credit",
    "params": {
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "amount": "90.02",
            "currency": "SEK",
            "messageid": "98348932",
            "enduserid": "32123",
            "orderid": "87654567",
            "notificationid": "9876543456",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {
            	"reference": "1E2FC19E5E5E4E18916609B7F8911C12",
            	"payerAlias": "467123476"
            }
        }
    },
    "version": "1.1"
}

{
    "result": {
        "signature": "D5FjuMqf3H0Ku ... S16VbzR5v==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "credit",
        "data": {
            "status": "OK"
        }
    },
    "version":"1.1"
}

Cancel

If the Swish request could not be processed, a cancel notification is sent.

Parameters

Data	Description	Type	Example
notificationid	Unique ID for this notification. Each notification must only be handled once in your system.	Text	"1234567890"
messageid	Your unique ID of the transaction.	Text	"98348932"
enduserid	The ID of the end-user in your system.	Text	"32123"
orderid	Unique ID of the order returned when creating the charge.	Text	"87654567"
timestamp	The time of the transaction and the GMT offset (+01 means GMT + 1 hours).	Text	"2010-01-20 14:42:04.67564"
attributes		Hash/Object

Attributes

Attribute	Description	Type	Example
reason	DECLINED CANCELED ERROR	Text	"DECLINED"
details	Description of reason	Text	"User Declined"

Example

{
    "method": "cancel",
    "params": {
        "signature": "F6+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-9021-b874-21ca-293425152415",
        "data": {
            "messageid": "98348932",
            "enduserid": "32123",
            "orderid": "87654567",
            "notificationid": "4876513450",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {
            	"reason": "DECLINED",
            	"details": "User declined"
            }
        }
    },
    "version": "1.1"
}

{
    "result": {
        "signature": "D5FjuMqf3H0Ku ... S16VbzR5v==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "cancel",
        "data": {
            "status": "OK"
        }
    },
    "version":"1.1"
}

Swish API Error codes

Error Num	Error Code	Description
602	ERROR_FUNCTION_ACCESS_DENIED	The merchant does not have access to this function.
607	ERROR_HOST_ACCESS_DENIED	The IP address of the merchant has not been added to Trustly's IP-whitelist.
615	ERROR_INVALID_AMOUNT	The Amount s invalid. The amount must be > 0 with 2 decimals.
616	ERROR_INVALID_CREDENTIALS	The username and/or password used in the API call is incorrect.
620	ERROR_UNKNOWN	There could be several reasons for this error, please reach out to your Trustly contact for details.
622	ERROR_INVALID_CURRENCY_CODE	The currency code is invalid. See this page for valid currencies.
623	ERROR_INVALID_PARAMETERS	Some value or parameter in the deposit call does not match the expected format.
636	ERROR_UNABLE_TO_VERIFY_RSA_SIGNATURE	The signature could not be verified using the merchant's public key. Either the wrong private key was used to generate the signature, or the the data object used to create the signature was serialized incorrectly.
637	ERROR_DUPLICATE_MESSAGE_ID	The MessageID has been used before.
639	ERROR_NO_PUBLIC_KEY	No public key has been configured for the merchant on Trustly's side.
688	ERROR_DUPLICATE_UUID	This uuid has been used before.
696	ERROR_ENDUSERID_IS_NULL	The EndUserID sent in the request is null
697	ERROR_MESSAGEID_IS_NULL	The MessageID sent in the request is null
698	ERROR_INVALID_IP	The IP attribute sent is invalid. Only one IP address can be sent.
700	ERROR_MALFORMED_SUCCESSURL	The SuccessURL sent in the request is malformed. It must be a valid http(s) address.
701	ERROR_MALFORMED_FAILURL	The FailURL sent in the request is malformed. It must be a valid http(s) address.
702	ERROR_MALFORMED_TEMPLATEURL	The TemplateURL sent in the request is malformed. It must be a valid http(s) address.
703	ERROR_MALFORMED_URLTARGET	The URLTarget sent in the request is malformed.
704	ERROR_MALFORMED_MESSAGEID	The MessageID sent in the request is malformed.
705	ERROR_MALFORMED_NOTIFICATIONURL	The NotificationURL sent in the request is malformed. It must be a valid http(s) address.
706	ERROR_MALFORMED_ENDUSERID	The EndUserID sent in the request is malformed.
717	ERROR_INVALID_ORDER_ATTRIBUTE	One or more attributes are sent with the incorrect value.
734	ERROR_NOT_SECURE_NOTIFICATIONURL	The NotificationURL must be using HTTPS, not plain HTTP.
739	ERROR_INVALID_MERCHANT_SWISH_NUMBER	Invalid Merchant Swish number.
740	ERROR_INVALID_SWISH_PAYER	Swish payer not enrolled
741	ERROR_INVALID_SWISH_MESSAGE	Wrong formatted Swish message.
742	ERROR_AGE_LIMITED_SWISH_PAYER	Payer does not meet the age limit.
743	ERROR_SSN_UNMATCHED_SWISH_PAYER	The payer alias in the request is not enrolled in swish with the supplied ssn
744	ERROR_ONGOING_PAYMENT_FOR_SWISH_PAYER	A payment request already exists for that payer.
745	ERROR_SWISH_COUNTERPART_NOT_ACTIVATED	Counterpart is not activated.
746	ERROR_SWISH_PAYER_NOT_ENROLLED	Payer is not enrolled.
747	ERROR_MERCHANT_SWISH_NUMBER_NOT_ENROLLED	Merchant swish number is not enrolled.

Introduction

Request Parameters

Attributes

Swish payment flows

👍Trustly recommends using the m-commerce flow as it provides a better user experience resulting in higher conversion.

Detailed flow diagram

Request and Response examples

Requests

Responses

Swish Notifications

Credit

Parameters

Attributes

Example

Cancel

Parameters

Attributes

Example

Swish API Error codes

👍
Trustly recommends using the m-commerce flow as it provides a better user experience resulting in higher conversion.