Vipps – Redirect

Introduction

When the payer starts the purchase process, you make a POST request towards Swedbank Pay with the collected Purchase information.
This will generate a payment object with a unique paymentID.
You will receive a Redirect URL to a hosted page.
You need to redirect the payer to the Redirect payment where the payer must push the payment button. This triggers a POST towards Swedbank Pay.
The payer is redirected to a Vipps payment page to enter the mobile number.
Swedbank Pay handles the dialog with Vipps and the payer confirms the purchase in the Vipps app.
To receive the state of the transaction you need to do a GET request containing the paymentID generated in the first step.

You redirect the payer to collect the payer’s mobile number.

steps of the vipps purchase flow

Step 1: Create A Purchase

Callback URL: It is mandatory to set a callbackUrl in the POST request creating the payment. When callbackUrl is set, Swedbank Pay will send a POST request to this URL when the payer has fulfilled the payment. Upon receiving this POST request, a subsequent GET request towards the id of the payment generated initially must be made to receive the state of the transaction.

GDPR: GDPR sensitive data such as email, phone numbers and social security numbers must not be used directly in request fields such as payerReference. If it is necessary to use GDPR sensitive data, it must be hashed and then the hash can be used in requests towards Swedbank Pay.

A Purchase payment is a straightforward way to charge the the payer. Below you will see the POST request you will need to send to collect the purchase information.

Redirect Request

Request

1
2
3

POST /psp/vipps/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "NOK",
        "prices": [
            {
                "type": "Vipps",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "hostUrls": [ "https://example.net" ],
            "completeUrl": "https://example.net/payment-completed",
            "cancelUrl": "https://example.net/payment-cancelled",
            "callbackUrl": "https://example.net/payment-callback",
            "logoUrl": "https://example.net/payment-logo.png",
            "termsOfServiceUrl": "https://example.net/payment-terms.pdf",
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "prefillInfo": {
            "msisdn": "+4792345678"
        }
    }
}

Redirect Response

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{
    "payment": {
        "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "instrument": "Vipps",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Ready",
        "currency": "NOK",
        "amount": 0,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "prices": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
        "transactions": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "authorizations": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations" },
        "reversals": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
        "cancellations": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" },
        "urls": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "payeeInfo": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
        "payers": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "settings": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/vipps/payments/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "rel": "update-payment-abort"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/vipps/payments/authorize/8fb05a835f2fc227dc7bca9abaf649b919ba8a572deb448bff543dd5806dacb7",
            "rel": "redirect-authorization"
        }
    ]
}

Show fields

Field	Type	Description
`payment`	`object`	The `payment` object contains information about the specific payment.
`operation`	`string`	The operation that the `payment` is supposed to perform. The `Purchase` operation is used in our example.
`intent`	`string`	`Authorization` is the only intent option for invoice. Reserves the amount, and is followed by a cancellation or capture of funds.
`currency`	`string`	NOK
`prices`	`object`	The `prices` resource lists the prices related to a specific payment.
`type`	`string`	Use the value ``.See the `prices` resource for more information.
`amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` NOK, `5000` = `50.00` NOK.
`vatAmount`	`integer`	The payment’s VAT (Value Added Tax) `amount`, entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` NOK, `5000` = `50.00` NOK. The `vatAmount` entered will not affect the `amount` shown on the payment page, which only shows the total `amount`. This field is used to specify how much of the total `amount` the VAT will be. Set to `0` (zero) if there is no VAT `amount` charged.
`description`	`string(40)`	A 40 character length textual description of the purchase.
`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
`language`	`string`	`sv-SE`, `nb-NO` or `en-US`.
`urls`	`object`	The `urls` resource lists urls that redirects users to relevant sites.
`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A `GET` request needs to be performed on the payment to inspect it further. See `completeUrl` for details.
`cancelUrl`	`string`	The URL to redirect the payer to if the payment is cancelled. Only used in redirect scenarios. Can not be used simultaneously with `paymentUrl`; only cancelUrl or `paymentUrl` can be used, not both.
`callbackUrl`	`string`	The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment. See callback for details.
`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
`payeeId`	`string`	This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(30)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.
`payeeName`	`string`	The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
`productCategory`	`string(50)`	A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process.
`orderReference`	`string(50)`	The order reference should reflect the order reference found in the merchant’s systems.
`subsite`	`string(40)`	The `subsite` field can be used to perform a split settlement on the payment. The different `subsite` values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown `subsite` value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of `A-Za-z0-9`.
`payer`	`string`	The `payer` object, containing information about the payer.
`payerReference`	`string`	The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if `generateRecurrenceToken`, `RecurrenceToken`, `generatePaymentToken` or `paymentToken` is `true`.
`prefillInfo`	`object`	An object that holds prefill information that can be inserted on the payment page.
`msisdn`	`string`	Number will be prefilled on payment page, if valid. Only Norwegian phone numbers are supported. The country code prefix is +47

Step 2: Authorization

To create an authorization in the redirect flow, simply perform an HTTP redirect of the payer towards the URL in the href of the redirect-authorization operation found in the list of operations in the response from the creation of the payment.

Once the payment is successfully authorized, the payer is returned to either the completeUrl or the cancelUrl; depending on the action performed. On the page as well as in the callbackUrl you need to perform an HTTP GET request towards the id of the payment to inspect its status.

Step 3: Get The Transaction State

The GETrequest below will give you the transaction state of the payment. The paymentId used below was provided in the fist step when creating a purchase.

GET Transaction State Request

Request

1
2
3
4

