Skip to main content

Online API (v1)

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Get merchant

path Parameters
merchantId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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,
  • "platformId": "32a6e381-64f4-4911-86b6-3bf681b64d23"
}

Update merchant

Update properties on a given merchant. Only provided values will be updated.

path Parameters
merchantId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
externalId
string or null

The PSP's unique id for the merchant.

merchantCategoryCode
integer or null <int32>

The MCC is used to classify a business by the types of goods or services it provides. More information here 'https://en.wikipedia.org/wiki/Merchant_category_code'.

name
string or null

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

billingCurrency
string or null

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

countryCode
string or null

Merchant country code e.g. Denmark = DK. Use ISO-3166 ('https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2') or special value APAC.

vatNumber
string or null

The VAT number of the merchant.

platformId
string or null <uuid>

Optional unique id of Platform

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "merchantCategoryCode": 0,
  • "name": "string",
  • "billingCurrency": "string",
  • "countryCode": "string",
  • "vatNumber": "string",
  • "platformId": "32a6e381-64f4-4911-86b6-3bf681b64d23"
}

Get merchants

header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Response samples

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

Create merchant

header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
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 ('https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2') or special value APAC.

externalId
required
string non-empty

The PSP's unique id of the merchant.

name
required
string [ 1 .. 255 ] characters

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

merchantCategoryCode
integer or null <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 'https://en.wikipedia.org/wiki/Merchant_category_code'.

vatNumber
string or null

The VAT number of the merchant.

platformId
string or null <uuid>

Optional unique id of Platform

Responses

Request samples

Content type
application/json
{
  • "externalId": "aarhus-trading-20018",
  • "merchantCategoryCode": 1234,
  • "name": "Gedekid og Smoothies",
  • "billingCurrency": "DKK",
  • "countryCode": "DK",
  • "vatNumber": "11102248",
  • "platformId": "32a6e381-64f4-4911-86b6-3bf681b64d23"
}

Response samples

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

Payments

Get payment

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Response 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": [
    ],
  • "preferVisaPartOfVisaDankort": true,
  • "publicKeyId": 0,
  • "redirectFromMobilePayUrl": "string",
  • "deliveryAddressAllowed": true,
  • "deliveryAddressDisallowedReasonCode": 0
}

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
succeeded
required
boolean

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

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 succesfull 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.

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

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

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

cancelIdentifier
required
string non-empty

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

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

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

captureIdentifier
required
string non-empty

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

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

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

refundIdentifier
required
string non-empty

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

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
required
Array of objects (CardType)

Allowed card types for the payment, includes callback configuration per. card type. See CardType./>.

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

merchantId
required
string <uuid>

Identifier for the Merchant. Originates from the CreateMerchant response.

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.

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.

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 non-empty

PSP's unique reference to payment.

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 'https://github.com/MobilePayDev/MobilePay-Online#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 parcelshop 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"
}

Invalidate payment

Invalidate the payment if a successful authorization hasn't been made. Invalidation means that the user cannot accept or create a request on this payment.

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Recurring Payments

Terminate agreement

query Parameters
agreementId
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Create agreement

header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

External id of the agreement.

merchantId
required
string <uuid>

The id of the merchant. Originates from the 'CreateMerchant' response.

merchantLogoUrl
required
string <uri>

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.

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 merchant's acquirer and in schemes.

merchantWebsiteUrl
required
string <uri>

Merchant website url.

recurringAgreementCallbackUrl
required
string <uri>

Url to be called with agreement state changes. Contains AgreementId and State. Must be https, and publicly available.

updateCardCallbackUrl
required
string <uri>

Called when user requests a card change on agreement. Must be resolved as either accepted or rejected by return call.
Must support a http(s) POST callback request with a JSON payload of types
* EncryptedCardUpdateCallbackPayload
* VisaTokenCallbackPayload
* MastercardTokenCallbackPayload
Please resolve by return call via 'PATCH api/v3/recurring/{agreementId}/card/{paymentId}'.

selfServiceUrl
string or null <uri>

Optional url for merchant self service. Must be https, and publicly available.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "recurringAgreementId": "32484295-ba94-499b-a4e2-3ab87e69ca0c"
}

Get agreement

path Parameters
agreementId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
application/json
{
  • "recurringAgreementId": "32484295-ba94-499b-a4e2-3ab87e69ca0c",
  • "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
  • "merchantName": "string",
  • "merchantLogoUrl": "http://example.com",
  • "externalAgreementId": "string",
  • "merchantWebsiteUrl": "http://example.com",
  • "selfServiceUrl": "http://example.com",
  • "recurringAgreementCallbackUrl": "http://example.com",
  • "updateCardCallbackUrl": "http://example.com",
  • "accountVerificationPaymentId": "f14d17c6-c6fe-4f38-8e1e-a8ec5661ca8b"
}

