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
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.
Request examples
{
"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"
}
Response examples
{
"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.
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"
}Swish notifications - Cancel
If the Swish request could not be processed, a cancel notification is sent.
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. |