McPay version 1.0
  • 25 Aug 2023
  • 4 Minutes to read
  • PDF

McPay version 1.0

  • PDF

Article summary

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.

paymentMethodrecurring=truerecurring=falseflow
creditcardPayexseamless, redirect
vippsRecurringredirect

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

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:

PropertyTypeDescription
baseUrlstringmcPayApiServer url
required
elementIdstringhtml 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:

PropertyTypeDescription
clientCodestringClient code
required
signstringSigned 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:

PropertyTypeDescription
clientCodestringClient code
required
paymentMethodstringcreditcardPayex, vippsRecurring
required
paymentFlowstringseamless, redirect
optional
paymentScopestringScope for vipps payment, space delimited: address birthDate email name phoneNumber
optional
productSpecCodestringCoupon code
required
productSpecNonumberCoupon number
required
currencystringCurrency, if not provided taken from the coupon
optional
amountnumberAmount, if not provided taken from the coupon
optional
recurringbooleanIs this recurring payment
required
descriptionstringPassed to payment provider
optional
externalReferencestringExternal reference to this payment from client side, unique, one time use only
required
phoneNumberstringPhone number
optional
returnUrlstringReturn 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:

PropertyTypeDescription
onInitfunctionCallback called after payment was initialized, user may fulfill the payment details.
Callback argument #1, paymentInit api response, structure: { mcPayRef: string; }
mcPayRefstring, id of the payment
onSuccessfunctionCallback called after payment was successfully completed. Works only during seamless flow, not during redirect flow.
Callback argument #1, paymentInit api response, structure: { mcPayRef: string; }
mcPayRefstring, 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.
onFailurefunctionCallback called after payment failed.
Callback argument #1, paymentInit api response, available if payment was initialized otherwise is undefined, structure: { mcPayRef: string; }
mcPayRefstring, 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'.
onRedirectfunctionCallback 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; }
mcPayRefstring, id of the payment
redirectUrlstring, 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.