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