FIX API, RESTful API, Streaming API

Getting Started

Nexpay API provides RESTful API to access and manage your accounts

RESTful API

Basic information

Service endpoints

Production environment:

Endpoint	Description
https://api.globitex.com	Service endpoint for RESTful API calls

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	HTTP status code name	When returned
400	Bad Request	Client request data has errors
403	Forbidden	Missing required fields for signature check or problems with message signature
404	Not Found	Request is sent to invalid path
500	Internal Server Error	Unexpected server error occurred when processing client request

Data structure for error description in JSON format:

Field	Required	Type	Description
errors	Yes	array of object	Error message

Data structure for errors object

Field	Required	Type	Description
code	Yes	integer	Error code
message	Yes	string	Error message
data	No	string	Additional data about error

Example responses:

"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	JSON Code	Message	Description
403	10	Missing API key	API key not exists in HTTP request header
403	20	Missing nonce	Nonce not exists in HTTP request header
403	30	Missing signature	Signature not exists in HTTP request header
403	40	Invalid API key	API key not found or have invalid format.
403	50	Nonce is not monotonous	Received nonce is smaller than in previous requests
403	60	Nonce is not valid	Too big number or not a number
403	70	Wrong signature	Specified signature is not correct
403	80	No permissions	API key has no permissions to call this method
403	90	API key is not enabled	Client have not enabled API key
403	100	API key locked	API key is locked due to client action or Nexpay decision
403	110	Invalid client state	Client account is closed or is not approved
403	120	Invalid API key state	API key is deleted
400	200	Mandatory parameter missing	At least one of the method mandatory parameters are missing

API sample

API samples can be found here: https://github.com/globitex/api-samples

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:

Parameter	HTTP header field	Required	Type	Description
apikey	X-API-Key	Yes	string as generated by Nexpay	API key from web application Settings page
nonce	X-Nonce	Yes	integer, less than (2^53-2)	unique monotonous number that should be generated on the client. Hint: use millisecond or microsecond timestamp
signature	X-Signature	Yes	string representation of hmac-sha512 result	uri, nonce and requestBody (for POST requests body is a concatenation of parameters encoded in x-www-form-urlencoded)

Signature generation pseudo-code:

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

