Skip to main content
API docs by Redocly

App payments

E-mail: developer@vippsmobilepay.com

General notes

All dates use the (ISO 8601-1:2019) format.
Date-time format - YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss+00:00.

Payments

Payments API makes it easy for you to collect money from your customers using MobilePay.

initiate new payment

Authorizations:
apiKeyopenId
header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

Request Body schema: application/json
amount
required
integer <int32>

The amount of money to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge €1.00). The minimum amount is 1. The maximum amount is defined by user's daily/yearly limits.

idempotencyKey
required
string <uuid>

A unique value that identifies this InitiatePayment request. Must be a valid GUID, and is used to protect against accidental duplicate calls. Multiple requests with the same idempotency key have the same result.

paymentPointId
required
string <uuid>

The Payment Point ID to associate with a payment.

redirectUri
required
string [ 0 .. 2000 ] characters

MobilePay will use the redirectUri URL to redirect the MobilePay user to the merchant's confirmation page once user action is completed in MobilePay app. Must be a valid URI.

reference
required
string [ 0 .. 64 ] characters

An ID to associate with the payment. Max length: 64 characters.
You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by your system). It is recommended to use a unique value for each payment.

description
string or null [ 0 .. 200 ] characters

Optional payment information to be displayed in MobilePay app to the customer. Max length: 100 characters.
This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase.

customerPhoneNumber
string or null [ 0 .. 15 ] characters

MobilePay will use the (international) phone number to prefill the landing page for dual device flows. Ex. +4512345678

Responses

Request samples

Content type
application/json
{
  • "amount": 1250,
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "paymentPointId": "7347ba06-95c5-4181-82e5-7c7a23609a0e",
  • "reference": "My-Payment-1",
  • "idempotencyKey": "fae7680f-9875-4ba9-8910-2f2e1791f390",
  • "redirectUri": "myapp://redirect",
  • "customerPhoneNumber": null
}

Response samples

Content type
application/json
{}

fetch a list of payments Deprecated

Returns a list of all merchant's payments if no filters are provided in query parameters. Can also return only payments of a specific payment point if paymentPointId is provided.

Authorizations:
apiKeyopenId
query Parameters
paymentPointId
string <uuid>

Filter payments of a specific payment point

pageNumber
integer <int32> >= 1
Default: 1
pageSize
integer <int32> [ 1 .. 1000 ]
Default: 100

Number of payments to be returned.

stateFilter
Array of strings
Items Enum: "initiated" "reserved" "captureStarted" "captured" "cancelledByMerchant" "cancelledByUser" "cancelledBySystem"

Filter payments by state.

startDate
string <date-time>

Filter payments by InitiatedOn property.

endDate
string <date-time>

Filter payments by InitiatedOn property.

header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

Responses

Response samples

Content type
application/json
{
  • "pageSize": 1,
  • "nextPageNumber": 2,
  • "payments": [
    ]
}

fetch single payment

Authorizations:
apiKeyopenId
path Parameters
paymentid
required
string <uuid>
header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

Responses

Response samples

Content type
application/json
{
  • "paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
  • "amount": 1250,
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "paymentPointId": "7347ba06-95c5-4181-82e5-7c7a23609a0e",
  • "reference": "My-Payment-1",
  • "redirectUri": "myapp://redirect",
  • "state": "initiated",
  • "initiatedOn": "2022-05-26T13:13:49.700315+03:00",
  • "lastUpdatedOn": "2022-05-26T13:13:49.700318+03:00",
  • "merchantId": "655ad36f-70b0-4add-a123-b943daca50e8",
  • "isoCurrencyCode": "DKK",
  • "paymentPointName": "MyPaymentPoint"
}

capture payment

Authorizations:
apiKeyopenId
path Parameters
paymentid
required
string <uuid>
header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

Request Body schema: application/json
amount
required
integer <int32>

The amount to be captured. A positive integer representing how much to capture in the smallest currency unit (e.g., 100 cents to capture €1.00). The minimum amount is 1.

Responses

Request samples

Content type
application/json
{
  • "amount": 0
}

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "correlationId": "91f2b05f-2171-4cea-9d5a-1cdbed6ae2cd",
  • "origin": "MPY"
}

cancel payment

Authorizations:
apiKeyopenId
path Parameters
paymentid
required
string <uuid>
header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

Responses

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "correlationId": "91f2b05f-2171-4cea-9d5a-1cdbed6ae2cd",
  • "origin": "MPY"
}

cancel payment using idempotency key

Authorizations:
apiKeyopenId
header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

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

