Introduction

This method initiates a Swish Payout. A typical user flow:

  1. End-user selects to withdraw with Swish on your website.
  2. End-user will get the result of the Payout on the your website after the notification
    from Trustly.
  3. There is no Trustly Checkout (frontend) involved. Swish Payout is offered as an API
    integration and the UX is controlled by the merchant.

Process Overview

Request Parameters

DataDescriptionRequiredTypeExample
UsernameThe UsernameYesText"joe"
PasswordAPI passwordYesText"secret"
NotificationURLThe URL to which notifications for this payment should be sent to. This URL should be hard to guess and not contain a ? ("question mark").YesText"https://www.trustly.com/Trustly/Notify/a2b63j23dj23883jhfhfh"
EndUserIDID, 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.
YesText"123123"
MessageIDYour unique ID for the deposit.YesText"12345678"
AttributesAttributes for this method.YesObject

Attributes

AttributesDescriptionRequiredTypeExample
MerchantPayoutSwishNumberThe Swish number of the payee.YesText"1231181189"
AmountThe 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.YesText"103.50"
CurrencyThe currency to use. The only currently supported value is SEK.YesText"SEK"
MessageMerchant supplies a message about the payment/order. Max 50 characters. Common allowed characters are the letters a-ö, A-Ö, the numbers 0-9, and special characters !?(),.-:;M-com flow: No

E-com flow : Yes
Text"Payment"
MobilePhoneThe 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).YESText"46712345678"
NationalIdentificationNumberThe end-user's social security number / personal number / birth number / etc.12 digit format.YESText"197901311234"

Request and Response examples

Requests

{  
   "method":"SwishPayout",
   "params":{  
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Attributes":{  
            "MerchantPayoutSwishNumber":"1231181189",
            "Amount":"25.00",
            "Currency":"SEK",
            "Message":"Pay for Merchant",
            "NationalIdentificationNumber":"790131-1234",
            "MobilePhone":"46712345678"
      	},
         "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

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



Swish Notifications

Payout Confirmation

Once the Swish Payout request has been successfully processed, a payout confirmation notification is sent.

Parameters

DataDescriptionTypeExample
notificationidUnique ID for this notification. Each notification must only be handled once in your system.Text"1234567890"
messageidYour unique ID of the transaction.Text"98348932"
enduseridThe ID of the end-user in your system.Text"32123"
orderidUnique ID of the order returned when creating the charge.Text"87654567"
amountThe amount set when creating the API callText"98.02"
currencyThe currency set when creating the API callChar(3)"SEK"
timestampThe time of the transaction and the GMT offset (+01 means GMT + 1 hours).Text"2010-01-20 14:42:04.675645+01"
attributesHash/Object

Attributes

AttributeDescriptionTypeExample
referencePayment reference, from the bank, of the payment that occurred based on the Payment request. Only available if status is PAID.Text"1E2FC19E5E5E4E18916609B7F8911C12"

Example

{
    "method": "payoutconfirmation",
    "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",
            }
        }
    },
    "version": "1.1"
}

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

Cancel

If the Swish Payout request cannot be processed, a cancel notification is sent.

Parameters

DataDescriptionTypeExample
notificationidUnique ID for this notification. Each notification must only be handled once in your system.Text"1234567890"
messageidYour unique ID of the transaction.Text"98348932"
enduseridThe ID of the end-user in your system.Text"32123"
orderidUnique ID of the order returned when creating the charge.Text"87654567"
timestampThe time of the transaction and the GMT offset (+01 means GMT + 1 hours).Text"2010-01-20 14:42:04.67564"
attributesHash/Object

Attributes

AttributeDescriptionTypeExample
reasonDECLINED
CANCELED
ERROR
Text"DECLINED"
detailsDescription of reasonText"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": "ERROR",
            	"details": "RF07-Transaction could not be executed"
            }
        }
    },
    "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 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.
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.