Nexpay API

Nexpay API

Getting started

Nexpay is a Lithuanian electronic money institution (EMI) that aims to simplify the payment process and provide secure and reliable financial services to businesses.

The company's services are designed to help businesses grow by issuing them dedicated IBANs that can be used to store, send, and receive EUR SEPA payments.

To apply for a sandbox account and try our REST API, please write at [email protected].

Integration steps

  1. Contact us to get a sandbox account
  2. Login to sandbox account and generate API keys in the settings page
  3. Check our API samples
  4. Follow the instruction on this page and try out our REST API on sandbox environment
  5. Access your real account and generate API keys in the settings page
  6. Connect and start using our REST API on production environment

Environments

Basic information

Authentication

RESTful API requires HMAC-SHA512 signatures for each request.

To use this API endpoint you should get your API key and Secret key from the web application Settings page.

Each request should include the following parameters in HTTP header:

apikey  string as generated by Nexpay 

required

HTTP header field:  X-API-KEY

Description:

API key from web application Settings page

nonce  integer, less than (2^53-2) 

required

HTTP header field:  X-NONCE

Description:

Unique monotonous number. Use a millisecond or microsecond timestamp.

signature  string representation of hmac-sha512 result 

required

HTTP header field:  X-Signature

Description:

Hmac-sha512 signature of the api-key, nonce, full request path and body, signed using the signature key generated in the client cabinet in the settings page (for POST requests the body is a concatenation of parameters encoded in the x-www-form-urlencoded format)

Nonce is not monotonous

Due to network latency, requests made earlier might arrive later, making it hard to guarantee a strictly monotonous nonce for API authentication.

In case of a Nonce is not monotonous error, it is recommended to handle JSON code 50 and retry the request until it succeeds.

Signature generation pseudo-code:

    fullPath = path [+ '?' + query]
    // (example 1: /api/2/trading/orders/active?symbols=BTCEUR)
    // (example 2: /api/1/trading/new_order)

    message = apikey + '&' + nonce + fullPath [+ ? + requestBody]
    // (example 1: 4c0af59aaad960538015f35eff051336&1499263537306/api/2/trading/orders/active?account=ZAN034A01)
    // (example 2: 4c0af59aaad960538015f35eff051336&1499262973793/api/1/trading/new_order?account=ZAN034A01&clientOrderId=REST1499262973793&symbol=BTCEUR&side=buy&price=2500&quantity=0.01)

    signature = lower_case(hex(hmac_sha512(message.getBytes(‘UTF-8’), secret_key.getBytes(‘UTF-8’) )))

Javascript code (example):

var crypto = require('crypto');
...
var signature = crypto.createHmac('sha512', secretKey).update(message).digest('hex');

Error messages

In case of error in client request processing, HTTP error code is returned. Additionally, JSON object containing error description can be returned.


Possible values for HTTP error codes:

HTTP status code: 400

HTTP status code name: Bad Request

When returned:

Client request data has errors

HTTP status code: 403

HTTP status code name: Forbidden

When returned:

Missing required fields for signature check or problems with message signature

HTTP status code: 404

HTTP status code name: Not Found

When returned:

Request is sent to invalid path

HTTP status code: 500

HTTP status code name: Internal Server Error

When returned:

Client request data has errors or an unexpected server error occurred when processing the request


Data structure for error description in JSON format:

errors  array of object 

required

Description:

Error message

traceId  string 

optional

Description:

A unique identifier when an error occurs while using a service. Provide this ID when contacting support to resolve the issue faster.


Data structure for errors object

code  integer 

required

Description:

Error code

message  string 

required

Description:

Error message

data  string 

optional

Description:

Additional data about error

{
  "errors": [
    {
      "code": -32600, 
      "message": "Invalid Request", 
      "data": "Unknown symbol BTCUSD"
    }
  ],
  "traceId": "b1d88d60011a9bda350b0eef7dc8dcbb"
}

{
  "errors": [
    {
      "code": 30240, 
      "message": "Invalid cryptocurrency address"
    }
  ],
  "traceId": "092b0d1cf5dfadac6f148039d40851ea"
}

Error codes

API method calls can return the following common errors with HTTP error codes:

HTTP error code

403

JSON Code

10

Message

Missing API key

Description

API key not exists in HTTP request header

HTTP error code

403

JSON Code

20

Message

Missing nonce

Description

Nonce not exists in HTTP request header

HTTP error code

403

JSON Code

30

Message

Missing signature

Description

Signature not exists in HTTP request header

HTTP error code

403

JSON Code

40

Message

Invalid API key

Description

API key not found or have invalid format

HTTP error code

403

JSON Code

50

Message

Nonce is not monotonous

Description

Received nonce is smaller than in previous requests

HTTP error code

403

JSON Code

60

Message

Nonce is not valid

Description

Too big number or not a number

