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 API 1.0

Payment (Deposit) Flow

1. Generate a sessionToken.

2. Perform the payment by sending a /payment request with the following mandatory parameters:

• • • 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
        • country must be SE
      • email
    • 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.

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',

REST API 2.0

Payment (Deposit) Flow

1. Perform the payment by sending a /payments request with the following mandatory parameters:

• • • amount
    • currency class containing:
      • “SEK“
    • paymentOption.alternativePaymentMethod class containing:
      • paymentMethod: “swish”
      • data class containing:
        • nationalId
    • deviceDetails class containing:
      • ipAddress
    • buyerDetails class containing:
      • buyerId
      • firstName
      • lastName
      • email
      • billingAddress
        • countryCode
          • countryCode must be SE

Example POST/payments Request

{
  "processingEntityId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": "200",
  "currency": "SEK",
  "merchantTransactionId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "swish",
      "data": {
        "nationalId": "<customer national ID>"
      }
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "buyerDetails": {
    "buyerId": "<unique customer identifier in merchant system>",
    "firstName": "Erik",
    "lastName": "Lindqvist",
    "email": "[email protected]",
    "billingAddress": {
      "countryCode": "SE"
    }
  },
  "urlDetails": {
    "webhookUrl": "<your webhook URL>"
  }
}

After the transaction is processed, Nuvei sends a webhook notification that includes the result of the transaction to the URL provided in urlDetails.webhookUrl, which Nuvei recommends including in the /payments request in order to receive asynchronous notifications.

Payout (Withdrawal) Flow

A user initiates payout by providing one of the following:

• Swish Direct details in paymentOption.alternativePaymentMethod.
• Previously created payment token in paymentOption.paymentToken.paymentTokenId.

Initiating Payout via alternativePaymentMethod

1. Send a POST/payouts request using the paymentOption.alternativePaymentMethod with the following mandatory parameters:

• • • amount
    • currency
    • alternativePaymentMethod class containing:
      • name: “swish”
      • data class containing:
        • nationalID
    • buyerDetails:
      • buyerId
      • firstName
      • lastName
      • companyName
      • locale
      • email
        • phone
    • billingAddress class containing:
      • city
      • zip
      • countryCode
        • countryCode must be SE
    • shippingAddress class containing
      • city
      • zip
      • countryCode
        • countryCode must be SE

Example /payouts Request with alternativePaymentMethod

{
  "processingEntityId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 100,
  "currency": "SEK",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "swish",
      "data": {
        "nationalId": "<customer national ID>"
      }
    }
  },
  "buyerDetails": {
    "buyerId": "buyerId123",
    "firstName": "Alex",
    "lastName": "Smith",
    "companyName": "Nuvei Corp",
    "locale": "sv-SE",
    "dateOfBirth": "1978-01-01",
    "email": "[email protected]",
    "phone": "46701234567",
    "billingAddress": {
      "city": "Stockholm",
      "zip": "11122",
      "countryCode": "SE"
    },
    "shippingAddress": {
      "sameAsBilling": true
    }
  },
  "urlDetails": {
    "webhookUrl": "<URL to which webhooks are sent>"
  }
}

After the payout is processed, Nuvei sends a webhook that includes the result of the transaction to the URL provided in urlDetails.webhookUrl, which Nuvei recommends including in the POST /payouts request.

Initiating Payout via paymentTokenId

Send a /payouts request that uses a previously created payment token by including paymentOption.paymentToken.paymentTokenId and the associated buyerDetails.buyerId.

Example POST/payments Request with Payment Token

{
  "processingEntityId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 100,
  "currency": "SEK",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "abc123def456ghi789jkl012mno345pq"
    }
  },
  "buyerDetails": {
    "buyerId": "buyerId123",
    "firstName": "Alex",
    "lastName": "Smith",
    "companyName": "Nuvei Corp",
    "locale": "sv-SE",
    "dateOfBirth": "1978-01-01",
    "email": "[email protected]",
    "phone": "46701234567",
    "billingAddress": {
      "city": "Stockholm",
      "zip": "11122",
      "countryCode": "SE"
    },
    "shippingAddress": {
      "sameAsBilling": true
    }
  },
  "urlDetails": {
    "webhookUrl": "<URL to which webhooks are sent>"
  }
}

After the payout is processed, Nuvei sends a webhook that includes the result of the transaction to the URL provided in urlDetails.webhookUrl, which Nuvei recommends including in the POST /payouts request.

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.