# Swish for Unified Payments API

To accept Swish payments, follow these steps:

1. Request a payment.
2. Redirect the customer.

---

## Request a payment

Call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint:

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/`

### Request example

```json
{
  "amount": 100,
  "currency": "SEK",
  "source": {
    "type": "swish",
    "account_holder":{
        "first_name":"Hannah",
        "last_name":"Bret"
      },
    "payment_country": "SE"
    },
    "billing_descriptor": {
      "name": "merchant name"
    }
}
```

### Response example

```json
{
  "id": "pay_3j4564ofxydevmruz6amur7djq",
  "status": "Pending",
  "reference": "example-ref",
  "payment_type": "Regular",
  "_links": {
    "self": {
      "href": "https://gwc.ckotech.co/payments/pay_3j4564ofxydevmruz6amur7djq"
    },
    "redirect": {
      "href": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfeFJWYVZaa0czeFBQTzBuZzd0czNhIn19.lfNRW50Wt-Au9l-daxQ6bi8N1XRbdJmVH4XFlPByhH16iJr-QlPEPZFPWD-8MX4-A8c2NPbeTaujr8ernyl4cg",
      "qr_code": {
        "text": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAsNklEQVR4Xu2d+5tdZZXn..."
      },
      "mobile": {
        "android": {
          "href": "swish://paymentrequest?token=AAAAAAAAAAAAABUCIDZXYpP3hM2Mx1Le&callbackurl=https%3A%2F%2Fqaapi.ckotech.co%2Fapms%2Fppro%2Fswish%2Fredirect%2Ftok_lzwgligaujlu5betpu3afjq4ju%3Ftxid%3D150220365762%26cs%3D058372607475360e841ac289156780f618cc79869d3d762af0dbe72f2eeb59db"
        },
        "ios": {
          "href": "swish://paymentrequest?token=AAAAAAAAAAAAABUCIDZXYpP3hM2Mx1Le&callbackurl=https%3A%2F%2Fqaapi.ckotech.co%2Fapms%2Fppro%2Fswish%2Fredirect%2Ftok_lzwgligaujlu5betpu3afjq4ju%3Ftxid%3D150220365762%26cs%3D058372607475360e841ac289156780f618cc79869d3d762af0dbe72f2eeb59db"
        }
      }
    }
  }
}
```

If you receive a `202` response, with the `status` field set to `Pending`, your request was successful.

---

## Redirect the customer

The redirection step varies depending on whether you request the payment from:

- A desktop browser
- A mobile app

### Desktop

To request a payment from a desktop browser:

1. Ensure that the Swish app is installed on your customer's phone.
2. Redirect your customer to the `_links.redirect.href` URL provided in the response. <br>
The URL displays a QR code.
3. Your customer must scan the code using their Swish app and authorize the payment on their device.
4. After authorizing the payment, the customer is redirected to either your success or failure URL.

### Mobile

To request a payment from a mobile app:

1. Ensure that the Swish app is installed on your customer's phone. <br>
If the application is not installed, instruct the customer to install it.
2. Get the necessary token from the `redirect.mobile` object in the response:
    - For Android – Pass the deeplink provided in `redirect.mobile.android` to open the Swish app in your customer's phone
    - For iOS – Pass the deeplink provided in `redirect.mobile.ios` to open the Swish app in your customer's phone
3. The Swish app launches on your customer's phone, where they can authorize the payment.

---

## Get details about a payment

To retrieve details about the payment, call the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList) endpoint, and provide the `payment_id` value you received in the Create a payment response as the `{id}` path parameter.

**Production**

`GET` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

### Response example

```json
{
  "id": "pay_4k4b3jkvgmuexfpiww6nzhf4ru",
  "requested_on": "2025-08-22T13:15:09.3823555Z",
  "source": {
    "type": "swish"
  },
  "amount": 123,
  "currency": "SEK",
  "payment_type": "Regular",
  "reference": "example-ref",
  "status": "Captured",
  "approved": true,
  "balances": {
    "total_authorized": 123,
    "total_voided": 0,
    "available_to_void": 0,
    "total_captured": 123,
    "available_to_capture": 0,
    "total_refunded": 0,
    "available_to_refund": 123
  },
  "billing_descriptor": {
    "name": "merchant name"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_4k4b3jkvgmuexfpiww6nzhf4ru"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_4k4b3jkvgmuexfpiww6nzhf4ru/actions"
    },
    "refund": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_4k4b3jkvgmuexfpiww6nzhf4ru/refunds"
    }
  }
}
```

---

## Refund a payment

Swish supports both full and partial refunds.

Call the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint, and provide the `payment_id` value you received in the Create a payment response as the `{id}` path parameter.

---

## Cancel a payment

If the customer fails to complete their payment within three minutes, you receive a [Payment expired](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_expired.md) webhook.

---

## Test your integration

To set up your test environment you need:

  - Credentials to Swish's sandbox environment
  - A BankID account – BankID is an electronic identification system, required for all Swish payments.
  - The Swish test app

1. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes) to request:
    - A test personal identification number
    - A test phone number
    - A certificate password
2. Sign in to BankID and follow their steps request a personal code.
3. You receive a personal code in your email.
4. Enter the personal code on the BankID login page to sign in.
5. Generate a _Mobile BankID_ using your test PIN from Checkout.com.
6. Download the BankID app from your device's app store.
7. Update the server from the Android or iOS app settings to configure to test environment: `"cavainternal.test.bankid.com"`.
8. Launch the BankID app and scan the QR code on your BankID screen.
9. Follow the instructions on the screen to finish setting up BankID.
10. Depending on your platform, download the Swish test app from their test distribution platforms:
    - Android – [Swish in Firebase](https://appdistribution.firebase.dev/i/6e190185a34cb2f3)
    - iOS – [Swish in TestFlight](https://testflight.apple.com/join/iQTsRg5b)
11. Sign in using the test personal number, phone number, and certificate password provided.
12. Select to activate your BankID.

After setting up your test environment, you can send test payment requests, and validate them using your test Swish app.