Integration

Authorization header

For Payonic to validate the client and authorization header must be added to the request.

To auhenticate the Payonic API an API-key will be rquired. This API-key can be fetched from within app.payonic.com from the menu "Settings" -> "API-key".

The API key is then required in all API requests by setting the API-key header Authorization to the value Basic API-key. Below is an example on how to call the API using cURL with the API-key "1234567890ABC":

	curl https://api.cit.payonic.com/api/initdynamic -H "Authorization: Basic 1234567890ABC"
							

Trace header

To trace each API request a simple header can be added to each individual request. The header is named TraceApi and must be set to an unique value (UUID). When both client and server stores this unique reference quick debugging is enabled.

Below is an example of how this header is set using cURL:

	curl https://api.cit.payonic.com/api/initdynamic -H "TraceApi: e018fdfb5bda40e4a7e91759c22922fd"
							

Server side initialization

The HTTP method of the client request must be POST.

The end-point of the API call is: https://api.cit.payonic.com/api/initdynamic

The first step is to initialize the payment session using a server-to-server side call. This is to void the client to have the posibillity to manipulate with any data transmitted between merchant and Payonic.

Below is an example of the JSON data, which needs to be transmitted to Payonic to initialize the payment session.

{
	"merchantid": "4f4e2451482d441ead8e2862369727d0",
	"merchantpaymentid": "cc00f2451482d441ead8e28623697aaf0",
	"newmerchantpaymentid": "eeee2451482d441ead8e28623697eeee",
	"amount": 250,
	"currency": "DKK",
	"reference": "order-12345",
	"idpan": "containerpan",
	"idexpmonth": "containerexpmonth",
	"idexpyear": "containerexpyear",
	"idsecuritycode": "containersecuritycode",
	"set3ds": "full_liability_skip_3ds",
	"rule": 1,
	"timeout": 900,
	"paymentid": "4f4e2451482d441ead8e2862369727d0",
	"hostedid": "123e2451482d441ead8e286236972abc",
	"instantcapture": 0,
	"processor":  ["finaro", "bambora"],
	"merchantdata": "Any kind of data that the merchant whish to parse through", 
	"textonstatement": "Payonic.com order 12345", 
	"notificationurl": "https://www.payonic.com/citpayment", 
}
							

As response the following JSON is returned:

{
	"merchantid": "4f4e2451482d441ead8e2862369727d0",
	"merchantpaymentid": "AAFF2451482d441ead8e28623697BB22",
	"sessionid": "168c4ef2f6d046029d72fd318d844f55",
	"amount": 10,
	"currency": "DKK",
	"reference": "order-12345",
	"idpan": "containerpan",
	"idexpmonth": "containerexpmonth",
	"idexpyear": "containerexpyear",
	"idsecuritycode": "containersecuritycode",
	"dfurlpan": "https://api.cit.payonic.com/dynamic/168c4ef2f6d046029d72fd318d844f55/pan",
	"dfurlexpyear": "https://api.cit.payonic.com/dynamic/168c4ef2f6d046029d72fd318d844f55/expyear",
	"dfurlexpmonth": "https://api.cit.payonic.com/dynamic/168c4ef2f6d046029d72fd318d844f55/expmonth",
	"dfurlsecuritycode": "https://api.cit.payonic.com/dynamic/168c4ef2f6d046029d72fd318d844f55/securitycode",
	"dfurlccsingle": "https://api.cit.payonic.com/dynamic/168c4ef2f6d046029d72fd318d844f55/ccsingle",
	"dfurlscriptinclude": "https://api.cit.payonic.com/dynamic/168c4ef2f6d046029d72fd318d844f55/dynamic.js",
}
							

Include JavaScript

When the payment session is initialized on the server-side the dynamic fields JavaScript must be included on the client side. This is done by selecting the dfurlscriptinclude from the initialization response.

								  	
	<script src="{{oresponse->dfurlscriptinclude}}"></script>
								  	
								

Add hosted fields

Add the HTML elements which needs to be filled by the Hosted Fields frames.

								  	
	<div id="containerpan"></div>
	<div id="containerexpmonth"></div>
	<div id="containerexpyear"></div>
	<div id="containersecuritycode"></div>
	<div id="containersingle"></div>
	<div id="containerchallenge"></div>
								  	
								

Initialize the hosted fields

								  	
	<script>
		$( document ).ready( function() {
			var req = {
				jsinitsuccess: initDynamicSuccess,
				jspaymentsuccess: paymentSuccess,
				jspaymentstarted: paymentStarted,
				jspaymentfailed: paymentFailed,
				jspaymenttimeout: paymentTimeout,
				jschallengestarted: challengeStarted,
				jschallengecompleted: challengeCompleted,
				jschallengeaborted: challengeaborted,
			}
			initDynamic( req );
		});
	</script>
								  	
								

JavaScript events

The javascript functions below can be set to receive notifications from the hosted fields with in formation of the current user state.

Payload

This section describes examples of the payload, which is transmitted as object to the javascript event function. Each javascript function takes in one parameter, which is an object of data. The javascript function can be implemented like this:

								  	
	<script>
		function jspaymentfailed(obj) {
			console.log(obj.sessionid);
			console.log(obj.paymentid);
			console.log(obj.errorcode);
			console.log(obj.errortext);
		}
	</script>
								  	
								

As payload following attributes on the obj parameter is defined:

jsinitsuccess

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
}
							

jspaymentsuccess

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
}
							

jspaymentstarted

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
}
							

jspaymentfailed

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
	"errorcode": "PAN_MISSING",
	"errortext": "The PAN is missing in the request",
}
							

jspaymenttimeout

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
}
							

jschallengestarted

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
}
							

jschallengecompleted

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
}
							

jschallengeaborted

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
}
							

Notice - we would like to have some more feedback regarding javascript event types

Add a payment button

Finally a payment button must be added. This button calls the function goPay(), which will start the payment process.

								  	
	<button type="button" class="btn btn-primary w-100" onclick="goPay();">PAY</button>
								  	
								

As the payment is processing JavaScript events will be notified to the function described in the JavaScript events section

Notification

When the payment is completed Payonic (success or timed out) notifies using a HTTP POST message to the initiator with successful payment data:

{
	"sessionid": "4f4e2451482d441ead8e2862369727d0",
	"paymentid": "BEFF2451482d441ead8e286236971234",
	"merchantpaymentid": "AAFF2451482d441ead8e28623697BB22",
	"newmerchantpaymentid": "eeee2451482d441ead8e28623697eeee",
	"status": "approved",
	"responsecode": "00",
	"authorizationcode": "654321",
	"processor": "finaro",
	"tcardnumber": "457123xxxxxx4578",
	"eci": "07",
	"merchantdata": "merchantdata",
	"par": "391c778120ca6de3a1ba8707e470b",
}
							

The notification expects that the receiving system replies by standard HTTP 200 as ok. Otherwise the notification will be retried once every hour up to 24 times. That means the system tries to perform a notification immediately. If this fails the system will retry 3 times with 3 second delay. Upon failure the system will retry 3 times with one hour delay. Finally the system will try to deliver the notification one time after 24 hours which is the final try.

Timeout for each notification is defined by the table below.

System API declines

This section describes the overall error handling when the payment platform declines an inbound request.

When the payment platform declines the request it will return to the requester with HTTP status code 400 and include the following payload.

{
	"error": "INVALID_PARAMETER",
	"errordescription": "the parameter [amount] with value [100,00] does not support alphanumeric values",
}
							

• INVALID_API_KEY
• INVALID_MERCHANTID
• INVALID_PARAMETER