Swish Payout

Introduction

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

End-user selects to withdraw with Swish on your website.
End-user will get the result of the Payout on the your website after the notification
from Trustly.
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

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
MerchantPayoutSwishNumber	The Swish number of the payee.	Yes	Text	"1231181189"
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).	YES	Text	"46712345678"
NationalIdentificationNumber	The end-user's social security number / personal number / birth number / etc.12 digit format.	YES	Text	"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":"197901311234",
            "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

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"

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

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": "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 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.
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.