Make Merchant API Bank Transfer payment

Initiate and authorize payment via PSD2 PIS service

  • To make a Merchant API Payment via PIS (PSD2 Payment Initiation Service), it must be Initiated and then Authorized. In short, flow can be splitted to these parts:

    • Initiate payment via API and receive unique Merchant API WidgetURL,
    • Forward Consumer in a browser to Merchant API Widget (MG-W) to authorize payment,
    • When Consumer is redirected back to your website, check Payment status via API.
  • PIS service supports only SEPA-SCT payments in Euro

  • Postman collection of Merchant API is here

Flow

Detailed payment flow:


Initiate a payment

To initiate a payment you should call Initiate Payment API.
Request should be sent from your backend server via already configured mTLS channel.
If payment was accepted, http response with have code 201.

Request Parameters

Provide all required parameters in the request:

merchant.brandId : Mandatory, your identificator - BrandId - will be provided by your Account Manager.
merchant.generic1 : Optional, this information will be passed back in the response.
merchant.generic2 : Optional, this information will be passed back in the response.
merchant.generic3 : Optional, this information will be passed back in the response
merchant.redirectUrl : Mandatory, your URL where to redirect Consumer after payment authorization journey. URL must begin with https:// protocol.
merchant.notificationUrl : Optional, your URL where notifications about the payment should be sent. URL must begin with https:// protocol.
merchant.language : Optional. Allows to specify Widget UI language. If parameter not provided, defaults to EN. Currently supported languages: EN, DE, NL, FI, SV.

payment.paymentMethod : Mandatory, use value PIS.
payment.providerCountryCode : Mandatory, Used to preselect country when requesting to initiate payment. Available countries are: DE, NL, FI
payment.providerId : Optional, allows you to preselect provider when requesting to initiate payment.

payment.debtorAccount.iban : Optional, IBAN from which the payment should be performed.
payment.debtorName : Optional, Name of debtor account holder

payment.instructedAmount.amount : Mandatory, requested amount, with 2 decimal digits.
payment.instructedAmount.currency : Mandatory, use value EUR.

payment.remittanceInformationUnstructured : Mandatory, payment details, up to 79 characters. For better customer buying expierience we strongly recommend adding order or invoice number.

identifiers.merchantReference : Mandatory, Unique payment reference in your system.
identifiers.endToEndId : Mandatory, End to End identifier in accordance with ISO20022 specification (1 to 35 symbols). Will be passed to the Consumer's Provider.
identifiers.creditorReference : Optional, Creditor Reference according to ISO 11649 (/^RF[0-9]{2}[0-9A-Za-z]{1,21}/).
identifiers.finnishReference : Optional, Finnish reference number (/^\\d{4,20}$/).
identifiers.norwegianKid : Optional, Norwegian KID reference number (/^\\d{3,25}$/).

consumer.firstName : Mandatory, Consumer first name.
consumer.lastName : Mandatory, Consumer last (family) name.
consumer.consumerId : Optional, if you have your internal Consumer ID, you can add it to the request.
consumer.ipAddress : Mandatory, IP address of Consumer's device.
consumer.phoneNo : Optional, Consumer's Phone No. Providing it would help to make Consumer's user experience smoother.
consumer.email : Optional, Consumer's email. Providing it would help to make Consumer's user experience smoother.


Parameter Notes:

payment.creditorAccount : Has been removed and should not be provided.
Hostname in merchant.redirectUrl and merchant.notificationUrl will be validated against comma separated URL list in DevApp property Callback Url

Request sample:

curl --location --request POST 'https://api-stage.connectpay.com/merchant/payments' \
--header 'X-Request-ID: 8e227a2a-9632-4c2f-85d4-b748ce2b8deb' \
--header 'Accept: application/json;version=1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer RNbg3diacuNIKnYTChgjMI7Tj6lN' \
--data-raw '{
	"merchant": {
		"brandId": "d96cc89c-0630-464d-b8d3-36bd527139a9",
		"generic1": "back-end",
		"generic2": "communities",
		"generic3": "mesh",
		"redirectUrl": "https://webhook.site/#!/747bcc1f-038e-48eb-8488-9f4f0ca7155d",
		"language": "EN"
	},
	"payment": {
		"paymentMethod": "PIS",
		"providerCountryCode": "DE",
		"instructedAmount": {
			"amount": "19.13",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "User-friendly 6th generation function"
	},
	"consumer": {
		"firstName": "London",
		"lastName": "Labadie",
		"consumerId": "169c5450-4796-4f94-8f9e-7aaffa35d30c",
		"ipAddress": "25.139.113.211",
		"phoneNo": "37066666666",
		"email": "Aaron.Mohr92@yahoo.com"
	},
	"identifiers": {
		"merchantReference": "bbd4cb12-2268-40f2-a60d-90e16a46e80f",
		"endToEndId": "1B4egLMMBx96xQ9nx2Pb2WwhmiZAcZN",
		"creditorReference": "RF12334567",
		"finnishReference": "12345",
		"norwegianKid": "12345"
	}
}'

