Configure payment experience

Swish offers different payment flows for different devices and user experiences. You can choose from three payment flows based on your integration requirements:

• Hosted flow: Redirects customers to a secure payment page that handles both desktop and mobile.
• QR code flow: Displays a QR code on your checkout page that desktop users scan with their mobile device.
• Mobile app switch flow: Redirect mobile users from your website directly to the Swish app.

Create payment

After configuring your client and local payment instances, you can initiate payments using the startPayment() method with flow-specific parameters.

Implement hosted flow

The hosted flow redirects customers to a secure payment page where they complete their Swish payment. This page automatically detects the device type and displays either a QR code (desktop) or switches to the Swish app (mobile).

The Braintree Web SDK supports two flow types for hosted payments:

• Redirect flow: Redirects the customer to the payment page in the same browser window or within an iframe. Before implementation, register the domains where customers will return after payment in the Braintree Control Panel for both sandbox and production environments. For more information, see Redirect flow.

  For iframe implementation, see Usage inside an iframe.

• Popup flow: Opens the payment page in a popup window.

localPaymentInstance.startPayment({
  paymentType: 'swish',
  paymentTypeCountryCode: 'SE',
  amount: '10.00',
  currencyCode: 'SEK',
  givenName: 'Joe',
  surname: 'Doe',
  fallback: {
    buttonText: 'Return to Store',
    url: 'https://example.com/my-checkout-page'
  },
  swishOptions: {
    returnUrl: 'https://example.com'
  },
  onPaymentStart: function (data, continueCallback) {
    // On desktop, this follows standard redirect flow
    console.log('Payment ID:', data.paymentId);
    continueCallback();
  }
}, function (startPaymentErr, payload) {
  if (startPaymentErr) {
    // Handle any error calling startPayment
    console.error(startPaymentErr);
    return;
  }

  // Submit payload.nonce to your server
  console.log('Payload', payload);
});

In the client-side implementation,

1. In the startPayment() method call, include the following data parameters:
   
   

   Parameter name	Description
   paymentType	Payment method for the transaction. For Swish payments, set to swish.
   paymentTypeCountryCode	Country where the Swish payment is processed, specified as an ISO 3166-1 alpha-2 country code. Set to SE to specify Sweden.
   amount	Total payment amount.
   currencyCode	Currency code for the transaction. For Swish payments, set to SEK for Swedish Krona.
   givenName	Customer's first name.
   surname	Customer's last name.
   fallback.url	URL to redirect the customer if the payment fails or is canceled.
   fallback.buttonText	Display text for the return button shown to customers when returning from a failed or canceled payment. Example: Return to Store
   swishOptions.returnUrl	URL to redirect the customer after they complete the Swish payment.
   onPaymentStart	Callback function invoked when the payment flow begins. Receives data containing the payment ID and continueCallback to proceed with the payment flow. ImportantStore data.paymentId on your server to identify this payment when you receive webhook notifications.

2. When the customer completes the payment, the SDK returns the single-use token in the payload. You can then send the single-use token to your server to create the transaction.

Implement QR code flow

The QR code flow displays a scannable QR code directly on your checkout page. Customers use their Swish mobile app to scan the code and complete payment on their mobile device. Unlike the hosted flow, there is no redirection - the QR code is displayed in your specified container element.

// This is Swish specific flow to render QR code.
// There is no redirection in this scenario.
// Merchant will receive single-use token via webhook.

localPaymentInstance.startPayment({
  paymentType: 'swish',
  paymentTypeCountryCode: 'SE',
  amount: '10.00',
  currencyCode: 'SEK',
  givenName: 'Joe',
  surname: 'Doe',
  swishOptions: {
    requestQrCode: true,
    qrContainer: '#qr-code-container' // QR code will be automatically injected here
  },
  onPaymentStart: function (data) {
    console.log('Payment ID:', data.paymentId);
    // QR code is already displayed in the container
  }
}, function (startPaymentErr, payload) {
  if (startPaymentErr) {
    // Handle any error calling startPayment
    console.error(startPaymentErr);
    return;
  }
  // Merchant will receive single-use token via webhook
});