HTTP error code

403

JSON Code

70

Message

Wrong signature

Description

Specified signature is not correct

HTTP error code

403

JSON Code

80

Message

No permissions

Description

API key has no permissions to call this method

HTTP error code

403

JSON Code

90

Message

API key is not enabled

Description

Client have not enabled API key

HTTP error code

403

JSON Code

100

Message

API key locked

Description

API key is locked due to client action or Nexpay decision

HTTP error code

403

JSON Code

110

Message

Invalid client state

Description

Client account is closed or is not approved

HTTP error code

403

JSON Code

120

Message

Invalid API key state

Description

API key is deleted

HTTP error code

403

JSON Code

121

Message

Deprecated API key

Description

API key is outdated and not suitable for this feature, needs to be regenerated

HTTP error code

400

JSON Code

30000

Message

Request error

Description

The request is invalid due to some logical error

HTTP error code

400

JSON Code

30010

Message

Invalid request parameter

Description

The request parameter is incorrectly formatted or invalid

HTTP error code

500

JSON Code

-32603

Message

Internal error

Description

The request failed due to an internal error

Payment management

The diagram shows how responses should be handled when making a new payment.

Request accepted

The payment request has been created and will be processed shortly.

Request denied

The payment request has been denied.

Please, check the error code, fix the problem and then submit the request again.


Recovery check using the same externalPaymentId (recommended)

An internal error has occurred or there are technical delays.

In other words, it is unclear whether the payment was created or will be created soon.

In such cases, the procedure of the recovery check has to be carried out:

  1. Repeat payment creation using the same externalPaymentId until the request succeeds.
    • It is recommended that payment re-creation attempts are carried out with an exponential back-off algorithm.
    • The use of the same externalPaymentId will avoid the creation of duplicate payments.
  2. If payment re-creation attempts keep failing with HTTP status 5XX or timeouts, contact support at [email protected].

Recovery check without reusing the same externalPaymentId (not recommended)

If it is not possible to send the same externalPaymentId on payment re-creation attempts as part of the recovery check procedure described above, then execute this procedure instead:

  1. Poll the payment status using the externalPaymentId for X minutes.
    • If the payment status is returned, it means that the payment request was successfully created and will be processed as usual based on the returned status.
    • If the payment could not be found after X minutes (error code 30000 and data No payment found with given payment parameter), then it can be assumed that payment creation failed.
    • In case of any other error either check if your requests are valid or contact support at [email protected].

Note that this method does not guarantee that the payment will not be created after X minutes, but the chance will be low, depending on the value of X.


Repeating payment creation

A payment re-creation can only be carried out in the following cases:

  • Request denied with HTTP status 4XX when making a new payment.
  • Request failed with HTTP status 5XX or a timeout occurrs when making a new payment. In such case, the payment should be re-created using the recovery check procedure described above.
  • Payment has status REJECTED.

Repeating payment creation under any other condition may result in duplicate payments and loss of funds!


API methods

Endpoints

Account

  • POST /api/1/eurowallet/account - generates new IBAN
  • GET /api/1/eurowallet/status - returns the list of IBANs with their statuses and balances
  • GET /api/1/eurowallet/deposit-details - returns your banking details

Payments

  • POST /api/2/eurowallet/payments - makes payment to other bank account
  • POST /api/2/eurowallet/reschedule - reschedule payment
  • POST /api/2/eurowallet/cancel-scheduled - cancel scheduled payment
  • GET /api/1/eurowallet/payments/commission - returns commission amount for making payment to other bank account
  • GET /api/1/eurowallet/payments/status - returns status of a particular payment
  • GET /api/1/nexpay/payments - returns details of a particular payment
  • GET /api/1/eurowallet/payments/history - returns information about account payment history
  • GET /api/2/eurowallet/payments/fx-rate - returns a rate for a provided currency
  • GET /api/2/eurowallet/payments/swift-currencies - returns a list of supported currencies to make a SWIFT transfer

Generate new IBAN

Request:

POST /api/1/eurowallet/account

Generates a new International Bank Account Number (IBAN)


Parameters:

accountType  string 

required

Account type, must be one of these:
  • OPERATIONAL
  • CLIENT_FUNDS

tagName  string 

optional

Description:

Title for an International Bank Account Number (IBAN)

Having a title does not affect anything and can be used for your internal convenience

isCommission  boolean 

optional

Description:

Allow taking commissions from the account

By default, this value is false.


The following fields are returned:

iban  string 

required

Description:

International Bank Account Number (IBAN)

status  string 

required

Description:

International Bank Account Number (IBAN) status

Can be ACTIVE (by default) or CLOSED

balance  string 

required

Description:

International Bank Account Number (IBAN) balance

tagName  string 

required

Description:

International Bank Account Number (IBAN) title

accountType  string 

required

Description:

