Nexpay API
Access sandbox

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


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"
    }
  ]
}

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

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

200

Message

Mandatory parameter missing

Description

At least one of the method mandatory parameters are missing

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/1/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/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

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

Error codes:

CodeMessage
30000Request error
-32600Bad request
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

bankCode  string 

required

Description:

Bank SWIFT code

accounts  array of string 

required

Description:

List of all active IBAN account numbers

Error codes:

CodeMessage
30000Request error
-32600Bad request
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/1/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

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

externalPaymentId  string 

optional

Description:

Optional unique external payment ID.

Max variable size 36

useGbxForFee  boolean 

optional

Description:

Should GBX token be used to cover transaction fee

transactionSignature  string 

required

Description:

Funds amount to transfer

Transaction signature. lower-case hex representation of hmac-sha512 of concatenated request parameters (name=value) delimited by “&” symbol. Note that concatenation parameters should be in a strict order.
Note that this signature is signed with outgoing transaction message signing secret!
API keys created before 20/08/2019 won't be able to create this signature since transaction signing secret wasn't provided before this date! Please create new API key!

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
  • SUSPENDED
  • COMPLETED
  • FAILED
  • REJECTED

Error codes:

CodeMessage
30000Request error
20000Invalid request time
20010Beneficiary name too long
20020Beneficiary name too short
20030Reference information for beneficiary too long
20040Invalid transaction signature
-32600Bad request

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/1/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


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)

Error codes:

CodeMessage
30000Request error
-32600Bad request
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
  • SUSPENDED
  • COMPLETED
  • FAILED
  • REJECTED

Error codes:

CodeMessage
30000Request error
20000paymentId or externalPaymentId parameters was not provided
20010Both paymentId and externalPaymentId parameters was provided
-32600Bad request
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 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:

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

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


Error codes:

CodeMessage
30000Request error
30010Invalid request parameters
-32600Bad request
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

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

Learn more