In the client-side implementation,

1. Ensure you have a container element for the QR code in your HTML.
2. In the startPayment() method call, include the following data parameters:
   
   

   Parameter name	Description
   paymentType	Payment method for the transaction. For Swish payments, set to swish.
   paymentTypeCountryCode	Country where the Swish payment is processed, specified as an ISO 3166-1 alpha-2 country code. Set to SE to specify Sweden.
   amount	Total payment amount.
   currencyCode	Currency code for the transaction. For Swish payments, set to SEK for Swedish Krona.
   givenName	Customer's first name.
   surname	Customer's last name.
   swishOptions.requestQrCode	Specifies whether to generate a QR code for the payment. Set to true to enable QR code generation.
   swishOptions.qrContainer	Identifier for the container element where the QR code is displayed. Example: #qr-code-container
   onPaymentStart	Callback function invoked when the payment flow begins. Receives data containing the payment ID.

3. When the payment starts, the SDK injects the QR code into the specified container. You can then use webhooks and polling to track when the customer completes the payment by scanning the QR code.

Implement mobile app switch flow

The mobile app switch flow automatically redirects customers from your mobile website to the Swish mobile app when they initiate payment from a mobile device browser.

// Mobile app switch flow - direct redirect to Swish mobile app
// Automatically triggers when customer is on mobile browser
// Customer completes payment in Swish app
// Merchant receives single-use token via webhook when payment completes

localPaymentInstance.startPayment({
  paymentType: 'swish',
  paymentTypeCountryCode: 'SE',
  amount: '10.00',
  currencyCode: 'SEK',
  givenName: 'Joe',
  surname: 'Doe',
  fallback: {
    buttonText: 'Return to Store',
    url: 'https://example.com/my-checkout-page'
  },
  swishOptions: {
    returnUrl: 'https://example.com/my-checkout-page' // optional
  },
  onPaymentStart: function (data, continueCallback) {
    // SDK automatically switches to Swish app on mobile
    console.log('Payment ID:', data.paymentId);
    continueCallback();
  }
}, function (startPaymentErr, payload) {
  if (startPaymentErr) {
    // Handle any error calling startPayment
    console.error(startPaymentErr);
    return;
  }
  // Merchant will receive single-use token via webhook
});

In the client-side implementation,

1. In the startPayment() method call, include the following data parameters:
   
   

   Parameter name	Description
   paymentType	Payment method for the transaction. For Swish payments, set to swish.
   paymentTypeCountryCode	Country where the Swish payment is processed, specified as an ISO 3166-1 alpha-2 country code. Set to SE to specify Sweden.
   amount	Total payment amount.
   currencyCode	Currency code for the transaction. For Swish payments, set to SEK for Swedish Krona.
   givenName	Customer's first name.
   surname	Customer's last name.
   fallback.url	URL to redirect the customer if the payment fails or is canceled.
   fallback.buttonText	Display text for the return button shown to customers when returning from a failed or canceled payment. Example: Return to Store
   swishOptions.returnUrl	URL to redirect the customer after they complete the Swish payment.
   onPaymentStart	Callback function invoked when the payment flow begins. Receives data containing the payment ID and continueCallback to proceed with the payment flow.

2. When the customer is on a mobile device, the SDK automatically redirects to the Swish mobile app. You can then use webhooks and polling to track when the customer completes the payment in the Swish app.

Handle webhooks

Implement webhook handling to receive real-time payment status updates from Braintree. Webhooks are essential for QR code and mobile app switch flows, where the payment completes outside your website and the customer may not return.

For complete webhook implementation details including endpoint setup, notification parsing, signature verification, and notification types, see Handle webhooks.

Track payment status

For QR code and mobile app switch flows, the customer completes payment outside your website in the Swish app. Your server receives the single-use token via webhook when payment completes. Implement client-side polling to check your server for payment status updates.