Type of a created account

isCommission  boolean 

required

Description:

Allow taking commissions from the account

This method allows the creation of up to 9 IBANs. In case this number is reached you will receive the following validation error: 

[
    {
        "code": 30000,
        "message": "Request error",
        "data": "Cannot open account for this customer - account limit is reached"
    }
]

If you need to have more IBANs, please get in touch with your account manager. 

POST url: /api/1/eurowallet/account

POST data: accountType=OPERATIONAL&tagName=New&isCommission=true

{
    "iban": "LT703080020000000712",
    "status": "ACTIVE",
    "balance": "0.00",
    "tagName": "New",
    "accountType": "OPERATIONAL",
    "isCommission": true
}

Get account information

Request:

GET /api/1/eurowallet/status

Returns details of either all accounts or the default account


Parameters:

allAccounts  Boolean 

optional

Description:

This parameter needs to be submitted in the request if you want to get information about all accounts

If this parameter is not provided in the request, the method will return the default account data

The following fields are returned:

accounts  array of objects 

required

Description:

Array of accounts


Account entry structure:

iban  string 

required

Description:

International Bank Account Number (IBAN)

swiftAccount  string 

required

Description:

Number of a virtual bank account

Used for SWIFT payments only

status  string 

required

Description:

International Bank Account Number (IBAN) status

Can be ACTIVE (by default) or CLOSED

balance  string 

required

Description:

International Bank Account Number (IBAN) balance

tagName  string 

required

Description:

International Bank Account Number (IBAN) title

accountType  string 

required

Description:

Type of the account

isCommission  boolean 

required

Description:

Allow taking commissions from the account

GET url: /api/1/eurowallet/status
GET data: allAccounts=true

{
  "accounts": [
    {
      "iban": "LT633080010000000208",
      "swiftAccount": null,
      "status": "ACTIVE",
      "balance": "2590.00",
      "tagName": null,
      "accountType": "OPERATIONAL",
      "isCommission": true
    },{
      "iban": "LT293080010000000238",
      "swiftAccount": "CH51087999390000000SO",
      "status": "CLOSED",
      "balance": "0.00",
      "tagName": "My account",
      "accountType": "CLIENT_FUNDS",
      "isCommission": false
    },{
      "iban": "LT023080010000000239",
      "swiftAccount": "CH51087999390000000SO",
      "status": "ACTIVE",
      "balance": "1096.80",
      "tagName": "My account 2",
      "accountType": "CLIENT_FUNDS",
      "isCommission": true
    }
  ]
}

Get banking details

Request:

GET /api/1/eurowallet/deposit-details

Returns banking details for receiving SEPA/SWIFT deposits


Parameters: no parameters

The following fields are returned:

clientName  string 

required

Description:

Your name as registered in our system

bankName  string 

required

Description:

Nexpay name

bankAddress  string 

required

Description:

Nexpay address

bicCode  string 

required

Description:

Nexpay BIC code

swift  object 

required

Description:

Deposit details for receiving SWIFT payments

accounts  array of string 

required

Description:

List of all active dedicated IBANs

For SEPA payments

swiftAccounts  array of string 

required

Description:

List of all active virtual IBANs

For SWIFT payments

SWIFT deposit detail structure:

beneficiaryName  string 

required

Description:

Recipient’s name

Sender must indicate Nexpay name as recipient

beneficiaryAddress  string 

required

Description:

Recipient’s address

Sender must indicate Nexpay address as recipient

bankName  string 

required

Description:

Bank name used when making SWIFT payments

bankAddress  string 

required

Description:

Bank address used when making SWIFT payments

bankSwiftCode  string 

required

Description:

Bank SWIFT code used when making SWIFT payments

GET url: /api/1/eurowallet/deposit-details

{
  "clientName": "John Smith",
  "bankName": "NexPay, UAB",
  "bankAddress": "J. Savickio g. 4, Vilnius, Lithuania",
  "bankCode": "NEUALT21",
  "swift": {
    "beneficiaryName": "NexPay, UAB",
    "beneficiaryAddress": "J. Savickio g. 4, Vilnius, Lithuania",
    "bankName": "Incore Bank AG",
    "bankAddress": "Grossmatt , 716, Bibern, Switzerland",
    "bankSwiftCode": "CZHHAHZL"
  },
  "accounts": [
    "LT233080020000000685",
    "LT933080020000000686",
    "LT593080020000000910"
  ],
  "swiftAccounts": [
    "CH89087999390000000U7"
  ]
}

Make new payment

Request:

POST /api/2/eurowallet/payments

Transfers funds to beneficiary account; returns a transaction ID or an error.

Note

Please, make sure payments are created and managed as described in the payment management section.


Parameters:

requestTime  64 bit integer 

required

Description:

Request time in Unix timestamp format

Precision - milliseconds.

account  string 

