Single payment’s parameters

Only single payment details will be covered in this section.

Provide all required parameters in the request:

Parameter

Description

Mandatory?

merchant.brandId 

For single merchants - Your identificator - BrandId - will be provided by your Account Manager

For baas partners - BrandID value from Get clients API response.

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 you provided us.

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 you provided us.

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,

CARD - for card payments.

If provided both, e.g. [“PIS, "CARD"] then one additional step added - payment method selection in our widget.

We strongly recommend choosing a payment method from checkout.

Yes

payment.providerCountryCode 

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

For card payments use any country value (soon to be retired for card payments)

Yes

payment.providerId 

Allows you to preselect provider for bank transfers 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 80 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. For business entities you can use company type (e.g. PLC)

Yes

consumer.lastName 

 Consumer‘s last (family) name. For business entities you can use company 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 (if not provided, we will collect email through payment widget)

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 paymentOrderNo and redirectUrl, where should forward Consumer to start authorizartion flow.
With paymentOrderNo 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:

A. If you are a single merchant, use this PATH: /merchant/payments and authorization requirements provided here.

B. If you are a platform using BaaS APIs, use this PATH: baas/merchant/payments and authorization requirements provided here.

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": {
		"paymentOrderNo": "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.

Undefined