McPay version 1.1

27 Sep 2023
4 Minutes to read

McPay version 1.1

Updated on 27 Sep 2023
4 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback

Mediaconnect payment SDK

This feature allows our clients to easily enable different payment method options on their websites. We will collect payments on your behalf. It is a javascript library that our clients can use to facilitate integration with payment intermediaries. It is possible to do payments on the same page(seamless view flow) or use redirect(redirect flow). In order to use this feature please contact Mediaconnect by sending an email to Support at Mediaconnect.

McPay servers

There are currently two types of servers in use, namely the mcPayCdnServer and the mcPayApiServer.

mcPayCdnServer
This provides static files e.g. javascript.

Production: https://api.mediaconnect.no/mcpay
Test: https://api-test.mediaconnect.no/mcpay

mcPayApiServer
This specifies API server, when initializing javascript library it must be provided.

Production: https://api.mediaconnect.no/capi/mcpay
Test: https://api-test.mediaconnect.no/capi/mcpay

Payment methods

There are several possible payment methods. Payment provider configuration is needed to use these payment methods. Some of the payment providers support recurring payment, see the table below.

Note that only some of these payment methods may be available to you, e.g. due to geographic availability, etc.

paymentMethod	recurring=true	recurring=false	flow
creditcardPayex	✔	✔	seamless, redirect
vippsRecurring	✔		redirect
vippsEcommerce		✔	redirect

How to use McPay

To use the library you need to include our javascript on your website.

Example:

<script src="[mcPayCdnServer]/lib/v/1/mediaconnectpay.js"></script>

The library is available under mediaconnectpay namespace in javascript.

mcPayCdnServer supports different url schemes

/lib/v/{dynamicVersion}/mediaconnectpay.js - suggested way of loading the newest version matching requested dynamic version e.g. 1 may return 1.1.2, 1.0 may return 1.0.1, 1.1 may return 1.1.2, 2 may return 2.0.0
/lib/public/{version}/mediaconnectpay.js - specific version where version is composed of {major}.{minor}.{patch}, exact matching e.g. 1.0.1, 1.1.2, 2.0.0
/lib/beta/mediaconnectpay.js - the newest version under development, should not be used under normal circumstances

Newest libary version at this moment is v. 1.1.0.

Please note: Never show the payment script inside an iframe. In general, it may break the payment flow

if not today, then later.

Then you need to initialize it.

Example:

<div id="mediaconnectpay-id"></div>

<script>
	mediaconnectpay.Api.init({
		// see [mcPayApiServer]
		baseUrl: 'https://api-test.mediaconnect.no/capi/mcpay',
		elementId: 'mediaconnectpay-id'
	});
	// ...
</script>

Technical details of init argument object:

Property	Type	Description
baseUrl	string	mcPayApiServer url required
elementId	string	html element id where library can place generated content required

Next step is to initiate payment.

Example:

mediaconnectpay.Api.paymentInit(request, callback);

Technical details of paymentInit request object:

Property	Type	Description
clientCode	string	Client code required
sign	string	Signed JWT token with payment init parameters required

Example:

{
  "clientCode": "no.mediaconnect.test",
  "sign": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50TWV0aG9kIjoiY3JlZGl0Y2FyZFBheWV4IiwicHJvZHVjdFNwZWNDb2RlIjoiVE9UVCIsInByb2R1Y3RTcGVjTm8iOjEsInJlY3VycmluZyI6dHJ1ZSwiY2xpZW50Q29kZSI6Im5vLm1lZGlhY29ubmVjdC50ZXN0IiwiZXh0ZXJuYWxSZWZlcmVuY2UiOiJVVUlELTIwMjItMDMtMDRUMTI6MDA6MDAuMDAwWiIsIm5iZiI6MTY0NjM5NTQ0NywiaWF0IjoxNjQ2Mzk1NDQ3LCJleHAiOjE2NDYzOTkwNDd9._zH3XwyzOzgaaIvsIpw5byAT2It84zrr7t4U65fTmDNoI8AfC8O3f_G99qGv7OkEB1zBJ7Om33XtmB2-9QCwCA"
}

Technical details of paymentInit request sign object before being signed:

Property	Type	Description
clientCode	string	Client code required
paymentMethod	string	creditcardPayex, vippsRecurring, vippsEcommerce required
paymentFlow	string	seamless, redirect optional
paymentScope	string	Scope for vipps payment, space delimited: address birthDate email name phoneNumber optional
productSpecCode	string	Coupon code optional, reuired for recurring
productSpecNo	number	Coupon number optional, required for recurring
currency	string	Currency, if not provided taken from the coupon or partner company default currency optional
amount	number	Amount, if not provided taken from the coupon, if coupon is not provided, amount is required optional, required for non-coupons/multiline orders
vatAmount	number	Vat amount optional, should be send for non-coupons/multiline orders
subscriptionStartAmount	number	Amount that overrides standard start coupon amount optional
recurring	boolean	Is this recurring payment required
description	string	Passed to payment provider payment window optional
externalReference	string	External reference to this payment from client side, unique, one time use only required
phoneNumber	string	Phone number optional
returnUrl	string	Return url. Url will have additional parameters added about the payment: mcPayRef - id of the payment, after successful payment use it as mcPayRef to place the order status - status of the payment, success or failure optional, required if payment method uses redirect flow

Example:

{
  "paymentMethod": "creditcardPayex",
  "productSpecCode": "TOTT",
  "productSpecNo": 1,
  "recurring": true,
  "clientCode": "no.mediaconnect.test",
  "externalReference": "UUID-2022-03-04T12:00:00.000Z"
}

Technical details of paymentInit callback object:

Property

Type

Description

onInit

function

Callback called after payment was initialized, user may fulfill the payment details.
Callback argument #1, paymentInit api response, structure: { mcPayRef: string; }

mcPayRef

string, id of the payment

onSuccess

function

Callback called after payment was successfully completed. Works only during seamless flow, not during redirect flow.
Callback argument #1, paymentInit api response, structure: { mcPayRef: string; }

mcPayRef

string, id of the payment, after successful payment use it as mcPayRef to place the order

Callback argument #2, complete response passed from payment provider, available if payment provider make it available otherwise undefined.

onFailure

function

Callback called after payment failed.
Callback argument #1, paymentInit api response, available if payment was initialized otherwise is undefined, structure: { mcPayRef: string; }

mcPayRef

string, id of the payment

Callback argument #2, error response.
Callback argument #3, error response passed from payment provider, available if payment provider make it available otherwise undefined. Callback argument #4, optional, string, failure reason e.g. 'cancel'.

onRedirect

function

Callback called after payment was initialized with redirect flow. Optional, if onRedirect function provided then you are responsible for handling it, either do redirect in same window or for example in new tab.
Callback argument #1, paymentInit redirect response, structure: { mcPayRef: string; redirectUrl: string; }

mcPayRef	string, id of the payment
redirectUrl	string, redirect url

Example:

{
	onInit: function (paymentInitResponse) {
		// ...
	},
	onSuccess: function (paymentInitResponse, providerResponse) {
		// ...
	},
	onFailure: function (paymentInitResponse, errorResponse, providerResponse) {
		// ...
	},
	// if onRedirect function provided then you are responsible for handling it
	onRedirect: function (redirectResponse) {
		// ...
	},
}

After payment is finished base on redirect flow mcPayRef will be returned together with status for payment (success/failure). If payment scope was provided for Vipps payment sub for Vipps user will be also returned.

Table of contents

Mediaconnect payment SDK
McPay servers
Payment methods
How to use McPay