Introduction

Swish Direct is a digital payment platform designed to offer a fast, secure, and convenient way to manage money and make transactions. It is widely used in Sweden, allowing users to easily send and receive money using only their mobile phones. The service is directly linked to users’ bank accounts and operates in real-time, making it ideal for everything from splitting bills with friends to paying for services and goods both online and in stores.

By default, the merchant redirects the customer to an APM provider page with the QR code.

Supported Countries

• Sweden

Supported Currencies

• SEK

REST 1.0 API

Payment (Deposit) Flow

1. Generate a sessionToken

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency class containing:
  • “SEK“
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Swish“
  • IBP_national_id
• deviceDetails class containing:
  • ipAddress
• billingAddress class containing:
  • firstName
  • lastName
  • country
  • email
    • country must be SE
• userDetails class containing:
  • firstName
  • lastName
  • country
  • email
  • identification
    • country must be SE

Example /payment Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "SEK",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Swish",
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "SE",
    "email": "[email protected]"
    "identification": "19810101-0000"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "SE",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response

{
  "internalRequestId": 40321021,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5416795427517477813",
  "merchantSiteId": "186111",
  "version": "1.0",
  "clientRequestId": "20240419161958",
  "sessionToken": "8343a532-e825-49e9-9c40-78d5736d52a2",
  "orderId": "42938811",
  "paymentOption": {
    "redirectUrl": <redirect URL>,
    "userPaymentOptionId": "2153232561",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Example Payment DMN with Status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=42938811&userid=&merchant_unique_id=&customData=&productId=&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=SEK&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Sweden&state=&city=Madrid&zip=%24%7BzipU%7D&phone1=0987654321&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ZimplerMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Swish&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-04-19.13%3A20%3A36&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&userPaymentOptionId=&TransactionID=2610000000000021338&externalTransactionId=1b980ce594ea4efe0217&APMReferenceID=5323D35BF5611BFA4E054E52123EBA6F&orderTransactionId=24342911&totalAmount=10.00&dynamicDescriptor=hristo+descriptor&item_name_1=NA&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&type=DEPOSIT&clientRequestId=20240419161958&relatedTransactionId=&sessionId=683848d005c89d7f13d175fef3ff&responsechecksum=5b7e3c0847db0b9226181141614e6d07c1bed66545ef4010012386fd31909d8d&advanceResponseChecksum=f26f81d6f86d86d00395f36562aab3bb3dbfaef1347e1236f153ef41ada84f8c',

Example Payment DMN with Status=PENDING

...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=42938811&userid=&merchant_unique_id=&customData=&productId=&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=SEK&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Sweden&state=&city=Madrid&zip=%24%7BzipU%7D&phone1=0987654321&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ZimplerMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_Swish&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-04-19.13%3A20%3A27&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&userPaymentOptionId=&TransactionID=2610000000000021338&externalTransactionId=1b980ce594ea4efe0217&APMReferenceID=5323D35BF5611BFA4E054E52123EBA6F&orderTransactionId=24342911&totalAmount=10.00&dynamicDescriptor=hristo+descriptor&item_name_1=NA&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&type=DEPOSIT&clientRequestId=20240419161958&relatedTransactionId=&sessionId=683848d005c89d7f13d175fef3ff&responsechecksum=af847b552e38b63f61a11323fa1ec59942d0021499f37ccf694c4112ae1f5f46&advanceResponseChecksum=5a8773c33096b8699b07cfb9c1aa82ad477f72f0d46c37e2b8dc9e54779cd502',

Payout (Withdrawal) Flow

Send a /payout request and include the userTokenId and userPaymentOptionId, which contains the user’s previously stored APM account details. See Payout for an example.
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

 

Example Payout DMN with Status=Approved

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=42941071&userid=123Swish8&merchant_unique_id=12345&customData=hristo_tr_test&productId=&first_name=&last_name=&email=&currency=SEK&clientUniqueId=12345&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Swish&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-04-22.07%3A34%3A48&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=123Swish8&userPaymentOptionId=2153197221&TransactionID=2610000000000021535&externalTransactionId=f92b3e3f-bdc0-4ea0-a0a1-92e500c160e7&totalAmount=10.0&dynamicDescriptor=hristo+descriptor&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20240422&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=3a4559644fe478714363ea878064ac53f29a415ac9181dd6bf61f798f642d1ba&advanceResponseChecksum=b08a1593d0d6c063ee441480af72d98c267cfc6b2580896abcf5f65d7f2c8f69',

User Experience

Payment

The user is redirected to the Swish website and a QR code appears.

Sandbox

In the sandbox environment, the transaction is simulated for approval or decline and the process ends.

Production

In the production environment, the process continues.

1. Using the Swish mobile app, the user scans the QR code and completes the payment.
   
   The user is redirected to Nuvei’s cashier for the transaction reference.
   

Payout (Withdrawal) After Deposit

1. On the ‘My Payment Methods’ screen, the user selects ‘Swish’.
   
   The withdrawal is created and processed.
   

Payout (Withdrawal) Without Deposit

For /payout without a prior deposit, the user phone number and national Id must be sent. Both are provided via user details. The phone number is collected on the cashier.

Testing

Nuvei provides test credentials and testing scenarios if needed.