Accept Payments

Introduction

Accept Payments

  • Collect EUR payments from customer bank accounts in DE, FI, NL, and LT
  • Automated reconciliation – reconcile payments automatically and effort free
  • Different plug ins for your e-commerce platforms

Create customized payment experiences with our Payment Gateway API

DEMO

How to get started?

If you wish to start using our Accept Payments service, please contact our sales and sign a contract.

Developer support

If you have any questions regarding integration / configuration support, please contact us: dev-support@connectpay.com

For operational questions, please contact us: support@connectpay.com

Ways of using our services

Our service can be reached in different ways:

  • By plug-in. Magento, Shopware, Woocommerce, OpenCart ecommerce platforms.
  • Direct integration. You can integrate our service according to this documentation.

Direct integration methods

We support 2 Accept payments API versions:

  • v1 – using mTLS and OAuth 2.0 authentication. It requires to have a SSL certificate issued by Certificate authorities that is renewed annually and OAuth token management . This version is not receiving feature updates and is planned for shutdown. 
  • v2 – using Basic authentication model and digital signatures for API requests. This is our default version used in plug-ins and is strongly recommended for merchants for direct integrations.
You can find Merchant API v2 documentation in our Postman collection.

 

Plugins

eCommerce platform

eCommerce platform version supported

ConnectPay plugin version

Plugin

Documentation

Woocommerce

Min 5.3.0

1.0.0.

Download  

User_Guide_for_Woocommerce_v.1.0.0.pdf (connectpay.com)

OpenCart

3.0.3.8

3.0.3.7

3.0.3.6

3.0.3.5

3.0.3.3

3.0.3.2

3.0.3.1

3.0.3.0

1.0.0.

Download

OpenCart_User_Guide_v.1.0.0_.pdf (connectpay.com)

Magento

2.4

1.0.0.

Download

User_Guide_for_Magento_v.1.0.0.pdf (connectpay.com)

Shopware

Min 6.4.0.0
Max 6.4.11.0

1.0.0.

Download

User_Guide_for_Shopware_v.1.0.0.pdf (connectpay.com)

PrestaShop Min V1.6.1.0
Max V1.7.8.6
1.1.0 Download User_Guide_for_PrestaShop_v.1.1.0.pdf (connectpay.com)

Payment methods

At this moment we support Payment initiation via bank transfer method (PIS) in EUR currency only and CARD payments (Visa, MasterCard).

Countries and banks

We support multiple countries and banks. A list is changing constantly:

Country Banks supported Payment scheme
Lithuania Swedbank SEPA-INST
SEB

SEPA-INST

Luminor SEPA-SCT
Citadele SEPA-SCT
Revolut SEPA-INST
Šiaulių bankas SEPA-SCT
Medicinos bankas SEPA-SCT
Germany Sparkasse Group SEPA-SCT
Postbank
Commerzbank
Deutsche Bank
TARGOBANK AG
ING (DiBa)
Hypovereinsbank
Norisbank
LBBW (Landesbank Baden- Württemberg)
DKB Deutsche Kreditbank AG Berlin
Comdirect
Santander
and others
Netherlands ING (Mijn) SEPA-SCT
Rabobank
SNS Bank
ABN AMRO
ASN Bank
Triodos
RegioBank
Finland OP SEPA-SCT
Nordea
Danske Bank
S-Pankki
Säästöpankki
Aktia
POP Pankki
Handelsbanken
Oma Säästöpankki
Ålandsbanken

 

 

In order to get full list of our providers in each country, you can use GET Providers API

Languages

Our widget supports these languages:

  • English (EN)
  • Lithuanian (LT)
  • German (DE)
  • Dutch (NL)
  • Swedish (SV)
  • Suomi (FI)

When sending a request, we recommend selecting the same language as your e-shop by default. Your client has ability to change it in widget.

Language parameter is optional. If language is not selected, widget will default to English.

You can change the language from plug-in admin panel also.

API v2 authorization requirements

To authorize API request, use Basic Authorization method:

Authorization: Basic BASE64(ClientId:ClientSecret)

Use ClientKey and ClientSecret provided by our team after signing the contract.

For more details see RFC-7617

API v2 authentication requirements (request signing)

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

We are generating keys for your convencience. To increase security we recommend to generate private and public key pair yourself and share 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 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"
	}
}

1. Get the request method and convert it to lowercase

var reqMethod = "post";

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

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

3. 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"}}"

4. Concatenate all three variables using 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"}}

5.Calculate SHA256 hash of the concatenated string and sign the hash using 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.

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

const encodedSignature = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Hex.parse(signature));
IzfqLFmHTkszikfbJ9fJgJDAI9uD+fVHoS9pPGl3avBJ5nZKuaxQsqLlwDwNGRfMCHHwP/9q+cP9DLahwLGkSI1e61I1TLxeVINcflyehypdF5rtEL/Xx5TguHdXgLqV60hVME0BArB1jAro8imAoey9sDkxfuyesm3bizqyYwVTVLKbpCX5tBrcOVbRC6MboG9z+H6jqGLBJSCxMz3QTzQ7ieWb0woW0Ex/AyHW5UN3vrBwPnlOBbTovWe82dklia7xAIpiL6mhzGz5JCwmscVcUqhv9sxOwXxhHCBydM0Xal7WiRWmJ0fd0It+V6uoJYW7RldmTRvjK84EwFULcA==

For complete working sample, please check Pre-request script of Initiate Payment API in our Postman collection.

7. 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"
	}
}

 

Payment parameters

Provide all required parameters in the request:

Parameter

Description

Mandatory?

merchant.brandId 

Your identificator - BrandId - will be provided by your Account Manager.

Yes

merchant.generic1 

This information will be passed back in the response.

No

merchant.generic2 

This information will be passed back in the response.

No

merchant.generic3 

This information will be passed back in the response.

No

merchant.redirectUrl 

URL where to redirect Consumer after payment authorization. 
We support only TLS encrypted connections (URL must begin with https://, not http://). Hostname will be validated against URLs in Merchant profile.

Yes

merchant.notificationUrl 

URL where notifications about the payment should be sent.
We support only TLS encrypted connections (URL must begin with https://, not http://). Hostname will be validated against URLs in Merchant profile.

No

merchant.language 

Allows to specify Widget UI language. If parameter not provided, defaults to EN. Currently supported languages: EN, DE, NL, FI, SV, LT.

No

payment.paymentMethod 

PIS – for payment initiation

Yes

payment.providerCountryCode 

Used to preselect country when requesting to initiate payment. Available countries are: DE, NL, FI, LT

Yes

payment.providerId 

Allows you to preselect provider when requesting to initiate payment. This way you can skip our widget part and redirect your customer to preselected bank.

Important! When using preselected provider, you must ensure our Terms of Use and Privacy Policy visible for your customer before initiating a payment. You can find the text here.

No

payment.debtorAccount.iban 

IBAN from which the payment should be performed

No

payment.debtorName 

Name of debtor account holder

No

payment.instructedAmount.amount 

Requested amount, with 2 decimal digits

Yes

payment.instructedAmount.currency 

Only EUR supported.

Yes

payment.remittanceInformationUnstructured 

Payment details, up to 79 characters. For better customer buying experience we strongly recommend adding order or invoice number.

Yes

identifiers.merchantReference :

Unique payment reference in your system

Yes

identifiers.endToEndId 

End to End identifier in accordance with ISO20022 specification (1 to 35 symbols). Will be passed to the Consumer's Provider

Yes

identifiers.creditorReference 

Creditor Reference according to ISO 11649 (/^RF[0-9]{2}[0-9A-Za-z]{1,21}/).

No

identifiers.finnishReference 

Finnish reference number (/^\\d{4,20}$/)

No

identifiers.norwegianKid 

Norwegian KID reference number (/^\\d{3,25}$/)

No

consumer.firstName 

Consumer‘s first name.

Yes

consumer.lastName 

Consumer‘s last (family) name

Yes

consumer.consumerId 

Your internal Consumer ID, if you have it

No

consumer.ipAddress 

IP address of Consumer's device

Yes

consumer.phoneNo 

Consumer's Phone Number. Providing it would help to make Consumer's user experience smoother.

No

consumer.email

Consumer's email. Providing it would help to make Consumer's user experience smoother.

No

Hostname in merchant.redirectUrl and merchant.notificationUrl will be validated against URLs provided to us.

In Payment initiation response, you will receive Merchant API paymentId and redirectUrl, where should forward Consumer to start authorizartion flow.
With paymentId you will be able to request Payment details via Get Payment Details API.

Payment flow

Payment flow

1. Initiate a payment

To accept a payment for your customer, at first you need to initiate a payment using our Initiate payment API as provided in example below:

POST /merchant/payments HTTP/1.1
Host: api2-stage.connectpay.com
X-Request-ID: 7b5e3498-a926-4fae-89a6-381eca510d6a
Accept: application/json;version=2
Content-Type: application/json
X-Signature: kQFANf/z8qjgHyEfFOLPITjgYeQKjT4ksOJcOOJ7CcqEn6WXEw8exuL8yt+BUWMKoGFFt9wrL5X69ELVSXhp/ARodqmx/zyG/NfyCcqZ+SLX31h0jHWGH/u+IQtQXKt5x46PR/Yi7gCebqhrZXIt8au7duvFZB/ZNr/0YDsW0ciMzDsPsDl9dJcAyTIqa4B29rbyM+Svd6SMzlvqIDo4gH0BBX9aNYshrD9/eSFtGb3iysfU412UBzKqwYRiFK5tp84XwKKxai/ktuPW+gFQbF8U/fo5HQMYTUQ8+FeoIUfIEr1dReIVZZmcBI5Ncnpme1WYUXoViT9tdC+B8Z6Sow==
Authorization: Basic NTQxOThmNTItN2Q5Mi0zZjk4LTk5ZmEtOTE5OTE2NWEzZDQ3OjdmMGVhYjExLWVjZDEtM2UwZi05OTgzLWQ3OWIwNjYyYTZkYw==

{
	"merchant": {
		"brandId": "6ce66290-71a3-4376-be87-77f16cf6fe19",
		"generic1": "B2C",
		"generic2": "ROI",
		"generic3": "grow",
		"redirectUrl": "https://localhost",
		"notificationUrl": "https://localhost",
		"language": "EN"
	},
	"payment": {
		"paymentMethod": ["PIS"],
		"providerCountryCode": "NL",
		"providerId": "03a4effd-d047-4c3e-ab95-1b4fb198b64f",
		"debtorName": "Turcotte, Reichel and Rau",
		"instructedAmount": {
			"amount": "1.23",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "Secured homogeneous structure"
	},
	"identifiers": {
		"merchantReference": "10438ba4-c180-44be-9306-3760d2ab00d0",
		"endToEndId": "3fZcjUEGynfXhs8JcsiGpXzRpowMe",
		"creditorReference": "RF12334567"
	},
	"consumer": {
		"firstName": "Morton",
		"lastName": "Heidenreich",
		"consumerId": "d48c0a1b-d1b0-49f9-8851-a4bea951ed2b",
		"ipAddress": "56.192.2.34",
		"phoneNo": "37066666666",
		"email": "Trycia69@gmail.com"
	}
}

If request was successful, you will receive response with http code 201 and payment ID and redirect URL in response body. You have to redirect your customer to redirtect URL to authorize a payment within their provider (bank). Save payment ID for further status check. Response example below:

{
	"merchant": {
		"generic1": "B2C",
		"generic2": "ROI",
		"generic3": "grow"
	},
	"payment": {
		"paymentId": "af8065f3-88da-4fad-b1d6-556667fe8284",
		"redirectUrl": "https://pay-stage.connectpay.com?key=2a65b7db-5645-4807-bc59-a65e15a5dce0"
	}
}

2. Redirect Consumer to Merchant API Widget

3. Redirect Consumer back to your environment

After authorization within their bank, Consumer will be redirected back to widget and will be presented with payment status information.

Sometimes, provider may not respond immediately with the final payment status information. In such cases, we will periodically check at Provider for final status and update payment information. Same way, you should periodically check payment status using Get payment details API .

As a final step of payment journey, by pressing button Return to Merchant, Consumer will be redirected back to your website using web address provided via redirectUrl parameter in Payment Initiation API request.

4. Get payment details.

 After Consumer is redirected back to your environment, get payment details by sending us a request as exampled below:

GET /merchant/payments/af8065f3-88da-4fad-b1d6-556667fe8284 HTTP/1.1
Host: api2-stage.connectpay.com
X-Request-ID: 4be51b3b-aef6-4797-bb03-982078c9f76f
Accept: application/json;version=2
X-Signature: kQFANf/z8qjgHyEfFOLPITjgYeQKjT4ksOJcOOJ7CcqEn6WXEw8exuL8yt+BUWMKoGFFt9wrL5X69ELVSXhp/ARodqmx/zyG/NfyCcqZ+SLX31h0jHWGH/u+IQtQXKt5x46PR/Yi7gCebqhrZXIt8au7duvFZB/ZNr/0YDsW0ciMzDsPsDl9dJcAyTIqa4B29rbyM+Svd6SMzlvqIDo4gH0BBX9aNYshrD9/eSFtGb3iysfU412UBzKqwYRiFK5tp84XwKKxai/ktuPW+gFQbF8U/fo5HQMYTUQ8+FeoIUfIEr1dReIVZZmcBI5Ncnpme1WYUXoViT9tdC+B8Z6Sow==
Authorization: Basic NTQxOThmNTItN2Q5Mi0zZjk4LTk5ZmEtOTE5OTE2NWEzZDQ3OjdmMGVhYjExLWVjZDEtM2UwZi05OTgzLWQ3OWIwNjYyYTZkYw==

Response body will contain all information about the payment. In addition to payment data provided in Payment Initiation request, Response will have set of various statuses and Consumer details.

{
	"merchant": {
		"generic1": "sticky",
		"generic2": "architectures",
		"generic3": "seize"
	},
	"payment": {
		"paymentMethod": "PIS",
		"providerId": "03a4effd-d047-4c3e-ab95-1b4fb198b64f",
		"providerName": "Test Bank",
		"creditorAccount": {
			"iban": "LT249388994358452435"
		},
		"creditorName": "Gravelbox Ltd.",
		"instructedAmount": {
			"amount": "1.23",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "Self-enabling homogeneous utilisation",
		"debtorAccount": {
			"bban": "1234567890",
			"bic": "1234"
		}
	},
	"identifiers": {
		"merchantReference": "c4e6c6f4-08c6-45f5-8dfe-48b84f736151",
		"creditorReference": "RF12334567",
		"endToEndId": "1dtejgGyPpkEMVqa3LrtvSgyCMX4Lm2VH"
	},
	"consumer": {
		"firstName": "Chaim",
		"lastName": "Towne",
		"consumerId": "087a248a-d9c8-405f-a675-e4f76b186eee",
		"ipAddress": "71.25.153.236",
		"email": "juozas@gmail.com"
	},
	"status": {
		"isTerminal": true,
		"createdAt": "2022-03-29T08:01:29.920Z",
		"code": "Approved",
		"lastUpdatedAt": "2022-03-29T08:02:47.000Z",
		"details": {
			"providerStatusCode": null,
			"providerMessage": null,
			"errorMessage": null
		}
	}
}

Property status.code

Our widget provides these statuses (parameter status.code) :

Initiated

 Payment initiation request received from Merchant.

PendingMerchant

 Payment initiation response sent to Merchant.

InProgress

 Redirect received from Merchant.

Processing

 Payment initiation request sent to Provider.

PendingProvider

 Redirect received from Provider OR Payment status update received from Provider, however payment status is not terminal.

Approved

 Payment approved.

Settled

Funds has been received in Merchant Account

Failed

 Payment failed.

Abandoned

 Payment canceled or abandoned at Provider OR Session expires OR Consumer cancels payment before initiating it.

Unknown

 Unknown payment status update received from Provider.

Property debtorAccount.iban

IBAN of Consumer account. Some providers do not provide Consumer’s account information (IBAN)

Property status.isTerminal

To uderstand if status is terminal, check status.isTerminal: Boolean finalisation indicator:

  • True – if payment is finalised and it‘s status won‘t change.
  • False – payment is not completed yet.

5. Get notifications

We strongly recommend to provide us your notification URL, which could be used to update you about payment status change if it is not terminal. When we get notification from provider, we would send you a POST request (and expect a response with 200 http code). In case of error, we will try to send you a notification 5 times in a row.

Request body will have same body as in Get Payment Details API.

Undefined