required

Description:

Your (Nexpay) bank account number from which the funds will be transferred

commissionAccount  string 

optional

Description:

Your (Nexpay) bank account number from which the commission will be transferred

Must be a bank account that has commissions enabled.

By default, the bank account with commissions enabled and highest balance will be used.

amount  string 

required

Description:

Payment amount

By default, the amount is assumed to be indicated in EUR.

networkType  string 

optional

Description:

Payment network through which the payment will be made

By default, network type is assumed to be SEPA.

For SWIFT payments, networkType should be specified.

beneficiaryName  string 

required

Description:

Name of the payment recipient

beneficiaryAddress  string 

optional

Description:

Address of the recipient

The field is optional and is applicable only for SEPA payments.

For SWIFT payments the address is mandatory and should be provided in beneficiaryAddressStreet, beneficiaryAddressTown, beneficiaryAddressCountry fields.

beneficiaryAccount  string 

required

Description:

Recipient’s bank account number

For the testing environment, you can indicate a randomly generated account number. Such payments will have a “PENDING” status.

In order to emulate the “COMPLETED” status, make the test payment either to one of your own IBANs (internal transfer) or to another Nexpay account’s IBAN (inter-account transfer).

beneficiaryReference  string 

required

Description:

Purpose of payment

beneficiaryBankBic  string 

conditional - required if networkType is SWIFT

Description:

Recipient bank identifier

Should be provided only if networkType = SWIFT

beneficiaryBankName  string 

optional

Description:

Recipient bank name

This field is applicable only for SWIFT payments.

useGbxForFee  boolean 

optional

Description:

Should be provided if you want to cover the payment fee with GBX token

externalPaymentId  string 

optional

Description:

Alternative payment identifier

Max variable size 36

Allowed characters: a-z, A-Z, &, -, %, whitespace and tab

This is an optional field to include your own identifier. This can be a custom ID recognized by both you and your end-customer, facilitating internal tracking and reference.

Note

It is strongly recommended to send this field, to ensure recovery check can be performed in case of unexpected errors.

beneficiaryAddressStreet  string 

conditional - required if networkType is SWIFT

Description:

Recipient street address

Should be provided only if networkType = SWIFT

beneficiaryAddressTown  string 

conditional - required if networkType is SWIFT

Description:

Recipient city

Should be provided only if networkType = SWIFT

beneficiaryAddressCountry  string 

conditional - required if networkType is SWIFT

Description:

Recipient country

Should be provided if networkType = SWIFT

The field is optional and applicable also for SEPA payments.

currency  string 

optional

Description:

Payment currency

By default, the amount is assumed to be indicated in EUR.

For SEPA and SWIFT EUR payments, the currency can be skipped.

For SWIFT non-EUR payments, the currency must be specified.

executionTime  string 

optional

Description:

Date time in UTC when payment should be executed

ISO 8601 format of yyyy-MM-ddThh:mm:ss (e.g. 2025-10-31T14:55:00).

Execution date time must be within 3 months from current date.

transactionSignature  string 

required

Description:

Transaction signature

Lower-case hmac-sha512 hex representation of the request parameters concatenated and delimited by the "&" symbol (parameter1=value1&parameter2=value2&...).

Note

Parameters for this signature must be concatenated in the same order as they appear in this list (see example on the right).

Signing is done using the outgoing transaction message signing secret.

The following fields are returned:

paymentId  string 

required

Description:

Payment ID of the processed transaction

status  string 

required

One of the following payment statuses:
  • PENDING
  • COMPLETED
  • REJECTED

Error codes:

CodeMessage
200Mandatory parameter missing
20000Invalid request time
20010Beneficiary name too long
20020Beneficiary name too short
20030Reference information for beneficiary too long
20040Invalid transaction signature
20050Invalid payment network type
20060Beneficiary bank BIC too long
20061Beneficiary bank BIC too short
20080Beneficiary bank name too long
20090Beneficiary address street too short
20091Beneficiary address street too long
20100Beneficiary address town too short
20101Beneficiary address town too long
20111Beneficiary address country invalid
20120Invalid execution date time
POST url: /api/2/eurowallet/payments

POST data: requestTime=1560246703074&account=LT023080010000000239&amount=45.00&beneficiaryName=John Smith&beneficiaryAddress=New Street 25&beneficiaryAccount=LT633080010000000208&beneficiaryReference=Invoice #314950-392&externalPaymentId=223102a35db34864b2057fa1fb1089000000&transactionSignature=c8888edc979b3ef4a54a6bb6c3fbc11e37df42ff1c9fe2fc2a12df70d68c9a22

POST url: /api/2/eurowallet/payments