The idempotency key identifying the payment to be canceled. Only payments in the initiated state can be canceled using the idempotency key.

Responses

Request samples

Content type
application/json
{
  • "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1"
}

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "correlationId": "91f2b05f-2171-4cea-9d5a-1cdbed6ae2cd",
  • "origin": "MPY"
}

simulates payment confirmation

Simulate user swiping and confirming the payment (available only in sandbox environment).

Authorizations:
apiKeyopenId
header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

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

The id of payment source which should be used to obtain funds.

userId
required
string <uuid>

The id of the user on whose behalf funds will be reserved.

Responses

Request samples

Content type
application/json
{
  • "paymentSourceId": "8b1def75-8f77-4a48-8924-bf2ab22251e6",
  • "userId": "be1e6d64-b73d-481a-9947-55e57ccbe4cf"
}

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "correlationId": "91f2b05f-2171-4cea-9d5a-1cdbed6ae2cd",
  • "origin": "MPY"
}

Payment points

fetch a list of payment points

Returns a list of all merchant's payment points.

Authorizations:
apiKeyopenId
query Parameters
pageNumber
integer <int32> >= 1
Default: 1

Values that are less than 1 will be replaced by 1.

pageSize
integer <int32> [ 1 .. 1000 ]
Default: 100

Number of payment points to be returned.

header Parameters
CorrelationId
string <uuid>

Correlation id used for logging (if you don't pass any value, we'll generate it)

Responses

Response samples

Content type
application/json
{
  • "pageSize": 1,
  • "nextPageNumber": 2,
  • "paymentPoints": [
    ]
}

Refunds

Refunds API makes it easy for you to refund payments to your customers. You can refund only those payments that were created via payments API above.

issue new refund

Authorizations:
apiKeyopenId
Request Body schema: application/json
amount
required
integer

The amount of money to refund. A positive integer representing how much to refund in the smallest currency unit (e.g., 100 cents to charge €1.00). The minimum amount is 1. The maximum amount is equal to full payment's amount.

idempotencyKey
required
string <uuid>

A unique value that identifies this request. Must be a valid GUID, and is used to protect against accidental duplicate calls. Multiple requests with the same idempotency key have the same result.

paymentId
required
string <uuid>

The ID of payment for which refund will be issued.

reference
required
string [ 0 .. 64 ] characters

An ID to associate with the refund. Max length: 64 characters.
You can use this field to associate the refund to an entity in an external system (for example, you might specify an order ID that is generated by your system). It is recommended to use a unique value for each refund.

description
string or null [ 0 .. 200 ] characters

Optional refund information to be displayed in MobilePay app to the customer. Max length: 200 characters.
This can be, for example, an invoice number, ticket number, or short description of the refund.

Responses

Request samples

Content type
application/json
{
  • "paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
  • "amount": 1250,
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "reference": "My-Refund-1",
  • "idempotencyKey": "fae7680f-9875-4ba9-8910-2f2e1791f390"
}

Response samples

Content type
application/json
{
  • "refundId": "7576910d-9789-4fef-a72e-877d89afec94",
  • "paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
  • "amount": 1250,
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "reference": "My-Refund-1",
  • "createdOn": "2021-07-19T12:42:38+00:00",
  • "remainingAmount": 250
}

fetch a list of refunds Deprecated

Authorizations:
apiKeyopenId
query Parameters
paymentId
string <uuid>

Filter refunds of specific payment

paymentPointId
string <uuid>

Filter refunds of specific payment point

pageNumber
integer >= 1
Default: 1

Values that are less than 1 will be replaced by 1.

pageSize
integer [ 1 .. 1000 ]
Default: 100

Number of refunds to be returned.

createdBefore
string <date-time>

Filter refunds by CreatedOn property.

createdAfter
string <date-time>

Filter refunds by CreatedOn property.

Responses

Response samples

Content type
application/json
{
  • "pageSize": 0,
  • "nextPageNumber": 0,
  • "refunds": [
    ]
}

fetch single refund

Authorizations:
apiKeyopenId
path Parameters
refundid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "refundId": "7576910d-9789-4fef-a72e-877d89afec94",
  • "paymentId": "186d2b31-ff25-4414-9fd1-bfe9807fa8b7",
  • "amount": 1250,
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "reference": "My-Refund-1",
  • "createdOn": "2021-07-19T12:42:38+00:00",
  • "paymentPointId": "7347ba06-95c5-4181-82e5-7c7a23609a0e",
  • "merchantId": "655ad36f-70b0-4add-a123-b943daca50e8",
  • "isoCurrencyCode": "DKK"
}