Skip to main content

MobilePay Online API (v1)

Download OpenAPI specification:Download

This is the API spec for MobilePay Online. This can only be used for MobilePay in Finland and Denmark. See the MobilePay Online guide for more details.

Merchants

Delete merchant

The merchant can no longer make payments, and is no longer eligible for subscription fee.

path Parameters
merchantId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Responses

Get merchant

path Parameters
merchantId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Responses

Response samples

Content type
application/json
{
  • "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
  • "externalId": "string",
  • "name": "string",
  • "billingCurrency": "string",
  • "countryCode": "string",
  • "vatNumber": "string",
  • "merchantCategoryCode": 0
}

Get merchants

header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Responses

Response samples

Content type
application/json
{
  • "merchants": [
    ]
}

Create merchant

header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
externalId
required
string non-empty

The PSP's unique id of the merchant.

merchantCategoryCode
required
integer <int32> [ 1 .. 9999 ]

The merchant category code (MCC) is used to classify a business by the types of goods or services it provides. More information here: MCC.

name
required
string [ 1 .. 255 ] characters

The PSP's name of the merchant for billing purposes.

billingCurrency
required
string non-empty

Billing currency of the merchant. Possible values are:
DKK
EUR
SEK
NOK

countryCode
required
string non-empty

Merchant country code e.g. Denmark = DK. Use ISO 3166-1.

vatNumber
required
string non-empty

The VAT number of the merchant.

Responses

Request samples

Content type
application/json
{
  • "externalId": "aarhus-trading-20018",
  • "merchantCategoryCode": 1234,
  • "name": "Gedekid og Smoothies",
  • "billingCurrency": "DKK",
  • "countryCode": "DK",
  • "vatNumber": "11102248"
}

Response samples

Content type
application/json
{
  • "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b"
}

Payments

Update payment authorization

Indicates that a successful authorization has been made, if 'succeeded' is set to true. The user will be shown a confirm message and redirected to RedirectFromMobilePayUrl

path Parameters
paymentId
required
string <uuid>
authorizationAttemptId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
reasonCode
integer <int32>

Reason code describing the reason for the authorization to fail.
Codes:
1000: rejected
1001: rejected, insufficient funds
1003: rejected, card expired
1004: rejected, fraud suspected
1005: rejected, soft blocked
1006: rejected, hard blocked
1007: rejected, web payment disabled for card
1008: soft reject, 3DS stepup required, ThreeDSecureUrl must be supplied
1009: after a successful 3DS stepup, PSP now has crypto and will retry authorization
1010: reject for payment invalidation, don´t forget to also call /invalidate endpoint
2000: error
2001: error, permanent - don't try again
2002: error, temporary - try again
3000: timeout - try again

reasonMessage
string or null

Description of why the authorization failed.

succeeded
required
boolean

Property indicating whether or not the authorization was successful. If false, reason code and reason message are required.

acquirerVatNumber
string or null

The VAT number of the acquirer to uniquely identify the acquirer used for this authorization attempt. Must be given for all reason codes in the 1000 range.
Used for our technical surveillance of the transactions and tracking errors.
Use the format described here: 'https://en.wikipedia.org/wiki/VAT_identification_number'.
Examples:
Clearhaus: DK33749996
Bambora: SE556233942301
Elavon: IE418442
Handelsbanken: SE502007786201
Nets: DK20016175
Swedbank: SE502017775301
Valitor: IS23243
Wirecard: DE201591202

acquirerMerchantId
string or null

The id of the merchant with the acquirer. Must be given for all reason codes in the 1000 range.

acquirerPaymentReference
string or null

The id of the payment with the acquirer. Must be given for all reason codes in the 1000 range.

threeDSecureUrl
string or null <uri>

For reason code 1008 the 3DS (3DSecure) fallback flow is activated. The MobilePay app will open this url in a web view.

Responses

Request samples

Content type
application/json
{
  • "reasonCode": 0,
  • "reasonMessage": "string",
  • "succeeded": true,
  • "acquirerVatNumber": "string",
  • "acquirerMerchantId": "string",
  • "acquirerPaymentReference": "string",
  • "threeDSecureUrl": "http://example.com"
}

Update payment

