McPay version 1.1
  • 27 Sep 2023
  • 4 Minutes to read
  • PDF

McPay version 1.1

  • 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
vippsEcommerceredirect

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:

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, vippsEcommerce
required
paymentFlowstringseamless, redirect
optional
paymentScopestringScope for vipps payment, space delimited: address birthDate email name phoneNumber
optional
productSpecCodestringCoupon code
optional, reuired for recurring
productSpecNonumberCoupon number
optional, required for recurring
currencystringCurrency, if not provided taken from the coupon or partner company default currency
optional
amountnumberAmount, if not provided taken from the coupon, if coupon is not provided, amount is required
optional, required for non-coupons/multiline orders
vatAmountnumberVat amount
optional, should be send for non-coupons/multiline orders
subscriptionStartAmountnumberAmount that overrides standard start coupon amount
optional
recurringbooleanIs this recurring payment
required
descriptionstringPassed to payment provider payment window
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.