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

Visits frontend application and selects a product or service

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

Creates a new payment order

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

Receives the request from our backend

Saves the payment order

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

Receives the response from the Ping Payments API and saves the payment_order_id

Creates a new payment

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

Receives the request

Saves the payment, connecting it to the payment order matching the payment_order_id

Passes the payment request to Swish

Receives a payment_request_token, from Swish and stores it with the payment

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

Receives the response from the Ping Payments API and saves the payment_id and the QR code or URL

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

The payer reviews the payment request in the Swish mobile app, and authorizes payment

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

Receives notification of the payment status from Swish, and updates the payment

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

Receives status update on the status_callback_url

Updates internal payment status

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

Receives a notification of successful payment from backend

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

The payer's client receives the notification of successful payment

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

The payer reviews the receipt shown in the Swish mobile app