This endpoint requires approval before it can be used. Please contact developer@vippsmobilepay.com

path Parameters
paymentId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
reservationExpireTimestamp
string or null <date-time>

The timestamp of where the reservation is known to expire. This must be patched when a successful authorization is made. Also it must be patched should the expiration be prolonged. No need to patch it if reservation is captured or cancelled.

redirectFromMobilePayUrl
string or null

The redirect url for the user when the payment is complete. Must be fully qualified url.

Responses

Request samples

Content type
application/json
{
  • "reservationExpireTimestamp": "2019-08-24T14:15:22Z",
  • "redirectFromMobilePayUrl": "string"
}

Cancel payment

path Parameters
paymentId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
cancelIdentifier
required
string non-empty

The PSP's unique id of the cancel to ensure idempotency.

amount
required
integer <int64>

Cancelled amount in minor unit. If the amount is lower than the originally authorized amount, it is a partial cancel.

timestamp
required
string <date-time>

Time of the cancel at the PSP.

Responses

Request samples

Content type
application/json
{
  • "cancelIdentifier": "string",
  • "amount": 0,
  • "timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "cancelId": "43be4d23-a0d9-4b8a-ad81-d5b8587824aa"
}

Capture payment

Create a capture. Multiple can be created. Amount must given in minor units of currency.

path Parameters
paymentId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
captureIdentifier
required
string non-empty

The PSP's unique id for the capture to ensure idempotency

amount
required
integer <int64>

Captured amount in minor unit. If the amount is lower than the originally authorized amount, it is a partial capture.

timestamp
required
string <date-time>

Time of the capture at the PSP.

authorizationAttemptId
string or null <uuid>

Id of the authorization attempt that was authorized. This will ensure that we mark the correct authorization attempt as succeeded.

Responses

Request samples

Content type
application/json
{
  • "captureIdentifier": "string",
  • "amount": 0,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "authorizationAttemptId": "52904e8c-5d19-450f-b4c0-1ba3de8b8bca"
}

Response samples

Content type
application/json
{
  • "captureId": "255ed88a-e063-46f6-943a-5ff3e0fe79ed"
}

Refund payment

Creates a refund. Multiple can be created. Amount must given in minor units of currency.

path Parameters
paymentId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
refundIdentifier
required
string non-empty

PSP's unique id of the refund to ensure idempotency.

amount
required
integer <int64>

Refunded amount in minor unit. If amount is lower than the originally authorized amount, it is a partial refund.

timestamp
required
string <date-time>

Time of the refund at the PSP.

Responses

Request samples

Content type
application/json
{
  • "refundIdentifier": "string",
  • "amount": 0,
  • "timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521"
}

Initiate payment

A payment or checkout always start by initiating the payment. All provided urls MUST be https with TLS 1.2 or better. merchantName and merchantUrl are mandatory because those are used for Dynamic Linking.

header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Request Body schema: application/json
merchantId
required
string <uuid>

Identifier for the Merchant. Originates from the CreateMerchant response.

merchantName
required
string non-empty

The display name of the merchant shown to the end-user. Is used for 'Dynamic Linking'. Must be the same as registered with the merchants Acquirer and in schemes.

merchantLogoUrl
required
string non-empty

The url of the logo shown to the end-user. Must be: 250x250 pixels, png or jpg served over a secure connection, must be https, and publicly available.

merchantOrderId
required
string non-empty

Merchant's order id.

merchantUrl
required
string non-empty

Url of the merchant. Max length 150 char. Is used for 'Dynamic Linking'. If the merchant doesn't have a Url, use VAT number (international format) or use the merchantId from MobilePay, as this will also guarantee uniqueness.

pspReferenceId
required
string [ 1 .. 50 ] characters

PSP's unique reference to payment.

amount
required
integer <int64>

Order amount in minor unit. I.e. 4,95 must be given as 495.

currencyCode
required
string non-empty

Currency of the order. Must be alphabetic or numeric ISO 4217 code. Accepted codes: DKK, EUR, NOK, SEK, USD, GBP, 208, 978, 578, 752, 840, 826

required
Array of objects (CardType)

Allowed card types for the payment, includes callback configuration per card type.

publicKeyId
required
integer <int32>

Id of the public key to be used for exchange of card data.

