Swish: M-Commerce payment flow

Ping Payments™ offers support for the Swish M-commerce flow.

Swish recommends that companies use the M-commerce flow for handling payments, rather than the older E-commerce flow.

You receive a payment_request_token when you use the Swish payment request endpoint. You must deliver the payment_request_token to the payer's client application in order for you to start a payment.

A website that offers you to make payments through Swish may use a URL scheme that triggers opening the Swish app on mobile devices, if the payer uses the same device for purchase and payment. A QR code can be used on one device and scanned into a Swish mobile app on another device, if the purchase is made on one device, and the payment is handled on another device.

The M-commerce flow doesn't rely on the user or payer entering a phone number. Instead, the Swish mobile app initializes a payment using information that was passed from the website or application the payment was initiated from. Using the M-commerce flow also makes it possible for a user to return to the website or application automatically after the payment is completed or cancelled.

You can find more information about the M-commerce flow and payment requests on the Swish website.

---

Using the M-commerce Flow Through Ping Payments

This describes a typical happy path case.

In this scenario, you as an tenant and/or your merchant are the providers of front-end and back-end services. The frontend should be aware of if the payer is using a mobile device or a desktop computer.

🚧

Ping Payments recommends that you persist payment requests in your backend

Making a Purchase

Our example starts with a customer, or payer . Our customer has decided to make a purchase.

📘

Payer

1. Visits frontend application and selects a product or service
2. Clicks pay in the user interface

Preparing for Payment

The payer has committed to a purchase and the process of handling their payment starts in our frontend.

📘

Frontend

Passes the request for a new payment to backend

Once the frontend is done, our backend takes over.

First, we need a payment order .

📘

Backend

1. Creates a new payment order
2. Posts the new payment order to the Ping Payments API

Notes:

• The header of the request we send to the Ping payments API contains our tenant_id
• The body of the request we send to the Ping payments API contains a currency.

Create a payment order with the Payment Order endpoint.

It's time for the Ping Payments API to start working on our payment order,

📘

Ping Payments API

1. Receives the request from our backend
2. Saves the payment order
3. Sends a response to back to our backend

Note:

• A successful response from the Ping Payments API contains the payment_order_id of the new payment order.

🚧

Ping Payments recommends that you persist payment_order_ids in your backend

It's time for us to create the Payment.

📘

Backend

1. Receives the response from the Ping Payments API and saves the payment_order_id
2. Creates a new payment
3. Posts the new payment to the Ping Payments API

Notes:

• Set the property use_qr_code to true, if a QR code from Swish is to be used
• Set the property method to m_commerce
• Always include the payment_order_id of the new payment

Create a payment with the Payments endpoint.

🚧

Ping Payments recommends that you Include a valid status_callback_url in the payment

Now that our payment order and payment have been sent off to the Ping payments API our preparations are done, and we're about to see how the payment is made.

Making the Payment

It's time for the Ping Payments API to pass your payment request to Swish.

📘

Ping Payments API

1. Receives the request
2. Saves the payment, connecting it to the payment order matching the payment_order_id
3. Passes the payment request to Swish
4. Receives a payment_request_token, from Swish and stores it with the payment
5. Sends a response to your backend

Notes:

• The response contains the payment_id of the new payment.
• The payment_request_token from Swish is included in the provider_method_response property in the response from the Ping Payments API to our backend.
• Swish supplied a QR code in their response If use_qr_code was set to true. Otherwise a valid URL was included in the response from Swish.
• The QR code or URL from Swish is included in the response from the Ping Payments API to our backend.

It's now possible for our backend to pass information about a successful payment to the frontend.

📘

Backend

1. Receives the response from the Ping Payments API and saves the payment_id and the QR code or URL
2. Passes the QR code or URL to your Frontend or Client

Note:

• The QR code or URL from Swish can be used as is, or you can use the payment_request_token from Swish to generate a new URL or QR code through an API provided by Swish

Our frontend prepares for the payer to see the payment.

📘

Frontend

use_qr_code = true
Receives the QR code generated by Swish and uses the URL to trigger opening the Swish mobile app

use_qr_code = false
Receives the URL generated by Swish and displays it on the screen for the payer to scan

As the payment request reaches the payer's client, it's possible for the payer to authorize the payment.

📘

Payer/Client

1. The payer reviews the payment request in the Swish mobile app, and authorizes payment
2. The Swish mobile app sends the authorization to Swish and Swish notifies Ping Payments

When the payer has approved of the payment request, all that's left is to confirm the payment.

Updating Payment Status

When Swish is done, it's time for the Ping Payments API to finish off the payment.

📘

Ping Payments API

1. Receives notification of the payment status from Swish, and updates the payment
2. Posts a callback with information regarding payment status to the status_callback_url

Note:

• If we'd omitted including a valid status_callback_url when we created the payment, we wouldn't be getting this status update now.

Now it's time for our backend to finish off the payment in our system.

📘

Backend

1. Receives status update on the status_callback_url
2. Updates internal payment status
3. Passes a notification of successful payment to frontend

After our backend is finished, our frontend can get to the business of making sure the payer is notified.

📘

Frontend

1. Receives a notification of successful payment from backend
2. Sends a receipt and proof of successful payment to payer's client

At the end of this journey, the payer gets a receipt.

📘

Payer/Client

1. The payer's client receives the notification of successful payment
2. use_qr_code = true:
   The payer's client shows a QR code and the payer scans the QR code in the Swish app
   use_qr_code = false:
   The payer's client triggers opening the Swish mobile app
3. The payer reviews the receipt shown in the Swish mobile app