message = apikey + '&' + nonce + uri [+ ? + 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');

Nexpay methods

RESTful API provides access to Nexpay data with the following methods:

transfer funds to beneficiary account - /api/1/eurowallet/payments
return account status information - /api/1/eurowallet/status
return deposit information - /api/1/eurowallet/deposit-details
return payment history - /api/1/eurowallet/payments/history
return payment status - /api/1/eurowallet/payments/status
get transfer commission amount - /api/1/eurowallet/payments/commission

Create new payment

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

Request: POST /api/1/eurowallet/payments

Parameters:

Parameter	Required	Type	Description
requestTime	Yes	64 bit integer	Request time in Unix timestamp format. Precision - milliseconds
account	Yes	string	Account number from what the funds will be transferred
amount	Yes	string	Funds amount to transfer
beneficiaryName	Yes	string	Beneficiary name of the specified beneficiary account
beneficiaryAddress	No	string	Beneficiary address
beneficiaryAccount	Yes	string	IBAN account number for the beneficiary
beneficiaryReference	Yes	string	Reference for beneficiary
externalPaymentId	No	string	Optional unique external payment ID
useGbxForFee	No	boolean	Should GBX token be used to cover transaction fee
transactionSignature	Yes	string	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:

Field	Required	Type	Description
paymentId	Yes	string	Payment ID of the processed transaction
status	Yes	string	One of the following payment statuses: PENDING SUSPENDED COMPLETED FAILED REJECTED

Error codes:

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

Suggested work-flow:

recovery flow

Example request:

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=223102a35db34864b2057fa1fb108900&transactionSignature=c8888edc979b3ef4a54a6bb6c3fbc11e37df42ff1c9fe2fc2a12df70d68c9a22

Example response:

{
"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=223102a35db34864b2057fa1fb108900

Get Account Status

Returns default (single) or all account status information.

Request: GET /api/1/eurowallet/status

Parameters:

Parameter	Required	Type	Description
allAccounts	No	Boolean	Indicates that all existing account status should be returned, otherwise the default account status will be shown

The following fields are returned:

Field	Required	Type	Description
accounts	Yes	array of objects	Array of accounts
iban	Yes	string	IBAN number
status	Yes	string	IBAN status (ACTIVE/CLOSE)
balance	Yes	string	Account balance

Error codes:

Code	Message
30000	Request error
-32600	Bad request

Example request:

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

Example response:

{
  "accounts": [
    {
      "iban": "LT633080010000000208",
      "status": "ACTIVE",
      "balance": "2590.00"
    },{
      "iban": "LT293080010000000238",
      "status": "CLOSED",
      "balance": "0.00"
    },{
      "iban": "LT023080010000000239",
      "status": "ACTIVE",
      "balance": "1096.80"
    }
  ]
}

Get Deposit Details

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

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

Parameters: no parameters

The following fields are returned:

Field	Required	Type	Description
clientName	Yes	string	Client full name
bankName	Yes	string	Bank name where EURO Wallet is in use
bankAddress	Yes	string	Bank address
bankCode	Yes	string	Bank SWIFT code
accounts	Yes	array of string	List of all active IBAN account numbers

Error codes:

Code	Message
30000	Request error
-32600	Bad request

Example request:

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

Example response:

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

Get Payment History

Returns payment history for provided account.

Request: GET /api/1/eurowallet/payments/history

Parameters:

Parameter	Required	Type	Description
fromDate	No	String in ISO 8601 format of yyyy-MM-dd, e.g. "2000-10-31"	Date from to display account history
toDate	No	String in ISO 8601 format of yyyy-MM-dd, e.g. "2000-10-31"	End date of account history to use in search criteria
account	No	string	Account IBAN number to use in search criteria. If not provided then default account number will be used

The following fields are returned:

Field	Required	Type	Description
debitTurnover	Yes	string	Debit turnover balance
creditTurnover	Yes	string	Credit turnover balance
balanceStart	Yes	string	Balance start amount
balanceEnd	Yes	string	Balance end amount
clientName	Yes	string	Client full name
account	Yes	string	Account holder\`s IBAN number
entries	Yes	array of objects	Array of account transaction entries, see structure in table bellow

Payment entry structure:

Field	Required	Type	Description
date	Yes	string	Transaction date
beneficiaryName	Yes	string	Beneficiary name
account	Yes	string	Transaction account IBAN number
details	Yes	string	Transaction details
amount	Yes	string	Transaction amount
runningBalance	Yes	string	Account balance state
direction	Yes	boolean	Payment direction (values: incoming or outgoing)
paymentId	Yes	string	Internal Payment identifier
externalPaymentId	No	string	External Payment identifier (provided by client at payment initiation call)

Error codes:

Code	Message
30000	Request error
30010	Invalid request parameters
-32600	Bad request

Example request:

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

Example response:

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

Get Payment Status

Returns payment status information.

Request: GET /api/1/eurowallet/payments/status

Parameters:

Parameter	Required	Type	Description
clientPaymentId	No, if externalPaymentId was provided	integer	Client payment ID number. If externalPaymentId parameter was provided then field should be NOT included
externalPaymentId	No, if clientPaymentId was provided	string	External payment ID. If clientPaymentId parameter was provided then field should be NOT included

The following fields are returned:

Field	Required	Type	Description
paymentId	Yes	integer	Payment ID number
status	Yes	string	One of the following payment statuses: PENDING SUSPENDED COMPLETED FAILED REJECTED

Error codes:

Code	Message
30000	Request error
20000	paymentId or externalPaymentId parameters was not provided
20010	Both paymentId and externalPaymentId parameters was provided
-32600	Bad request

Example request:

GET url: /api/1/eurowallet/payments/status
GET data: clientPaymentId=49

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

Example response:

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

Get Payment Commission Amount

Returns Payment Commission Amount

Request: GET /api/1/eurowallet/payments/commission

Parameters:

Parameter	Required	Type	Description
beneficiaryBankAccount	Yes	string	Beneficiary bank account number (must be a valid IBAN account)
amount	Yes	string	Payment amount. Must be valid decimal string with at most two fractions and value greater than 0.00

The following fields are returned:

Field	Required	Type	Description
commissionAmount	Yes	string	Amount that will be taken as fee (if GBX (Globitex Token) fee settlement will not be used)

Error codes:

Code	Message
30000	Request error
-32600	Bad request

Example request:

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

Example response:

{
  "commissionAmount": "3.00"
}