Neopay integration specification V2.29 PSD2

Neopay payment initiation module integration specification

1. Initiating a payment window

The payment window is initiated by javascript. Therefore, it is necessary to include the following javascript file.

<script type="text/javascript" src="https://psd2.neopay.lt/widget.js"></script>

Payment window initiation called by using the NEOWidget.initialize method.

var NEOWidgetHost = "https://psd2.neopay.lt";

NEOWidget.initialize(
  NEOWidgetHost,
  data.token,
  {
   'other':'off',
   'creditor': 'HABALT22',
   'css':'yours_css_url.css',
   'default_country':'LT',
   'default_language':'LV',
   'callback_url':'https://myproject.com/redirect_flow'
   }
);

1.1. Token

Initiating a payment window, you need to submit a token data.token, which is a JWT token ( https://jwt.io/ ).

Token is signed with the projects secret, issued by Neo Finance.

Token payload

{
  "projectId": 1,
  "amount": 0.1,
  "paymentPurpose": "IPS Demonstration",
  "receiverName": "NEO Finance",
  "payerCode": "38400081104",
  "receiverAccountNumber": "LT463520037067823082",
  "transactionId": "697a0b6b",
  "payerPhoneNumber": "+37062057581",
  "currency": "EUR"
}
The variable Explanations Required field Type Example of value
projectId A unique project ID given by Neo Finance YES INTEGER 1
amount Payment initiation amount YES DOUBLE 0.1
paymentPurpose Payment purpose YES VARCHAR(255) IPS Demonstration
payerCode Submitted when a person with a pre-known personal code is being checked to match bank account holder’s personal code. Where a personal code is valid personal code of a Lithuanian citizen. If payments is made when this variable is provided - it means the payer code matched with provided payer code. This solution is currently working with HABALT22, CBVILT2X NO VARCHAR(255) 33309058638
transactionId Transaction Id provided by you. It should be unique for each payment initiation. YES VARCHAR(255) 697a0b6b
payerPhoneNumber Payer phone number NO VARCHAR(255) +370620575781
currency Payment currency NO VARCHAR(255) One possible value: EUR

Note: “paymentPurpose” and “transactionId” the total number of characters may not exceed 140.

When money from clients are being collected to accounts opened in other banks than Neo Finance. This should be known when configuring the projectId provided by Neo Finance.

The variable Explanations Required field Type Example of value
receiverName Beneficiary’s companies name or name, surname YES VARCHAR(255) Ltd Company name, John Johnson
receiverAccountNumber Beneficiary’s (company or person’s) account number in IBAN format. YES VARCHAR(255) LT359623025677463023

When the money from clients are being collected to the Neo finance - your company should open an IBAN account at Neo finance. Besides that the Beneficiary’s account, as well as the Beneficiary’s name, are pre-configured in projectId and variables “receiverName”, “ReceiverAccountNumber” shouldn’t be provided to tokens payload when initiating a payment.

1.2. Additional payment initiation parameters

The variable Explanations Required field Example of value
other When the “Other bank” option needs to be disabled in the payment initiation window. NO off
creditor When initiating a payment, you can pre-select a bank choice. Used when banks selection is provided in your side. Should be provided bank BIC code. OTHER is used when there is a need tho initiate a payment with only payment details provided. Should be provided only one BIC. Array is not supported. NO HABALT22, CBVILT2X, NDEAEE2X, OTHER
css Provided when there is a need to use your personalised style for the payment widget. NO URL to CSS file
default_country This variable is used when there is a need to provide certain country bank list. Country code should be provided in ISO 3166-1 Alpha-2 code format. NO LT, LV, EE, NL
default_language This variable is used when there is a need to set a certain language of the Neopay widget. Language code should be provided in ISO 639-1 code format. NO LT, LV, ET, NL, EN
payer_consent_neopay_rules This variable is used when there is a need to skip the first step for payment initiation at Neopay widget and redirect a payer directly to the bank for authentification. It can be only used when creditor variable is provided. This feature works only with the banks which don’t require an additional information to be provided for authentification (currently works with Swedbank and SEB). NO 1,0
callback_url Redirect flow is enabled when this variable is provided. The callback URL should be different from the one is used to receive callbacks about Signed and Confirmed payments. YES https://myproject.com/redirect_flow

You can explore more details about our api in this JSON file https://psd2.neopay.lt/api/countries

2. Canceled payment by client

When the payment is canceled by the client, we redirect the client to provided callback_url with additional variable at the end of the URL canceled=1 e.g. https://myproject.com/redirect_flow?canceled=1

3. Successful payment

If the payment has been signed successfully by the client, we redirect the client to provided callback_url with additional variable at the end of the URL token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2FjdGlvbklkIjoiOTYxNDY1Y2IiLCJwYXllckNvZGVNYXRjaGVzIjp0cnVlLCJpYXQiOjE0OTMyMDg0OTgsImV4cCI6MTQ5MzI5NDg5OH0.msTdcBXihK-CBlxqHr6aSwViYGm_OvU-KAjqSOWO0Eg e.g. https://myproject.com/redirect_flow?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0cmFuc2FjdGlvbklkIjoiMTU3NTg5MzUwNy02ODIiLCJwYXllckFjY291bnROdW1iZXIiOiJMVDUwNzMwMDAxMDEwMjA3ODE3MyIsImN1cnJlbmN5IjoiRVVSIiwiYW1vdW50IjowLjAxLCJpYXQiOjE1NzU4OTM1NDUsImV4cCI6MTU3NTk3OTk0NSwic3RhdHVzIjoic2lnbmVkIn0.Rds2WfYgq7yXO5E773ywAzJqJbrcg7TgT_J0jh1oczo

Where token is a JWT token signed by your secret, so it needs to be validate on server side to make sure it is a Neopay signed response. Example of signature token payload:

{
  "transactionId": "697a0b6b",
  "payerAccountNumber": "LT507300010102078173",
  "currency": "EUR",
  "amount": 0.01,
  "iat": 1575893545,
  "exp": 1575979945,
  "payerPhoneNumber": "+37062057581"
  "status": "signed"
}
The variable Explanations Example
transactionId A unique transaction number that was submitted when initiating a payment. 697a0b6b
payerAccountNumber Payer account number LT507300010102078173
currency What’s the payment currency EUR
amount Payment initiation amount 0.10
iat The time it was issued. 1575893545
exp Expiry date. 1575979945
payerPhoneNumber This variable will be provided if it was set when the payment was initiated +37062057581
status Status type One possible value “signed”

If Money are collected to the IBAN which is opened at Neo Finance, the money are going to be deposited to your account within 2 minutes after you receive this event. If money are collected to the IBAN account which is not at Neo finance, the funds from the client are expecting to be received with a next payment clearing cycle.

4. Confirmation of completed payment and received funds to the specified callback URL address

Provided callback URL (which is preconfigured in the project and it’s different from the one you provide in callback_url when initiating the payment) will be used to notify about signed and confirmed transactions. Instantly, after receiving signed payment response from the Bank, we POST a request to callback URL with a body of JSON

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2FjdGlvbklkIjoiOTYxNDY1Y2IiLCJwYXllckNvZGVNYXRjaGVzIjp0cnVlLCJpYXQiOjE0OTMyMDg0OTgsImV4cCI6MTQ5MzI5NDg5OH0.msTdcBXihK-CBlxqHr6aSwViYGm_OvU-KAjqSOWO0Eg"
}

