Skip to main content

Migration guide

đź’Ą Work in progress đź’Ą

Are you currently using MobilePay APIs for your payment integration needs?

In that case, we’re excited to introduce you to Vipps MobilePay APIs, a reliable and versatile payment solution that can make the migration hassle-free and even dazzle you with its ease of use and features. To ensure a smooth transition, we recommend using our comprehensive migration guide, which will provide step-by-step instructions and best practices for integrating with Vipps MobilePay APIs.

This document is still under development. Here is a quick summary of key facts and shortcuts for our APIs​.

Subscriptions vs. Recurring​

API documentation:

Agreement​

See: Agreements.

MOBILEPAY AGREEMENT ​VIPPS MOBILEPAY AGREEMENT​
Description ​productDescription​
Amount​pricing: { "type"("LEGACY" => amount ,"VARIABLE" => suggestedMaxAmount), "currency"("NOK") } ​
Frequency​interval: { "unit"("YEAR" "MONTH" "WEEK" "DAY"), "count"([1..31]) } ​
Links: [user-redirect, success-callback, cancel-callback, cancel-redirect] merchantRedirectUrl + merchantAgreementUrl​
Plan​productName​
mobile_phone_number​phoneNumber​
external_id​externalId​
currency​N/A
country_code​N/A
expiration_timeout_minutes​N/A
retention_period_hours​N/A
disable_notification_management​N/A
notifications_on​N/A
N/Ascope (Space separated list of the user profile-data scope to require for the agreement)​
N/AisApp (If merchant is redirecting user from an app or a mobile device)​
N/AskipLandingPage (true = skip landing page by sending notification directly to user)​

Charges​

See: Charges.

MobilePay one-off​Vipps MobilePay initial charge
Amount (kroner.øre) ​Amount (øre)​
External_id​OrderId (if NULL → autogenerated)​
Description​Description​
Expiration_timeout_minutes​N/A
N/AtransactionType (RESERVE_CAPTURE, DIRECT_CAPTURE)​
MOBILEPAY RESPONSE FROM AGREEMENTVIPPS MOBILEPAY RESPONSE FROM AGREEMENT
IdagreementId
links["rel", "href"]vippsConfirmationUrl
one_off_payment_idchargeId

Invoice vs. ePayment​

See:

Please note that "ePayments" encompasses various use case scenarios. Therefore, if you are seeking use cases that target existing MobilePay merchants and can be utilized for migration purposes, some examples include:

MobilePay invoiceVipps Mobilepay ePayment
InvoiceIssuer​Merchant-Serial-Number (Header in request) ​
ConsumerAlias {Alias, AliasType} ​Customer {Alias} (Example: 4512345678)
TotalAmount​Amount {currency, value(øre)}​
InvoiceNumber / PaymentReference​reference / paymentDescription ​
DueDate​expiresAt (10min → 28 days. Example: 2023-02-26T17:32:28)​
(InvoiceLink) RedirectUrl ​returnUrl (The URL the user is redirected to after the payment session).​
Comment​N/A
ConsumerAddressLines []N/A
DeliveryAddressLines []N/A
ConsumerName​N/A
TotalVATAmount​N/A
IssueDateN/A
OrderDateN/A
OrderDateN/A
DeliveryDate​N/A
MerchantContactNameN/A
MerchantOrderNumberN/A
BuyerOrderNumber​N/A
InvoiceUrl+ InvoiceArticles []​See Order Management API
N/A ​paymentDescription​
N/Aprofile (scope)​
N/A ​paymentMethod (WALLET or CARD. CARD → WEB_REDIRECT)​
N/AuserFlow (Push_message, Native_redirect, Web_redirect, QR) ​
N/AqrFormat {format, size} (only applicable when userFlow is set to QR) ​
N/AcustomerInteraction (Customer_present, Customer_not_present)​
N/AindustryData (Additional compliance data related to the transaction)​

Point of Sale vs. ePayment​

See:

PoS and ePayment endpoints​

OperationMobilePay PoSePayment
PoS managementPOST/GET/DELETE /v10/pointofsalesN/A
Initiate PaymentPOST:/v10/paymentsPOST:/v1/payments
Initiate Prepared paymentPOST:/v10/payments/prepareN/A (For loyalty check solutions)
Query PaymentGET:/v10/payments/{paymentid}GET:/v1/payments/{reference}
Query Active PaymentsGET /v10/paymentsN/A
Query payment logN/AGET:/v1/payments/{reference}/events
Capture PaymentPOST:/v10/payments/{paymentid}/capturePOST:/v1/payments/{reference}/capture
Cancel PaymentPOST:/v10/payments/{paymentid}/cancelPOST:/v1/payments/{reference}/cancel
Refund PaymentPOST:/v10/refundsPOST:/v1/payments/{reference}/refund
Lookup a refundGET:/v10/refunds/{refundid}GET:/v1/payments/{reference}

PoS Authentication and headers​

MobilePay PoSePayment
Authorization (POST:/connect/token)Authorization (POST:/accesstoken/get)
X-MobilePay-Client-System-VersionVipps-System-Version
N/AVipps-System-Name
N/AVipps-System-Plugin-Name (if applicable)
N/AVipps-System-Plugin-Version (if applicable)
X-MobilePay-Merchant-VAT-NumberN/A
X-MobilePay-Idempotency-KeyIdempotency-Key
N/AOcp-Apim-Subscription-Key
N/AMerchant-Serial-Number

PoS Initiate Payment​

MobilePay PoSePayment
amountamount (currency, value)
currencyCodeApplied in amount
orderIdpaymentDescription
plannedCaptureDelayN/A
posIdN/A
restrictions (debitCardDisallowed, creditCardDisallowed)N/A
merchantPaymentLabelN/A
N/Acustomer (phoneNumber)
N/AcustomerInteraction ("CUSTOMER_PRESENT")
N/ApaymentMethod (type "WALLET")
N/Areference
N/AuserFlow ("PUSH_MESSAGE" "QR")
N/AqrFormat (format, size)
Response
paymentIdreference (set in paymentInitiation)

PoS Query Payment​

MobilePay PoSePayment
paymentIdreference
Response
orderIdreference
amountamount (currency, value)
currencyCodeApplied in amount
statusstate
N/Aaggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
N/ApaymentMethod (type)
loyaltyIdsprofile (sub)
N/ApspReference

N/A: posId, restrictions (debitCardDisallowed, creditCardDisallowed), merchantPaymentLabel, plannedCaptureDelay, customerToken, customerReceiptToken, paymentExpiresAt, partialCapturePossible, pollDelayInMs)

PoS Capture, Cancel and Refund Payment​

MobilePay PoSePayment
paymentIdreference
amountmodificationAmount (currency, value) not applicable for cancel
Response
N/Aamount (currency, value)
N/Astate
N/Aaggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
refundId only applicable for refundpspReference
N/Areference