Response

In Payment initiation response, we 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.

Response sample

{
	"merchant": {
		"generic1": "killer",
		"generic2": "initiatives",
		"generic3": "synergize"
	},
	"payment": {
		"paymentId": "f73239ec-37ea-4fcb-9499-568e5e098838",
		"redirectUrl": "https://pay-stage.connectpay.com?key=d81d5bf2-dab2-4a78-8744-954d8baae76b"
	}
}

Redirect Consumer to Merchant API Widget

Redirect Consumer to the MG-W by forwarding his browser to the redirectUrl. Consumer will be presented with set of screens to enter email (if it was not provided in Payment Initiation request), review payment details, choose country, provider.
After that, Merchant API will send payment initiation request to the chosen provider and will forward Consumer to provider's website to perform authorization.


Authorization

In some cases, especially with German banks, Consumers will have to authenticate and authorize payment directly in a widget. As it is standard method with these banks, Consumers should not feel any discomfort.

Consumer should authenticate and authorize payment using his provider's auth method.



Redirect back to Merchant API Widget

After authorization, Consumer will be redirected back to MG-W and will be presented with payment status information.
Sometimes, provider may not respond immediately with 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 at Merchant API .

Redirect back to Merchant website

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


Check Payment Status

To check status, call Get Payment Details API.

Request

In API request you have to provide MG issued paymentId as a path parameter:

curl --location --request GET 'https://api-stage.connectpay.com/merchant/payments/d48c0776-27fd-4dbf-3aa6-c9cdc4124453' \
--header 'X-Request-ID: 695eca51-378b-4b06-a35c-a7d9b86cf750' \
--header 'Accept: application/json;version=1' \
--header 'Authorization: Bearer 1m49pYDXZrb....UmUGjYrqs'

Response

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.

Some providers do not provide Consumer's account information (IBAN)

debtorAccount.iban: IBAN of Consumer account.
status.isTerminal: Boolean finalisation indicator:

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

status.createdAt: Timestamp when payment order was created at Provider.
status.code: Status of payment:

  • 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.
  • Declined - Paymend declined by Provider.
  • Failed - Payment failed.
  • Abandoned - Payment canceled or abandoned at Provider OR Session expires OR Consumer cancels payment.
  • Unknown - Unknown payment status update received from Provider.

status.lastUpdatedAt: Timepstamp, when payment record was updated.
status.details.providerStatusCode: Status code from provider, if available. Usefull for failure investigation.
status.details.providerMessage: Additiona information from provider, if available. Usefull for failure investigation.
status.details.errorMessage: Error message from provider, if available. Usefull for failure investigation.

Response sample

{
	"merchant": {
		"generic1": "back-end",
		"generic2": "applications",
		"generic3": "incubate"
	},
	"payment": {
		"paymentMethod": "PIS",
		"providerCountryCode": "DE",
		"providerId": "626505e7-507a-47a5-b3a0-59db424bd12b",
		"providerName": "Test bank with data #14 EUR",
		"creditorAccount": {
			"iban": "DK9520000123456789"
		},
		"creditorName": "Schmitt - Vandervort",
		"instructedAmount": {
			"amount": "19.13",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "Horizontal uniform attitude",
		"debtorAccount": {
			"iban": "DK3500013110127523"
		}
	},
	"identifiers": {
		"merchantReference": "62d69aa4-df4f-498f-bf5c-db5b9db6d0ba",
		"creditorReference": "RF12334567",
		"endToEndId": "37YHpsqJwdp8u7c7meFbXAqTNL",
		"finnishReference": "12345",
		"finnishArchiveId": "12345",
		"norwegianKid": "12345"
	},
	"consumer": {
		"firstName": "Karelle",
		"lastName": "Champlin",
		"consumerId": "4b5cfcc7-aa34-426a-a369-c7375f003c34",
		"ipAddress": "71.67.187.181",
		"email": "Gerson_Tillman@hotmail.com"
	},
	"status": {
		"isTerminal": true,
		"createdAt": "2020-11-26T09:51:31.930Z",
		"code": "APPROVED",
		"lastUpdatedAt": "2020-11-26T09:52:30.000Z",
		"details": {
			"providerStatusCode": null,
			"providerMessage": null,
			"errorMessage": null
		}
	}
}
Undefined