Skip to main content

Online Payments

Vipps

Last updated: 18-Apr-2022
Rate this article:

Overview

Checkout can be used to accept Vipps payments.

This guide requires familiarity with Accepting payments.

Integrate Vipps via Checkout (HPP)

Parameters Type Required Description
currency_code String Yes Supported currencies: NOK
amount Integer Yes Transaction amount
customer String Yes ID of a Customer created via the Customer API. A customer object can be created and attached to a Checkout.
configurations.vipps Object Yes Object carrying the parameters required for making a Vipps payment

payment_contract_id

String Yes This ID can be found in the portal or given to you by a Verifone employee. It is used to retrieve a merchant's Vipps credentials necessary for payment.

dynamic_descriptor

String No Short text to be displayed on the bank statement of the cardholder. Support varies per Payment Contract.

capture_now

Boolean No Used for separate authorization and capture

is_app

Boolean No Flag to identify the transaction originated from APP or Browser

app_phone_number

String No Indicates the phone number registered with Vipps Mobile APP

card

Object  No Details regarding SCA compliance Required, 3DS Required and authorization type Required

authorization_type

String No Card Authorization Type (PRE_AUTH, FINAL_AUTH). When capture_now is set to true, pre-authorization transactions cannot be done.

Authorization and capture

You can use Vipps transactions through the Checkout to do a sale (capture_now = true) or to authorize without capturing immediately (capture_now = false). An authorized payment reserves the money and allows you to capture the funds at a later stage.

Sending a checkout request using Vipps payment method:

{

    "currency_code": "NOK",
    "entity_id": "466c5c59-5177-45c2-b9a7-41ac422ef1fa",
    "customer": "deebacec-cd75-4ce5-9641-bfc40de5710d",
    "configurations": {
        "vipps": {
            "dynamic_descriptor": "Test Product",
            "capture_now": true,
            "payment_contract_id": "98a003be-03f2-43c4-a89c-36021fa63635",
            "app_phone_number": "40950037",
            "card": {
                "sca_compliance_level": "WALLET",
                "authorization_type": "FINAL_AUTH",
                "threed_secure": {
                    "enabled": true,
                    "threeds_contract_id": "76c87838-610e-40cf-8434-c91debb7cfd9",
                    "total_items": "01",
                    "transaction_mode": "S"
                }
            }
        }
    },
    "amount": 4300,
    "merchant_reference": "Test",
    "return_url": "http://enbyhy7yz2lg98r.m.pipedream.net",
    "interaction_type": "HPP"

}

Handling responses

Whenever a card payment is processed via the Checkout, the responses events include additional parameters specific to card payments in the Details object.

Example of a successful Vipps payment via the Checkout:

[

    {

        "type": "TRANSACTION_INITIATED",
        "id": "8de44848-c9eb-48c1-bafe-ba97bf3fb77f",
        "timestamp": "2021-09-15T12:03:55.368Z",
        "details": {

            "amount": 400,
            "created_at": "2021-09-15T12:03:55.071859Z",
            "customer": "deebacec-cd75-4ce5-9641-bfc40de5710d",
            "details": {},
            "merchant_reference": "f811eb59-9fb6-4ac0-a0ee-df36e8e0fe4f",
            "status": "INITIATED",
            "shopper_interaction": "ECOMMERCE",
            "geo_location": [
                20.0063,
                77.006
            ],
            "country_code": "FI",
            "id": "03732287-5fca-4e63-baa7-9f059af58a62",
            "redirect_url": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJraWQiOiJqd3RrZXkiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJmMDE0MmIxYy02YjIwLTQ1M2MtYTlmMS1lMWUwZGFiNjkzOTciLCJubyI6eyJoZWFkZXIiOiJCZXRhbCIsImNvbnRlbnQiOiI0IGtyIHRpbCBURVNUVklQUFNFQ09NMSJ9LCJtb2IiOiI0MDk1MDAzNyIsImN0eCI6ImM0YjZhNWM5LWI4ODktNGRhMC05MWNmLTAxYjQ4MDU4MDI4ZSIsIm1lcmNoYW50U2VyaWFsTnVtYmVyIjoiMjI2NTYzIiwiaXNzIjoiaHR0cHM6XC9cL1ZJUFBTLU1ULUNPTi1BR0VOVC1pbGIudGVjaC0wMi5uZXRcL210MVwvZGVlcGxpbmstb3BlbmlkLXByb3ZpZGVyLWFwcGxpY2F0aW9uXC8iLCJlbiI6eyJoZWFkZXIiOiJQYXkiLCJjb250ZW50IjoiNCBrciB0byBURVNUVklQUFNFQ09NMSJ9LCJ0eXBlIjoiUFNQX1BBWU1FTlQiLCIxZmEiOiJ0cnVlIiwidXVpZCI6ImQzMGUxZTViLTg3MTgtNDFiMC04Y2ZjLTViNDM3ZTBjMzZiYyIsInVybCI6Imh0dHBzOlwvXC9hcGl0ZXN0LnZpcHBzLm5vXC9sYW5kaW5ncGFnZVwvZHdvXC92MVwvbGFuZGluZ3BhZ2UiLCJyZWZlcmVuY2VJZCI6ImY4MTFlYjU5LTlmYjYtNGFjMC1hMGVlLWRmMzZlOGUwZmU0ZiIsImF1ZCI6ImYwMTQyYjFjLTZiMjAtNDUzYy1hOWYxLWUxZTBkYWI2OTM5NyIsImF6cCI6ImYwMTQyYjFjLTZiMjAtNDUzYy1hOWYxLWUxZTBkYWI2OTM5NyIsImFwcFR5cGUiOiJMQU5ESU5HUEFHRSIsIm5vRWRpdCI6ZmFsc2UsImV4cCI6MTYzMTcwNzczNSwidG9rZW5UeXBlIjoiREVFUExJTksiLCJpYXQiOjE2MzE3MDc0MzUsImZhbGxiYWNrIjoiaHR0cHM6XC9cL2Rldi5jaGVja291dC52Zmltcy5jb21cL3YyXC9jaGVja291dFwvYWIwYTEzNGEtYjI5Zi00YzhjLThjYWQtOTIzMjkwOTkzNGFmXC9yZXR1cm4iLCJqdGkiOiIzMGZjOTczNy1jY2NiLTRhNDgtYWJiZS0zMjdkM2MwOWU2OTMifQ.Wt48XLuOu0t_2J8xKxaesU9fgjtsWGOEy7mPeZ0Sy-A_sjTpV41rUZOUwtJ7zvPc5LHAPr0FbhUAFdN4OBZP54K6X_SE0_Z4xx6GMJOGSj17IRqD2FU01APd7P65kWf5yRj9r3yj8gXpmQmfOF-ASCK9On9-P1_Ki35tcYJNERcjqiGUhEd_1D1OczPWjQv-9Kg2D6AtkMz3aWXbftmakiKHLsBx42groPCLYqCAdxl5xvpVyBc-X2q19IryJ3mIwpHasAZGUEcek2jkoS0kGCVbkBu_gj33yfL6Igr8dxrbj4klLOXk7sMO_bUEf8U-51RiGs8y6XXkScSDyWR3fQ",
            "processor": "NETS",
            "payment_product": "CARD",
            "payment_product_type": "Unknown"

        }

    },

    {

        "type": "TRANSACTION_SUCCESS",
        "id": "1aaebd63-2daf-4753-bc32-bcdb8c35b743",
        "timestamp": "2021-03-31T11:44:07.717Z",
        "details": {

            "id": "fd31890c-8c45-4846-a934-a7faa584e823",
            "captureId": "93459848W31137123",
            "createdAt": "2021-03-31T11:44:06Z",
            "isFinalCapture": true,
            "payer": {
                "payerId": "92FT3NN28KELQ",
                "shippingAddress": {
                    "country": "IN",
                    "postalCode": "100047",
                    "countrySubdivision": "Maharashtra",
                    "city": "Mumbai",
                    "addressLine1": "addressLine1",
                    "addressLine2": "addressLine2",
                }

            },

            "status": "AUTHORISED"
        }

    }

]

Example of a failed Vipps payment via the Checkout:

[

    {

        "type": "TRANSACTION_FAILED",
        "id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
        "timestamp": "2020-07-08T12:42:37.974Z",
        "details": {

              "id": "6d85d047-1e78-4f13-afe2-cc041bce524f",
              "authorizationId": "4PB16132MH590854B",
              "createdAt": "2021-01-06T04:40:30Z",
              "expiresAt": "2021-02-04T04:40:30Z",
              "status": "FAILED",
              "payer": {

                  "payerId": "92FT3NN28KELQ",
                  "shippingAddress": {

                      "country": "IN",
                      "postalCode": "100047",
                      "countrySubdivision": "Maharashtra",
                      "city": "Mumbai",
                      "addressLine1": "addressLine1",
                      "addressLine2": "addressLine2",

                      }

        }

      }

    }

  ]
 
  • Note: 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

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 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:
Logo of Verifone