GET /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "NOK",
        "prices": [
            {
                "type": "Vipps",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "hostUrls": [ "https://example.net" ],
            "completeUrl": "https://example.net/payment-completed",
            "cancelUrl": "https://example.net/payment-cancelled",
            "callbackUrl": "https://example.net/payment-callback",
            "logoUrl": "https://example.net/payment-logo.png",
            "termsOfServiceUrl": "https://example.net/payment-terms.pdf",
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "prefillInfo": {
            "msisdn": "+4792345678"
        }
    }
}

GET Transaction State Response

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

{
    "payment": {
        "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "state": "Ready",
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "NOK",
        "amount": 1500,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "prices": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
        "payeeInfo": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
        "payers": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "urls": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "transactions": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "authorizations": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations" },
        "captures": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures" },
        "reversals": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
        "cancellations": { "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" }
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/vipps/core/scripts/client/px.vipps.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&operation=authorize",
            "rel": "view-authorization",
            "contentType": "application/javascript"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/vipps/core/scripts/client/px.vipps.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&operation=authorize",
            "rel": "view-payment",
            "contentType": "application/javascript"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/vipps/payments/authorize/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "rel": "redirect-authorization",
            "contentType": "text/html"
        },
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
            "rel": "create-capture",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/vipps/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid",
            "rel": "paid-payment",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/vipps/7e6cdfc3-1276-44e9-9992-7cf4419750e1/failed",
            "rel": "failed-payment",
            "contentType": "application/problem+json"
        }
    ]
}

Show fields

Field	Type	Description
`payment`	`object`	The `payment` object contains information about the specific payment.
`id`	`string`	The relative URL and unique identifier of the `payment` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`number`	`integer`	The payment `number`, useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, where `id` should be used instead.
`created`	`string`	The ISO-8601 date of when the payment was created.
`updated`	`string`	The ISO-8601 date of when the payment was updated.
`state`	`string`	`Ready`, `Pending`, `Failed` or `Aborted`. Indicates the state of the payment, not the state of any transactions performed on the payment. To find the state of the payment’s transactions (such as a successful authorization), see the `transactions` resource or the different specialized type-specific resources such as `authorizations` or `sales`.
`prices`	`object`	The `prices` resource lists the prices related to a specific payment.
`prices.id`	`string`	The relative URL and unique identifier of the `prices` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`description`	`string(40)`	A 40 character length textual description of the purchase.
`payers`	`string`	The URL to the `payer` resource where the information about the payer can be retrieved.
`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
`language`	`string`	`sv-SE`, `nb-NO` or `en-US`.
`urls`	`string`	The URL to the urls resource where all URLs related to the payment can be retrieved.
`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
`operations`	`array`	The array of operations that are possible to perform on the payment in its current state.
`method`	`string`	The HTTP method to use when performing the operation.
`href`	`string`	The target URL to perform the operation against.
`rel`	`string`	The name of the relation the operation has to the current resource.

Vipps Redirect Sequence Diagram

The sequence diagram below shows the two requests you have to send to Swedbank Pay to make a purchase. The links will take you directly to the API description for the specific request.

sequenceDiagram
    participant Browser
    participant Merchant
    participant SwedbankPay as Swedbank Pay
    participant VippsApi as Vipps API
    participant VippsApp as Vipps App

    Browser->>Merchant: Start purchase (pay with Vipps)
    activate Browser
    activate Merchant
    Merchant->>SwedbankPay: POST <Create  Vipps payment>
    activate SwedbankPay
    note left of Merchant: First API request
    SwedbankPay-->>Merchant: Payment resource
    deactivate SwedbankPay
    Merchant-->>Browser: Redirect to payment page
    deactivate Merchant

    note left of Browser: Redirect to Swedbank Pay
    Browser->>SwedbankPay: Redirect
    activate SwedbankPay
    SwedbankPay-->>VippsApi: Initialize Vipps payment
    activate VippsApi
    VippsApi-->>SwedbankPay: Response
    activate SwedbankPay
    SwedbankPay-->>-Browser: Display payment page
    activate Browser
    Browser->>Browser: Enter mobile number
    SwedbankPay-->>Browser: Authorization response (State=Pending)
    note left of Browser: Check your phone

    VippsApi-->>VippsApp: Confirm Payment UI
    activate VippsApp
    VippsApp-->>VippsApp: Confirmation dialog
    VippsApp-->>VippsApi: Confirmation
    deactivate VippsApp

    VippsApi-->>SwedbankPay: Make payment
    activate SwedbankPay
    SwedbankPay-->>SwedbankPay: Execute payment
    SwedbankPay-->>VippsApi: Response
    deactivate SwedbankPay
    deactivate VippsApi

    SwedbankPay-->>SwedbankPay: Authorize result
    SwedbankPay-->>Browser: Authorize result
    deactivate SwedbankPay

    Browser-->>Merchant: Redirect to merchant
    activate Merchant
    note left of Browser: Redirect to merchant

        alt Callback
        activate SwedbankPay
        SwedbankPay-->>-VippsApi: Callback response
        SwedbankPay->>-Merchant: Transaction callback
        end

    activate SwedbankPay
    Merchant-->>SwedbankPay: GET <payment.id>
    note left of Merchant: Second API request
    SwedbankPay-->>Merchant: Payment resource
    Merchant-->>Browser: Display purchase result
    deactivate SwedbankPay
    deactivate Merchant
    deactivate Browser

You will later (i.e. if a physical product, when you are ready to ship the purchased products) have to make a Capture or Cancel request.