POST data: requestTime=1560246703074&account=LT023080010000000239&amount=45.00&networkType=SWIFT&beneficiaryName=John Smith&beneficiaryAccount=LT633080010000000208&beneficiaryReference=Invoice #314950-392&beneficiaryBankBic=&beneficiaryBankName=Test Bank&externalPaymentId=223102a35db34864b2057fa1fb1089000000&beneficiaryAddressStreet=Street&beneficiaryAddressTown=Town&beneficiaryAddressCountry=LV&transactionSignature=c8888edc979b3ef4a54a6bb6c3fbc11e37df42ff1c9fe2fc2a12df70d68c9a22

{
    "paymentId": "30",
    "status": "PENDING"
}

Signature generation pseudo-code:

message = "requestTime=" + requestTime + "&account=" + account + "&amount=" + amount + "&beneficiaryName=" + beneficiaryName + "&beneficiaryAddress=" + beneficiaryAddress + "&beneficiaryAccount=" + beneficiaryAccount + "&beneficiaryReference=" + beneficiaryReference + "&externalPaymentId=" + externalPaymentId
transactionSignature = lower_case(hex(hmac_sha512(message.getBytes("UTF-8"), secret_key)))

example: requestTime=1560246703074&account=LT023080010000000239&amount=45.00&beneficiaryName=John Smith&beneficiaryAddress=New Street 25&beneficiaryAccount=LT633080010000000208&beneficiaryReference=Invoice #314950-392&externalPaymentId=223102a35db34864b2057fa1fb1089000000

message = "requestTime=" + requestTime + "&account=" + account + "&amount=" + amount + "&networkType=" + networkType + "&beneficiaryName=" + beneficiaryName + "&beneficiaryAccount=" + beneficiaryAccount + "&beneficiaryReference=" + beneficiaryReference + "&beneficiaryBankBic=" + beneficiaryBankBic + "&beneficiaryBankName=" + beneficiaryBankName + "&externalPaymentId=" + externalPaymentId + "&beneficiaryAddressStreet=" + beneficiaryAddressStreet + "&beneficiaryAddressTown=" + beneficiaryAddressTown + "&beneficiaryAddressCountry=" + beneficiaryAddressCountry
transactionSignature = lower_case(hex(hmac_sha512(message.getBytes("UTF-8"), secret_key)))

example: requestTime=1560246703074&account=LT023080010000000239&amount=45.00&beneficiaryName=John Smith&beneficiaryAddress=New Street 25&beneficiaryAccount=LT633080010000000208&beneficiaryReference=Invoice #314950-392&externalPaymentId=223102a35db34864b2057fa1fb1089000000

Reschedule payment

Request:

POST /api/2/eurowallet/payments/reschedule

Reschedule payment that wasn't executed yet.


Parameters:

executionTime  string 

required

Description:

Date time in UTC when payment should be rescheduled

ISO 8601 format of yyyy-MM-ddThh:mm:ss (e.g. 2025-10-31T14:55:00).

Execution date time must be within 3 months from current date.

clientPaymentId  integer 

required

Description:

Payment identifier generated by Nexpay system

Info

clientPaymentId is identical to paymentId returned in POST /api/2/eurowallet/payments response

This parameter does not need to be provided if externalPaymentId is passed in the request

externalPaymentId  string 

required

Description:

Alternative payment identifier

This parameter does not need to be provided if **clientPaymentId** is passed in the request

Response: 200 OK

Error codes:

CodeMessage
20000paymentId or externalPaymentId parameters was not provided
20010Both paymentId and externalPaymentId parameters was provided
20120Invalid execution date time
POST url: /api/2/eurowallet/payments/reschedule
POST data: executionTime=2025-03-14T20:43:11&clientPaymentId=49

or

POST url: /api/2/eurowallet/payments/reschedule
POST data: executionTime=2025-03-14T20:43:11&externalPaymentId=123102a35db34864b2057fa1fb108900

200 OK

Cancel scheduled payment

Request:

POST /api/2/eurowallet/payments/cancel-scheduled

Cancel scheduled payment that wasn't executed yet


Parameters:

clientPaymentId  integer 

required

Description:

Payment identifier generated by Nexpay system

Info

clientPaymentId is identical to paymentId returned in POST /api/2/eurowallet/payments response

This parameter does not need to be provided if externalPaymentId is passed in the request

externalPaymentId  string 

required

Description:

Alternative payment identifier

This parameter does not need to be provided if **clientPaymentId** is passed in the request

Response: 200 OK

Error codes:

CodeMessage
20000paymentId or externalPaymentId parameters was not provided
20010Both paymentId and externalPaymentId parameters was provided
POST url: /api/2/eurowallet/payments/cancel-scheduled
POST data: clientPaymentId=49

or

POST url: /api/2/eurowallet/payments/cancel-scheduled
POST data: externalPaymentId=123102a35db34864b2057fa1fb108900

200 OK

Get list of currencies

Request:

GET /api/2/eurowallet/payments/swift-currencies

