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 that should be generated on the client. Hint: use 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)

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 errorsUnexpected server error occurred when processing client request


Data structure for error description in JSON format:

errors  array of object 

required

Description:

Error message

traceId  string 

optional

Description:

Include the Trace ID in your ticket to help the support team quickly diagnose and solve your issue


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

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
  • 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

Generate new IBAN

Request:

POST /api/1/eurowallet/account


Parameters:

tagName  string 

optional

Description:

IBAN account name


The following fields are returned:

iban  string 

required

Description:

IBAN

status  string 

required

Description:

IBAN status (ACTIVE/CLOSE)

balance  string 

required

Description:

IBAN’s current balance

tagName  string 

required

Description:

IBAN’s name

This method allows the creation of up to 7 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

{
    "iban":"LT703080020000000712",
    "status":"ACTIVE",
    "balance":"0.00",
    "tagName":"New"
}

Get account information

Request:

GET /api/1/eurowallet/status

Returns default (single) or all account status information.


Parameters:

allAccounts  Boolean 

optional

Description:

Indicates that all existing account status should be returned, otherwise the default account status will be shown


The following fields are returned:

accounts  array of objects 

required

Description:

Array of accounts


Account entry structure:

iban  string 

required

Description:

IBAN number

status  string 

required

Description:

IBAN status (ACTIVE/CLOSE)

balance  string 

required

Description:

Account balance

tagName  string 

required

Description:

IBAN’s name

swiftAccount  string 

optional

Description:

The virtual SWIFT account number

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

{
  "accounts": [
    {
      "iban": "LT633080010000000208",
      "status": "ACTIVE",
      "balance": "2590.00",
      "tagName": null
    },{
      "iban": "LT293080010000000238",
      "status": "CLOSED",
      "balance": "0.00",
      "tagName": "My account"
    },{
      "iban": "LT023080010000000239",
      "status": "ACTIVE",
      "balance": "1096.80",
      "tagName": "My account 2"
    }
  ]
}

Get banking details

Request:

GET /api/1/eurowallet/deposit-details

Returns deposit information, such client full name with bank requisites.


Parameters: no parameters

The following fields are returned:

clientName  string 

required

Description:

Client full name

bankName  string 

required

Description:

Bank name where EURO Wallet is in use

bankAddress  string 

required

Description:

Bank address

bicCode  string 

required

Description:

Bank SWIFT code

accounts  array of string 

required

Description:

List of all active IBAN account numbers

swiftAccounts  array of string 

required

Description:

List of all active virtual SWIFT account numbers

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

{
  "clientName": "John Smith",
  "bankName": "NexPay, UAB",
  "bankAddress": "J. Savickio g. 4, Vilnius, Lithuania",
  "bankCode": "NEUALT21"
}

Make new payment

Request:

POST /api/2/eurowallet/payments

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


Parameters:

requestTime  64 bit integer 

required

Description:

Request time in Unix timestamp format. Precision - milliseconds

account  string 

required

Description:

Account number from what the funds will be transferred

amount  string 

required

Description:

Funds amount to transfer

networkType  string 

optional

Description:

Payment network, must be one of SEPA or SWIFT, defaults to SEPA

beneficiaryName  string 

required

Description:

Beneficiary name of the specified beneficiary account

beneficiaryAddress  string 

optional

Description:

Beneficiary address

beneficiaryAccount  string 

required

Description:

IBAN account number for the beneficiary

For the testing environment, you can indicate a randomly generated IBAN account. As there is no clearing for test payments to external IBANs, such transactions 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:

Reference for beneficiary

beneficiaryBankBic  string 

conditional - required if networkType is SWIFT

Description:

The BIC code of the SWIFT beneficiary bank

beneficiaryBankName  string 

conditional - required if networkType is SWIFT

Description:

The name of the SWIFT beneficiary bank

beneficiaryBankAddress  string 

conditional - required if networkType is SWIFT

Description:

The address of the SWIFT beneficiary bank

useGbxForFee  boolean 

optional

Description:

Should GBX token be used to cover transaction fee

externalPaymentId  string 

optional

Description:

Optional unique external payment ID.

Max variable size 36

transactionSignature  string 

required

Description:

Transaction signature. Lower-case hmac-sha512 hex representation of concatenated request parameters (name=value) delimited by the “&” symbol. Note that concatenation parameters should be in a strict order.

Note that this signature is signed with 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
20070Beneficiary bank address too short
20071Beneficiary bank address too long
20080Beneficiary bank name too long

Request accepted

Payment is accepted and should be in processing

Request denied

Request was denied. Error should be reviewed, resolved and then request should be retried

Recovery check

