Basic authorization and brand information

Before initiating the first merchant payment, please ensure that you have devApp created with merchant services added to the configuration. To authorize API requests, use the Basic Authorization method:

Authorization: Basic BASE64(ClientId:ClientSecret)

Use ClientKey and ClientSecret from devApp.

For more details, see RFC-7617 .

API v2 authentication requirements (request signing)

Use the private key provided by our team after signing the contract.

We are generating keys for your convenience. To increase security, we recommend generating private and public key pairs yourself and sharing the public key with us instead.

openssl genrsa -out private.pem 2048
openssl rsa -pubout -in private.pem -out public.pem

All requests must contain a digital signature in X-Signature header. To generate signature, you have to calculate SHA256 hash of concatenated string with request parameters and sign the hash using RSA private key (String may need to be converted to UTF-8 before hashing).

Example

Let’s sign the Payment Initiation API request with this body:

{
	"merchant": {
		"brandId": "6ce66290-71a3-4376-be87-77f16cf6fe19",
		"redirectUrl": "https://localhost"
	},
	"payment": {
		"paymentMethod": [
			"PIS"
		],
		"providerCountryCode": "FI",
		"debtorName": "Wehner, Padberg and Pfannerstill",
		"instructedAmount": {
			"amount": "1.23",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "Multi-tiered global leverage"
	},
	"identifiers": {
		"merchantReference": "a983cef4-4969-487a-b7fb-0308e2038d27",
		"endToEndId": "3zNK8E5NpDsVrYdUknF988RPud"
	},
	"consumer": {
		"firstName": "Darrel",
		"lastName": "Keeling",
		"ipAddress": "235.114.187.1"
	}
}

Get the request method and convert it to lowercase

var reqMethod = "post";

Get request URL without https:// and convert it to lowercase

var reqUrl = "api2-stage.connectpay.com/merchant/payments";

Get the request body and minify it (remove all spaces, tabs, newlines)

var reqBodyMinified = reqBody.replace(/\s+/g, '');

"{"merchant":{"brandId":"6ce66290-71a3-4376-be87-77f16cf6fe19","redirectUrl":"https://localhost"},"payment":{"paymentMethod":["PIS"],"providerCountryCode":"FI","debtorName":"Wehner,PadbergandPfannerstill","instructedAmount":{"amount":"1.23","currency":"EUR"},"remittanceInformationUnstructured":"Multi-tieredgloballeverage"},"identifiers":{"merchantReference":"a983cef4-4969-487a-b7fb-0308e2038d27","endToEndId":"3zNK8E5NpDsVrYdUknF988RPud"},"consumer":{"firstName":"Darrel","lastName":"Keeling","ipAddress":"235.114.187.1"}}"

Concatenate all three variables using the vertical bar (pipeline) symbol | as separator

var dataToSign = reqMethod + "|" + reqUrl + "|" + reqBodyMinified;

post|api2-stage.connectpay.com/merchant/payments|{"merchant":{"brandId":"6ce66290-71a3-4376-be87-77f16cf6fe19","redirectUrl":"https://localhost"},"payment":{"paymentMethod":["PIS"],"providerCountryCode":"FI","debtorName":"Wehner,PadbergandPfannerstill","instructedAmount":{"amount":"1.23","currency":"EUR"},"remittanceInformationUnstructured":"Multi-tieredgloballeverage"},"identifiers":{"merchantReference":"a983cef4-4969-487a-b7fb-0308e2038d27","endToEndId":"3zNK8E5NpDsVrYdUknF988RPud"},"consumer":{"firstName":"Darrel","lastName":"Keeling","ipAddress":"235.114.187.1"}}

Calculate SHA256 hash of the concatenated string and sign the hash using the RSA private key (String may need to be converted to UTF-8 before hashing)

eval(pm.environment.get('pmlib_code'));

const dataToSign = reqMethod + "|" + reqUrl + "|" + reqBodyMinified;
var sig = new pmlib.rs.KJUR.crypto.Signature({"alg": "SHA256withRSA"});
sig.init(privateKey);
var signature = sig.signString(dataToSign); // Hashes and signs string

This sample uses postman-util-lib library by joolfe.

Encode the resulting signature bytes in Base64 and place them in the X-Signature header

const encodedSignature = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Hex.parse(signature));

IzfqLFmHTkszikfbJ9fJgJDAI9uD+fVHoS9pPGl3avBJ5nZKuaxQsqLlwDwNGRfMCHHwP/9q+cP9DLahwLGkSI1e61I1TLxeVINcflyehypdF5rtEL/Xx5TguHdXgLqV60hVME0BArB1jAro8imAoey9sDkxfuyesm3bizqyYwVTVLKbpCX5tBrcOVbRC6MboG9z+H6jqGLBJSCxMz3QTzQ7ieWb0woW0Ex/AyHW5UN3vrBwPnlOBbTovWe82dklia7xAIpiL6mhzGz5JCwmscVcUqhv9sxOwXxhHCBydM0Xal7WiRWmJ0fd0It+V6uoJYW7RldmTRvjK84EwFULcA==

For a complete working sample, please check the Pre-request script.

Request sample:

POST /merchant/payments HTTP/1.1
Host: api2-stage.connectpay.com

X-Request-ID: ce9db1f3-4c19-4447-a717-0239b15bb049
Accept: application/json;version=2
Content-Type: application/json
X-Signature: IzfqLFmHTkszikfbJ9fJgJDAI9uD+fVHoS9pPGl3avBJ5nZKuaxQsqLlwDwNGRfMCHHwP/9q+cP9DLahwLGkSI1e61I1TLxeVINcflyehypdF5rtEL/Xx5TguHdXgLqV60hVME0BArB1jAro8imAoey9sDkxfuyesm3bizqyYwVTVLKbpCX5tBrcOVbRC6MboG9z+H6jqGLBJSCxMz3QTzQ7ieWb0woW0Ex/AyHW5UN3vrBwPnlOBbTovWe82dklia7xAIpiL6mhzGz5JCwmscVcUqhv9sxOwXxhHCBydM0Xal7WiRWmJ0fd0It+V6uoJYW7RldmTRvjK84EwFULcA==
Authorization: Basic NTQxOThmNTItN2Q5Mi0zZjk4LTk5ZmEtOTE5OTE2NWEzZDQ3OjdmMGVhYjExLWVjZDEtM2UwZi05OTgzLWQ3OWIwNjYyYTZkYw==

{
	"merchant": {
		"brandId": "6ce66290-71a3-4376-be87-77f16cf6fe19",
		"redirectUrl": "https://localhost"
	},
	"payment": {
		"paymentMethod": [
			"PIS"
		],
		"providerCountryCode": "FI",
		"debtorName": "Wehner, Padberg and Pfannerstill",
		"instructedAmount": {
			"amount": "1.23",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "Multi-tiered global leverage"
	},
	"identifiers": {
		"merchantReference": "a983cef4-4969-487a-b7fb-0308e2038d27",
		"endToEndId": "3zNK8E5NpDsVrYdUknF988RPud"
	},
	"consumer": {
		"firstName": "Darrel",
		"lastName": "Keeling",
		"ipAddress": "235.114.187.1"
	}
}

Create a brand

Stage:

To start testing this service, drop a message to [email protected] mentioning you will want to integrate Merchant APIs and receive a Stage account. Please add your email (which will be used as a login to the stage environment) and phone No (to receive SMS OTPs). After you receive credentials from our dev support team, go to your online banking, select the “Merchant” tab, and fill out the merchant application. After it’s done, contact dev-support to approve contract creation; you will receive a brandId. You will also receive a .pem certificate via email that is attached to your brand. You can use this cert to sign requests.

Production:

To receive this service, you will need to have a merchant contract – MAR (Master Authorized Representative) should go to online banking, select the “Merchant” tab, and fill out the merchant application. After approval, contact us at [email protected] and send us your production public key; after it’s added to the brand configuration, we will share the brandId with you.

Create a devApp

Providers, payment methods, and languages

Single Payments

Recurring payments