Get MIT payment details

path Parameters
mitPaymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Response 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": [
    ]
}

Update agreement

path Parameters
recurringAgreementId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
merchantLogoUrl
string or null <uri>

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.

merchantWebsiteUrl
string or null <uri>

Merchant website url.

selfServiceUrl
string or null <uri>

Url for merchant self service. Must be https, and publicly available.

recurringAgreementCallbackUrl
string or null <uri>

Url to be called with agreement state changes. Contains AgreementId and State. Must be https, and publicly available.

updateCardCallbackUrl
string or null <uri>

Url to be called when user changes card on agreement. Contains AgreementId and token/encrypted card data. Must be https, and publicly available.

Array of objects or null (CardType)

Allowed card types for the payment, includes callback configuration per. card type. See CardType./>.

Responses

Request samples

Content type
application/json
{}

Confirm or reject card update

Confirm or reject requested card update on agreement

path Parameters
agreementId
required
string <uuid>
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
succeeded
required
boolean

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

reasonCode
integer <int32>

Reason code describing the reason for the card update 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 succesfull 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 card update failed.

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.

acquirerVatNumber
string or null

The VAT number of the acquirer to uniquely identify the acquirer used for this card update. 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.

Responses

Request samples

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

Update MIT payment

Update MIT on recurring agreement. Indicates that a successful authorization has been made, if 'succeeded' is set to true.

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
succeeded
required
boolean

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

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 (unsupported for MIT, user not present)
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.

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.

Responses

Request samples

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

Cancel MIT payment

Cancel MIT payment on recurring agreement. Indicates that a successful authorization has been made, if 'succeeded' is set to true

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

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

cancelIdentifier
required
string non-empty

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

timestamp
required
string <date-time>

Timestamp for the cancel event 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 MIT payment

Capture MIT payment on recurring agreement

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

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

captureIdentifier
required
string non-empty

PSP's unique identifier for the capture to ensure idempotency

timestamp
required
string <date-time>

Timestamp for capture as known by the PSP.

Responses

Request samples

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

Response samples

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

Initiate CIT payment

Initiate a new CIT payment on recurring agreement

query Parameters
agreementId
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
required
Array of objects (CardType)

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

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

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 merchant id from MobilePay, as this will also guarantee uniqueness.

pspReferenceId
required
string non-empty

PSP's unique reference of the payment.

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.

validUntil
string or null <date-time>

Indicates 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.

isAccountVerification
boolean

Set to true if the payment is only an account verification (aka a zero-auth) - if set to true, payment amount cannot exceed 1 (100 in minor units)

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
{
  • "merchantLogoUrl": "string",
  • "merchantOrderId": "string",
  • "merchantUrl": "string",
  • "pspReferenceId": "string",
  • "amount": 0,
  • "currencyCode": "string",
  • "allowedCardTypes": [
    ],
  • "publicKeyId": 0,
  • "redirectFromMobilePayUrl": "string",
  • "failedPaymentCallbackUrl": null,
  • "validUntil": "2019-08-24T14:15:22Z",
  • "autoCapture": true,
  • "preferVisaPartOfVisaDankort": true,
  • "customerLanguageCode": "string",
  • "isAccountVerification": true,
  • "minimumMobilePayUserAge": 150
}

Response samples

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

Initiate MIT payment

Initiate merchant initiated payment on recurring agreement

query Parameters
agreementId
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
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

last4
required
string = 4 characters

Must match known last4 of card PAN on agreement to avoid card mismatch between MobilePay and PSP. If card does not match, payment will be rejected and user prompted to update card on agreement.

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 non-empty

PSP's unique reference of the payment.

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.

Responses

Request samples

Content type
application/json
{
  • "merchantOrderId": "string",
  • "merchantUrl": "string",
  • "pspReferenceId": "string",
  • "amount": 0,
  • "currencyCode": "string",
  • "autoCapture": true,
  • "last4": "1234"
}

Response samples

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

Refund MIT payment

Refund a MIT payment on agreement

path Parameters
paymentId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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

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

refundIdentifier
required
string non-empty

PSP's unique identifier for the refund to ensure idempotency.

timestamp
required
string <date-time>

Timestamp for refund as known by 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"
}

Platforms

Get platforms

header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register platform

Please do not create any platforms unless agreed with developer support

header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
name
required
string [ 3 .. 120 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "platformId": "32a6e381-64f4-4911-86b6-3bf681b64d23"
}

Update platform

Please do not create any platforms unless agreed with developer support

path Parameters
platformId
required
string <uuid>
header Parameters
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Request Body schema: application/json
name
required
string [ 3 .. 120 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

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
x-ibm-client-id
required
string

Client id for authentication

x-ibm-client-secret
required
string

Client secret for authentication

CorrelationId
string

CorrelationId used for logging

Responses