Returns the list of currencies in which SWIFT payment can be made


The following fields are returned:

swiftCurrencies  array of string  

required

Description:

Array of available currencies

GET url: /api/2/eurowallet/payments/swift-currencies

{
    "swiftCurrencies": ["GBP", "USD", "EUR", "CAD", "AUD", "NZD", "SGD", "SEK", "NOK", "DKK", "PLN", "HKD", "CHF", "CZK", "JPY", "HUF", "BGN"],
}

Get currency rate

Request:

GET /api/2/eurowallet/payments/fx-rate

Returns FX rate for selected currency against euro


Parameters:

currency  string 

required

Description:

Base currency for rate calculation

By default, quote currency is EUR (e.g. GBP/EUR)

The following fields are returned:

fxRate  string 

required

Description:

FX rate

By default, quote currency is EUR (e.g. GBP/EUR) 
GET url: /api/2/eurowallet/payments/fx-rate
GET data: currency=USD

{
    "fxRate": "0.93",
}

Get commission amount

Request:

GET /api/1/eurowallet/payments/commission

Calculates commission


Parameters:

beneficiaryBankAccount  string 

required

Description:

Beneficiary bank account number

amount  string 

required

Description:

Payment amount

Must be valid decimal string with at most two fractions and value greater than 0.00

networkType  string 

optional

Description:

Payment network through which the payment will be made

By default, network type is assumed to be SEPA.

For SWIFT payments, networkType should be specified.


The following fields are returned:

commissionAmount  string 

required

Description:

Commission amount

GET url: /api/1/eurowallet/payments/commission
GET data: beneficiaryBankAccount=LT023080010000000239&amount=20.00

{
  "commissionAmount": "3.00"
}

Get payment status

Request:

GET /api/1/eurowallet/payments/status

Returns information about specific payment status


Parameters:

clientPaymentId  integer 

required

Description:

Payment identifier generated by Nexpay system

Info

clientPaymentId is identical to paymentId returned in POST /api/2/eurowallet/payments response

This parameter does not need to be provided if externalPaymentId is passed in the request

externalPaymentId  integer 

required

Description:

Alternative payment identifier

This parameter does not need to be provided if **clientPaymentId** is passed in the request

The following fields are returned:

paymentId  integer 

required

Description:

Payment identifier generated by Nexpay system

paymentId is identical to clientPaymentId

status  string 

required

Description:

Payment status

  • PENDING
  • COMPLETED
  • REJECTED

rejectReason  string 

optional

Description:

Reason for payment rejection

executionTime  string 

optional

Description:

Date time in UTC when payment should be executed

ISO 8601 format of yyyy-MM-ddThh:mm:ss (e.g. 2025-10-31T14:55:00).

Error codes:

CodeMessage
20000paymentId or externalPaymentId parameters was not provided
20010Both paymentId and externalPaymentId parameters was provided
GET url: /api/1/eurowallet/payments/status
GET data: clientPaymentId=49

or

GET url: /api/1/eurowallet/payments/status
GET data: externalPaymentId=123102a35db34864b2057fa1fb108900

{
  "paymentId": 49,
  "status": "COMPLETED"
}

Get payment details

Request:

GET /api/1/nexpay/payments

Returns information about specific payment


Parameters:

clientPaymentId  integer 

required

Description:

Payment identifier generated by Nexpay system

Info

clientPaymentId is identical to paymentId returned in POST /api/2/eurowallet/payments response

This parameter does not need to be provided if externalPaymentId is passed in the request

externalPaymentId  integer 

required

Description:

Alternative payment identifier

This parameter does not need to be provided if clientPaymentId is passed in the request


The following fields are returned:

networkType  string 

required

Description:

Payment network through which the payment was made

  • SEPA
  • SWIFT

date  string 

required

Description:

Payment processing date

ISO 8601 format of yyyy-MM-dd (e.g. 2000-10-31)

beneficiaryName  string 

required

Description:

Recipient/sender’s name

account  string 

required

Description:

Recipient/sender’s bank account number

details  string 

required

Description:

Purpose of payment

amount  string 

required

Description:

Payment amount

originalAmount  string 

conditional - if networkType is SWIFT

Description:

Original payment amount

This value is provided only for SWIFT non-EUR incoming payments

originalCurrency  string 

conditional - if networkType is SWIFT

Description:

Original payment currency

This value is provided only for SWIFT non-EUR incoming payments

runningBalance  string 

required

Description:

Your account balance after making/recieving the payment

direction  boolean 

required

Description:

Payment direction

  • INCOMING
  • OUTGOING

status  string 

required

Description:

Payment status

  • PENDING
  • COMPLETED
  • REJECTED

paymentId  string 

required

Description:

Payment identifier generated by Nexpay system

paymentId is identical to clientPaymentId

feePaymentId  string 

optional