redirectFromMobilePayUrl
required
string non-empty

Where to redirect the user when the payment is complete. Must be fully qualified URL.

failedPaymentCallbackUrl
string or null <uri>
Default: null

Url to be notified when a payment ends unsuccessful. Must be a fully qualified URL. Must be secured by TLS 1.2.
You're strongly encouraged to only set this property if your service handles the callback returned, i.e. reply with an http status 2xx for valid callbacks.

isCheckout
boolean

Is the payment a Checkout payment which will require the user to pick an address.

addressCallbackUrl
string or null <uri>

Url to make callback with chosen address data for Checkout payment. Request is described here callbacks.

deliveryAddressAllowed
boolean or null

Is it possible to set the delivery address on this particular payment.

deliveryAddressDisallowedReasonCode
integer or null <int32>

Reason code to indicate the reason choosing of delivery address has been disallowed.
1: Reason not given
2: Goods don't require physical delivery
3: 'Pick up at store' already selected in the Webshop
4:'Parcel Shop' already selected in the Webshop
5: Shop will select a parcel shop close to your home

deliveryLimitedTo
Array of strings or null

List of countries in which chosen countries can be. Must be in ISO 3166-1 alfa-2 standard. If empty, no restrictions are imposed.

validUntil
string or null <date-time>

Indicate when the user shouldn't be able to accept the payment anymore (3DS or Checkout payments will override and extend the remaining time with 15min).
If not defined, a default offset of 35 minutes is used. Value, if not null, should be in a valid UTC format, e.g. 2020-04-30T07:35:22.8743886+00:00 or 2020-04-30T07:35+00:00.

autoCapture
boolean

Set to true, if the payment will be automatically captured.
In MobilePay the payment will then be marked as captured immediately after the authorization is successful. If false, you need to mark it as captured as usual.

preferVisaPartOfVisaDankort
boolean

If set to true, the Visa part of the Danish co-branded Visa/Dankort will be preferred over the Dankort part. The card type given in the callback from MobilePay must still be respected.

customerLanguageCode
string or null

Override the default language code for the payment.
Accepted values are DA|EN|FI.

minimumMobilePayUserAge
integer or null <int32> [ 0 .. 150 ]

Optional. The payment will fail if the MobilePay user age is below the given minimum age.

Responses

Request samples

Content type
application/json
{
  • "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
  • "merchantName": "string",
  • "merchantLogoUrl": "string",
  • "merchantOrderId": "string",
  • "merchantUrl": "string",
  • "pspReferenceId": "string",
  • "amount": 0,
  • "currencyCode": "string",
  • "allowedCardTypes": [
    ],
  • "publicKeyId": 0,
  • "redirectFromMobilePayUrl": "string",
  • "failedPaymentCallbackUrl": null,
  • "isCheckout": true,
  • "addressCallbackUrl": "http://example.com",
  • "deliveryAddressAllowed": true,
  • "deliveryAddressDisallowedReasonCode": 0,
  • "deliveryLimitedTo": [
    ],
  • "validUntil": "2019-08-24T14:15:22Z",
  • "autoCapture": true,
  • "preferVisaPartOfVisaDankort": true,
  • "customerLanguageCode": "string",
  • "minimumMobilePayUserAge": 150
}

Response samples

Content type
application/json
{
  • "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  • "redirectToMobilePayUrl": "string",
  • "redirectToMobilePayAppUrl": "string"
}

Simulation

This api is only available for test data.

Simulate user behavior

  1. User enters phone number for payment.
  2. User selects the first eligible card for payment.
  3. User swipes to accept payment.
path Parameters
paymentId
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
phoneNumber
required
string
lastFourDigits
string or null

Optional, if defined the user will select the first eligible card that where the last four digits match.

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "lastFourDigits": "string"
}

PSP Onboarding

Get Credentials

Get IntegratorName, ClientName and Active Status for the specified x-ibm-client-Id

header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Responses

Create Credentials

Generates, saves and returns a x-ibm-client-id and x-ibm-client-secret, used for calling product endpoints

header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Update secret

Generates, replaces and returns a new x-ibm-client-secret

header Parameters
CorrelationId
string

CorrelationId used for logging

x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

Responses