logo
Trustly Docs
BETA

Swish

Updated 8 days ago

Introduction

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

  1. A user selects to pay with Swish at the checkout or cashier at the merchant's website.

  2. Depending on the merchant integration, the user scans a QR code, opens Swish, or enters their mobile phone number.

  3. Once the user is in the Swish app, the user is requested to authorize the payment with Mobile BankID.

  4. Following successful payment authorization, the user is redirected back to the merchant.

  5. 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

M-commerce flow request
E-commerce flow request
{  
   "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"
}


Response examples

M-commerce response
E-commerce response
{  
   "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"
   }
}

Swish Notifications - Credit

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

Example

Credit
Valid response
{
    "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"
}

Swish notifications - Cancel

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

Example

Cancel
Valid response
{
    "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"
}

Swish API Error codes

Error NumError CodeDescription
602ERROR_FUNCTION_ACCESS_DENIEDThe merchant does not have access to this function.
607ERROR_HOST_ACCESS_DENIEDThe IP address of the merchant has not been added to Trustly’s IP-whitelist.
615ERROR_INVALID_AMOUNTThe Amount s invalid. The amount must be > 0 with 2 decimals.
616ERROR_INVALID_CREDENTIALSThe username and/or password used in the API call is incorrect.
620ERROR_UNKNOWNThere could be several reasons for this error, please reach out to your Trustly contact for details.
622ERROR_INVALID_CURRENCY_CODEThe currency code is invalid. See this page for valid currencies.
623ERROR_INVALID_PARAMETERSSome value or parameter in the deposit call does not match the expected format.
636ERROR_UNABLE_TO_VERIFY_RSA_SIGNATUREThe 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.
637ERROR_DUPLICATE_MESSAGE_IDThe MessageID has been used before.
639ERROR_NO_PUBLIC_KEYNo public key has been configured for the merchant on Trustly’s side.
688ERROR_DUPLICATE_UUIDThis uuid has been used before.
696ERROR_ENDUSERID_IS_NULLThe EndUserID sent in the request is null
697ERROR_MESSAGEID_IS_NULLThe MessageID sent in the request is null
698ERROR_INVALID_IPThe IP attribute sent is invalid. Only one IP address can be sent.
700ERROR_MALFORMED_SUCCESSURLThe SuccessURL sent in the request is malformed. It must be a valid http(s) address.
701ERROR_MALFORMED_FAILURLThe FailURL sent in the request is malformed. It must be a valid http(s) address.
702ERROR_MALFORMED_TEMPLATEURLThe TemplateURL sent in the request is malformed. It must be a valid http(s) address.
703ERROR_MALFORMED_URLTARGETThe URLTarget sent in the request is malformed.
704ERROR_MALFORMED_MESSAGEIDThe MessageID sent in the request is malformed.
705ERROR_MALFORMED_NOTIFICATIONURLThe NotificationURL sent in the request is malformed. It must be a valid http(s) address.
706ERROR_MALFORMED_ENDUSERIDThe EndUserID sent in the request is malformed.
717ERROR_INVALID_ORDER_ATTRIBUTEOne or more attributes are sent with the incorrect value.
734ERROR_NOT_SECURE_NOTIFICATIONURLThe NotificationURL must be using HTTPS, not plain HTTP.
739ERROR_INVALID_MERCHANT_SWISH_NUMBERInvalid Merchant Swish number.
740ERROR_INVALID_SWISH_PAYERSwish payer not enrolled
741ERROR_INVALID_SWISH_MESSAGEWrong formatted Swish message.
742ERROR_AGE_LIMITED_SWISH_PAYERPayer does not meet the age limit.
743ERROR_SSN_UNMATCHED_SWISH_PAYERThe payer alias in the request is not enrolled in swish with the supplied ssn
744ERROR_ONGOING_PAYMENT_FOR_SWISH_PAYERA payment request already exists for that payer.
745ERROR_SWISH_COUNTERPART_NOT_ACTIVATEDCounterpart is not activated.
746ERROR_SWISH_PAYER_NOT_ENROLLEDPayer is not enrolled.
747ERROR_MERCHANT_SWISH_NUMBER_NOT_ENROLLEDMerchant swish number is not enrolled.