Token is signed with your secret. Token payload

{
  "transactions": {
    "697a0b6b": {
      "status": "success",
      "action": "signed",
      "payerName": "Vardas Pavardė",
      "payerAccountNumber": "Mokėtojo sąskaitos numeris",
      "paymentPurpose": "IPS Demonstracija",
      "payerPhoneNumber": "+37062057581",
      "confirmedAt": "2017-04-26T12:08:18.037Z"
    }
  },
  "iat": 1493209390,
  "exp": 1493295790
}

It is expected to get a JSON response within 10 seconds, when a callback is successfully received by you

{ "status": "success" }

If we don’t get the success status. We will repeat POSTing the request in 5 minutes. We will repeat this step until we get a response status success.

The variable Explanations Example of value
transactionId A unique transaction number which was submitted when initiating a payment. Your transaction number
status Payment status success
action Payment action signed, confirmed
payerName Payer’s name, surname. This variable is provided when action variable value is confirmed
paymentPurpose Payment which was provided when initiating the payment.
payerAccountNumber Payer’s account number in IBAN format LT317300010090854742
iat The time it was issued.
confirmedAt When the money has been received. This variable is provided when action variable value is confirmed 2017-04-26T12:08:18.037Z
exp Expiry date.
currency What’s the payment currency EUR
payerPhoneNumber This variable will be provided if it was set when the payment was initiated +37062057581

Action variable value meanings

Value Explanations
signed Indicates that the response is received notifying about successfully signed payment initiation from client side. Sign action is usually used to indicate, that payment process has ended successfully and payers funds expected to be received with a next payment clearing cycle.
confirmed Indicates that the response is received notifying about successfully confirmed payment (received funds). Confirmed action is usually used when there is an additional need to make sure the money has been successfully received. This variable value may be used (not mandatory) only if money are collected to the IBAN opened at Neo finance.

5. WorkFlow

mip_flow_psd2_en.jpg