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
- Contact us to get a sandbox account
- Login to sandbox account and generate API keys in the settings page
- Check our API samples
- Follow the instruction on this page and try out our REST API on sandbox environment
- Access your real account and generate API keys in the settings page
- Connect and start using our REST API on production environment
Environments
Environment | Endpoint |
---|---|
Sandbox | https://api-beta.tst.globitex.com |
Production | https://api.globitex.com |
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)
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
Error codes
API method calls can return the following common errors with HTTP error codes:
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
403
200
Mandatory parameter missing
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/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.
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:
Code | Message |
---|---|
30000 | Request error |
-32600 | Bad request |
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:
Code | Message |
---|---|
30000 | Request error |
-32600 | Bad request |
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.
useGbxForFee boolean
optional
Description:
Should GBX token be used to cover transaction fee
transactionSignature string
required
Description:
Funds amount to transfer
The following fields are returned:
paymentId string
required
Description:
Payment ID of the processed transaction
status string
required
- PENDING
- COMPLETED
- 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 |
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)
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:
Code | Message |
---|---|
30000 | Request error |
-32600 | Bad request |
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
- PENDING
- COMPLETED
- 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 |
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:
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)
status string
required
- 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:
Code | Message |
---|---|
30000 | Request error |
20000 | paymentId or externalPaymentId parameters were not provided |
20010 | Both paymentId and externalPaymentId parameters were provided |
-32600 | Bad request |
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:
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:
Code | Message |
---|---|
30000 | Request error |
30010 | Invalid request parameters |
-32600 | Bad request |