Payment request maybe accepted, for this reason checking should be performed. In order to perform recovery checks externalPaymentld must be provided in the initial request. There are several approaches to perform this: Preferred way: check payment status by querying payment status using externalPaymentld. Alternate way: retry payment create request (IMPORTANT: must provide the same externalPaymentld)

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

{
    "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

Get Commission Amount

Request:

GET /api/1/eurowallet/payments/commission

Returns Payment Commission Amount


Parameters:

beneficiaryBankAccount  string 

required

Description:

Beneficiary bank account number (must be a valid IBAN account)

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, must be one of SEPA or SWIFT, defaults to SEPA


The following fields are returned:

commissionAmount  string 

required

Description:

Amount that will be taken as fee (if GBX (Globitex Token) fee settlement will not be used)

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 payment status information.


Parameters:

clientPaymentId  integer 

required

Description:

Client payment ID number. If externalPaymentId parameter was provided then field should be NOT included

externalPaymentId  integer 

required

Description:

External payment ID. If clientPaymentId parameter was provided then field should be NOT included

The following fields are returned:

paymentId  integer 

required

Description:

Payment ID number

status  string 

required

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

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 payment details.


Parameters:

clientPaymentId  integer 

required

Description:

Client payment ID number. If externalPaymentId parameter was provided then field should NOT be included

externalPaymentId  integer 

required

Description:

External payment ID. If clientPaymentId parameter was provided then field should NOT be included


The following fields are returned:

networkType  string 

required

Description:

Payment network, one of SEPA or SWIFT

date  string 

required

Description:

Transaction date

beneficiaryName  string 

required

Description:

Beneficiary name

account  string 

required

Description:

Transaction account IBAN number

details  string 

required

Description:

Transaction details

amount  string 

required

Description:

Transaction amount

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)

runningBalance  string 

required

Description:

Account balance state

direction  boolean 

required

Description:

Payment direction (values: incoming or outgoing)

status  string 

required

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

paymentId  string 

required

Description:

Internal Payment identifier

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


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

{
    "date": "2023-08-07",
    "beneficiaryName": "Some beneficiary",
    "account": "LT103080010000000095",
    "details": "Test payment",
    "amount": "23.33",
    "runningBalance": "188.03",
    "direction": "incoming",
    "status": "COMPLETED",
    "paymentId": "49",
    "feePaymentId": "60",
    "externalPaymentId": "123102a35db34864b",
    "batchReference": "test"
}

Get Account history

Request:

GET /api/1/eurowallet/payments/history

Returns payment history for provided account.


Parameters:

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

optional

Description:

Date from to display account history

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

optional

Description:

End date of account history to use in search criteria

account  string 

optional

Description:

Account IBAN number to use in search criteria. If not provided then default account number will be used


The following fields are returned:

debitTurnover  string 

required

Description:

Debit turnover balance

creditTurnover  string 

required

Description:

Credit turnover balance

balanceStart  string 

required

Description:

Balance start amount

balanceEnd  string 

required

Description:

Balance end amount

clientName  string 

required

Description:

Client full name

account  string 

required

Description:

Account holder`s IBAN number

entries  array of objects 

required

Description:

Array of account transaction entries, see structure in table bellow


Payment entry structure:

networkType  string 

required

Description:

Payment network, one of SEPA or SWIFT

date  string 

required

Description:

Transaction date

beneficiaryName  string 

required

Description:

Beneficiary name

account  string 

required

Description:

Transaction account IBAN number

details  string 

required

Description:

Transaction details

amount  string 

required

Description:

Transaction amount

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)

runningBalance  string 

required

Description:

Account balance state

direction  boolean 

required

Description:

Payment direction (values: incoming or outgoing)

paymentId  string 

required

Description:

Internal Payment identifier

externalPaymentId  string 

optional

Description:

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

feePaymentId  string 

optional

Description:

The ID of the linked commission charge transaction

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": [
    {
      "date": "2019-01-31",
      "amount": "1.00",
      "runningBalance": "188.03",
      "direction": "incoming",
      "paymentId": "275",
      "externalPaymentId": "MyID000123"
    },
    {
      "date": "2019-01-31",
      "details": "Some vala",
      "amount": "123.00",
      "runningBalance": "311.03",
      "direction": "incoming",
      "paymentId": "276"
    },
    {
      "date": "2019-01-31",
      "details": "Testing 123",
      "amount": "123.00",
      "runningBalance": "434.03",
      "direction": "incoming",
      "paymentId": "277",
      "feePaymentId": "222381"
    }
  ]
}
Last Updated:
Contributors: C.Gutfrics, Artur

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

Learn more