Description:

Reference to the commission charge that is linked to this payment

externalPaymentId  string 

optional

Description:

Alternative payment identifier

batchReference  string 

optional

Description:

Reference to the batch file of which this payment is a part

otherAddressLine  string 

required

Description:

Recipient/sender’s house/apartment number

otherAddressStreet  string 

required

Description:

Recipient/sender’s street address

otherAddressTown  string 

required

Description:

Recipient/sender’s city

otherAddressPostCode  string 

required

Description:

Recipient/sender’s postal code

otherAddressCountry  string 

required

Description:

Recipient/sender’s country

ISO 3166-1 alpha-2 two-letter country code

Error codes:

CodeMessage
20000paymentId or externalPaymentId parameters were not provided
20010Both paymentId and externalPaymentId parameters were provided
GET url: /api/1/nexpay/payments
GET data: clientPaymentId=49

or

GET url: /api/1/nexpay/payments
GET data: externalPaymentId=123102a35db34864b

{
    "networkType": "SEPA",
    "date": "2024-09-18",
    "beneficiaryName": "Some beneficiary",
    "account": "LT103080010000000095",
    "details": "Test payment",
    "amount": "23.33",
    "originalAmount": null,
    "originalCurrency": null,
    "runningBalance": "807.52",
    "direction": "outgoing",
    "status": "COMPLETED",
    "paymentId": "211",
    "feePaymentId": "60",
    "externalPaymentId": "123102a35db34864b",
    "batchReference": "test",
    "otherAddressLine": "Sporto g. 7A, Vilnius, Lithuania",
    "otherAddressStreet": null,
    "otherAddressTown": null,
    "otherAddressPostCode": null,
    "otherAddressCountry": null
}

Get account history

Request:

GET /api/1/eurowallet/payments/history

Returns payments history for a specified account


Parameters:

fromDate  string 

optional

Description:

Date from which to show account statement

ISO 8601 format of yyyy-MM-dd (e.g. 2000-10-31)

toDate  string 

optional

Description:

Date until which to show account statement

ISO 8601 format of yyyy-MM-dd (e.g. 2000-10-31)

account  string 

optional

Description:

Account number (IBAN) for which to generate a statement

If account number (IBAN) is not provided, the statement will be generated for default account

The following fields are returned:

debitTurnover  string 

required

Description:

Debit turnover

creditTurnover  string 

required

Description:

Credit turnover

balanceStart  string 

required

Description:

Balance at the beginning of the selected period

balanceEnd  string 

required

Description:

Balance at the end of the selected period

clientName  string 

required

Description:

Your name as registered in our system

account  string 

required

Description:

Account number (IBAN) for which the statement is generated

entries  array of objects 

required

Description:

Array of payments


Payment entry structure:

networkType  string 

required

Description:

Payment network through which the payment was made

  • SEPA
  • SWIFT

date  string 

required

Description:

Payment date

ISO 8601 format of yyyy-MM-dd (e.g. 2000-10-31)

beneficiaryName  string 

required

Description:

Recipient/sender’s name

account  string 

required

Description:

Payment account number (IBAN)

details  string 

required

Description:

Payment description

amount  string 

required

Description:

Payment amount

originalAmount  string 

conditional - if networkType is SWIFT

Description:

Original payment amount

This value is provided only for SWIFT non-EUR incoming payments

originalCurrency  string 

conditional - if networkType is SWIFT

Description:

Original payment currency

This value is provided only for SWIFT non-EUR incoming payments

runningBalance  string 

required

Description:

Your account balance after making/recieving the payment

direction  string 

required

Description:

Payment direction

  • INCOMING
  • OUTGOING

paymentId  string 

required

Description:

Payment identifier generated by Nexpay system

paymentId is identical to clientPaymentId

externalPaymentId  string 

optional

Description:

Alternative payment identifier

feePaymentId  string 

optional

Description:

Reference to the commission charge that is linked to this payment

GET url: /api/1/eurowallet/payments/history
GET data: fromDate=2019-05-01&toDate=2019-07-04&account=LT023080010000000239

{
  "debitTurnover": "0.00",
  "creditTurnover": "248.00",
  "balanceStart": "187.03",
  "balanceEnd": "395.83",
  "clientName": "Tester User",
  "account": "LT103080010000000095",
  "entries": [
    {
        "networkType": "SEPA",
        "date": "2024-02-01",
        "beneficiaryName": "NexPay, UAB",
        "account": "LT000000000000000001",
        "details": "Excepteur nulla pariatur cupidatat adipisicing nostrud commodo tempor mollit dolor amet eiusmod non eu id.",
        "amount": "14.00",
        "runningBalance": "979.50",
        "direction": "outgoing",
        "paymentId": "37"
    },
    {
        "networkType": "SEPA",
        "date": "2023-02-01",
        "beneficiaryName": "NexPay, UAB",
        "account": "LT000000000000000001",
        "details": "Ipsum non esse adipisicing aliquip ex est sit pariatur ad voluptate aliqua.",
        "amount": "1751.00",
        "runningBalance": "20979.50",
        "direction": "incoming",
        "paymentId": "37"
    }
  ]
}

