Swish
Last updated: 12-Nov-2024
Overview
Checkout can be used to accept Swish payments.
Integration options supported : Hosted payment page (HPP) or IFRAME.
This guide requires familiarity with Accepting payments.
How to decide to use mCommerce or eCommerce flows?
- Paying with Swish in an Android/iOS app: Use the mCommerce flow and switch to the Swish app automatically without human interaction.
- Paying with Swish in a web browser on Android/iOS: Use the mCommerce flow and switch to the Swish app automatically without human interaction.
- Paying with Swish in a web browser on desktop: Use the eCommerce flow where the user inputs their phone number to start the payment.
In case of eCommerce flow, the app_phone_number field is required. In case of mCommerce, it is not.
Integrate Swish via Checkout (HPP)
| Parameters | Type | Required | Description |
|---|---|---|---|
| entity_id | String | Yes | Entity ID obtained from Verifone Central. The Entity ID can be found in Verifone Central, under Administration → Organisations. The 'Organisation ID' listed is the Entity ID. |
| currency_code | String | Yes | Supported currency: SEK |
| amount | integer | Yes | Transaction amount - The minimum value accepted is "100" (1 SEK) |
| configuration.swish | Object | Yes | Object carrying the parameters required for making a Swish payment |
| app_phone_number | String | No |
Indicates the phone number registered with Swish Mobile App. Customer can provide the phone number in the checkout page. |
| shopper_interaction | String | No |
Shopper interaction to send within the payment request. Default value : "ECOMMERCE" Enum: "ECOMMERCE" "MCOMMERCE" Shopper interaction to send within the payment request. |
Authorization and capture
Swish transactions through the Checkout can be used to do a sale through automatic capture.
Sending a checkout request using Swish payment method:
{
"currency_code": "SEK",
"entity_id": "b42d5c50-e6bf-4499-b20d-b36bdcbea4ba",
"customer": "51c11df6-2e43-44e4-95dd-598ffe6e4361",
"configurations": {
"swish": {
"app_phone_number": "46740555072",
"shopper_interaction": "ECOMMERCE"
}
},
"amount": 1,
"merchant_reference": "Order-1111",
"interaction_type": "HPP"
}Handling responses
Example of successful checkout via the Checkout:
[
{
"type": "TRANSACTION_INITIATED",
"id": "41fc9ea6-b01f-42dd-96ab-2cf50dbce26a",
"timestamp": "2021-10-20T09:21:38.429Z",
"details": {
"amount": 850,
"blocked": false,
"created_at": "2021-10-20T09:21:37.75308Z",
"customer": "4b32a5ef-dd84-45ba-81ae-f676ef032580",
"details": {},
"merchant_reference": "103b0aab-5e2c-4b68-9d18-09eb4411bca7",
"status": "INITIATED",
"shopper_interaction": "ECOMMERCE",
"geo_location": [
28.6327,
77.2198
],
"city": "New Delhi",
"country_code": "NL",
"id": "502ace6c-f25c-49b5-8f85-ec290fa781f8",
"processor": "SWISH",
"payment_product": "SWISH",
"payment_product_type": "Swish"
}
},
{
"type": "TRANSACTION_SUCCESS",
"id": "de504bb2-1818-4de9-8422-64cc09773370",
"timestamp": "2021-10-20T09:23:09.238Z",
"details": {
"id": "502ace6c-f25c-49b5-8f85-ec290fa781f8",
"processor_reference": null,
"status": "SETTLED",
"authorization_code": null,
"cvv_result": null,
"details": {
"mid": null
},
"reason_code": null,
"rrn": null,
"stan": null,
"additional_data": {
"acquirer_response_code": null,
"initiator_trace_id": null
}
}
}
]
Example of failed Swish payment via the Checkout:
[
{
"type": "TRANSACTION_DECLINED",
"id": "8b512de7-9ad1-4c9f-a189-8c91c2b53690",
"timestamp": "2021-10-20T09:26:52.504Z",
"details": {
"id": "0a1f3875-524b-406f-afd7-0cf0b7461da3",
"processor_reference": null,
"status": "DECLINED",
"authorization_code": null,
"cvv_result": null,
"details": {
"mid": null
},
"reason_code": null,
"rrn": null,
"stan": null,
"additional_data": {
"acquirer_response_code": null,
"initiator_trace_id": null
}
}
}
]
To ensure that the redirection request was not tampered with, always check that the transaction_id received as query parameter in the redirection matches the transaction_id property of the retrieved Checkout. If those are not matching, this is indication of either an incorrect integration, that the redirection to your return_url did not originate from Verifone, or transaction_id was tampered with.
You can now store the transaction_id value together with the order 1234 in your system to link the two together.
Scenarios
The table below describes the different outcomes of a Checkout. A full list of error codes is available.
| Description | Result | Merchant action |
|---|---|---|
| Transaction is not completed in three minutes by the customer from the Swish app | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} & errorCode=123 | Checkout page will get timed out with a 504 Timeout error. And we will initiate a technical reversal. |
| Failed transaction* | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} & errorCode=123 | Unsuccessful payment (technical reason), do not display order confirmation |
| Successful transaction | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} | Display order confirmation |
| Customer visits the URL of an already completed Checkout | Redirect: checkout_id={checkout_id} & errorCode=168 | Display corresponding message to the customer. Checkout is completed whenever there was a single successful payment processed through it. |
| Customer visits the URL of an expired Checkout | Redirect: checkout_id={checkout_id} & errorCode=169 | Display corresponding message to the customer. Checkout is expired whenever the expiry_time is reached. |
| Customer visits the URL of a Checkout which has reached the maximum of failed payment attempts | Redirect: checkout_id={checkout_id} & errorCode=165 | Display corresponding message to customer. Payments through a single Checkout can be attempted up to three times unsuccessfully. |
| Form validation errors / Other service failures on the Checkout page | Displays error alert to Customer on the page | Customer is prompted to correct their form input and retry the payment or try using alternate card or another payment method |
*Failed transaction - Depending on which step in the payment process failed, the transaction_id might not always be present as the query parameter.
Rate this article:
