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
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.
Plugins
eCommerce platform |
eCommerce platform version supported |
ConnectPay plugin version |
Plugin |
Documentation |
Woocommerce |
Min 5.3.0 |
1.0.0. |
||
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. |
||
Magento |
2.4 |
1.0.0. |
||
Shopware |
Min 6.4.0.0 |
1.0.0. |
||
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. |
Yes |
merchant.notificationUrl |
URL where notifications about the payment should be sent. |
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
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.