API webhook

Description

Nexpay webhooks allow you to subscribe to events that happen within your Nexpay account and receive HTTP notifications to an endpoint you configure. Webhooks are available in both the sandbox account and real account.


To start using webhooks:

  1. You must deploy an HTTPS endpoint capable of handling webhook notifications, according to the specification below
  2. Contact [email protected] to configure webhook subscriptions and credentials for you account

Specification

Each webhook notification will be sent in the following format:

Method: POST

Headers:

  • Content-Type: application/json
  • X-Signature: <signature>

Body:

{
    "event": "<event_name>",
    "payload": {
        ...
    }
}

The "X-Signature" header contains a signature the receiver must verify to ensure that the notification has been sent by Nexpay and has not been tampered with. The signature is generated from the request body using the ECDSA-SHA512 algorithm and the NIST P-256 curve. It will be sent as a hexdecimal string in the ASN.1 DER encoding.


You will receive the PEM encoded EC public key used for signature verification after successfully contacting Nexpay and registering your webhook subscription.


Below is an example of the request body, signature and public key that can be used to test signature verification:

{"payload":{"paymentId":27,"feePaymentId":null,"externalPaymentId":null,"batchReference":null,"account":"LT953080020000000650","amount":"5.01","direction":"incoming","status":"COMPLETED","date":"2024-06-06","networkType":"SEPA","otherName":"Roach Combs LLC","otherAccount":"LT093080020000000646","details":"Test payment 501","originalAmount":null,"originalCurrency":null,"runningBalance":"18.08"},"event":"payment.status"}

3045022026cfb1ace150acf7547db537e74772950bc03a96e14d50ae085a6853cc52b033022100ed30a1a50874622b0e74fe4874ed1b72d995d647ea3be135019a8ce2a8fcbe22

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY3GPZkskfkKHCCysnSQEqgcQxs+W
oV3EubNu6uIb35QaIgFjatt+9go1ulcWRO9jdrDbKHzf+Jmb35q6yvimLA==
-----END PUBLIC KEY-----

Events

Payments

  • payment.status - status change event for an outgoing or incoming SEPA/SWIFT payment

Payment status

Status change events for an outgoing or incoming SEPA/SWIFT payment.


The following fields are returned in the payload:

paymentId  string 

required

Description:

Internal payment identifier

account  string 

required

Description:

The account receiving or sending funds

amount  string 

required

Description:

Transaction amount

direction  boolean 

required

Description:

Payment direction (values: incoming or outgoing)

status  boolean 

required

Description:

Payment status (values: COMPLETED or REJECTED)

networkType  string 

required

Description:

Payment network, one of SEPA or SWIFT

otherName  string 

required

Description:

Name of the other counterparty receiving or sending funds

otherAccount  string 

required

Description:

Account of the other counterparty receiving or sending funds

originalAmount  string 

conditional - if networkType is SWIFT

Description:

The original amount transferred in the SWIFT transaction (currently only for SWIFT deposits)

originalCurrency  string 

conditional - if networkType is SWIFT

Description:

The original currency transferred in the SWIFT transaction (currently only for SWIFT deposits)

feePaymentId  string 

optional

Description:

The ID of the linked commission charge transaction

externalPaymentId  string 

optional

Description:

External payment identifier (provided by client at payment initiation call)

batchReference  string 

optional

Description:

Reference of the batch payment that the payment is part of

date  string in ISO 8601 format of yyyy-MM-dd, e.g. "2000-10-31" 

optional

Description:

Transaction date

details  string 

optional

Description:

Transaction details

runningBalance  string 

optional

Description:

Account balance at the time of the transaction

rejectReason  string 

optional

Description:

Reason for payment rejection

{
    "event": "payment.status",
    "payload": {
        "paymentId": "132",
        "account": "LT103080010000000095",
        "amount": "23.33",
        "direction": "incoming",
        "status": "COMPLETED",
        "networkType": "SEPA",
        "otherName": "Test company",
        "otherAccount": "LT103080010000000601",
        "feePaymentId": "133",
        "externalPaymentId": "8c306b2e-36a8-49ad-a766-8155e071b6df",
        "batchReference": "batch-123843",
        "date": "2023-08-07",
        "details": "Test payment",
        "runningBalance": "188.03"
    }
}
Last Updated:
Contributors: C.Gutfrics, Ralfs Braunfelds, artursp, Artur, Arturs D

We use cookies to improve your experience and analyse site's usage. By using our site, you consent to cookies.

Learn more