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
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
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
121
Deprecated API key
API key is outdated and not suitable for this feature, needs to be regenerated
400
30000
Request error
The request is invalid due to some logical error
400
30010
Invalid request parameter
The request parameter is incorrectly formatted or invalid
500
-32603
Internal error
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 - GET
/api/2/eurowallet/payments/fx-rate- returns a rate for a provided currency - GET
/api/2/eurowallet/payments/swift-currencies- returns a list of supported currencies to make a SWIFT transfer
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
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 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
swift object
required
Description:
Deposit details used when making SWIFT payments
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
SWIFT deposit detail structure:
beneficiaryName string
required
Description:
Beneficiary name used when making SWIFT payments
beneficiaryAddress string
required
Description:
Beneficiary address used when making SWIFT payments
bankName string
required
Description:
Bank name used when making SWIFT payments
bankAddress string
required
Description:
Bank address used when making SWIFT payments
bankSwiftCode string
required
Description:
Bank SWIFT code used when making SWIFT payments
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:
Your (Nexpay) bank account number from which the funds will be transferred
amount string
required
Description:
Payment amount
By default, the amount is assumed to be indicated in EUR.
networkType string
optional
Description:
Payment network through which the payment will be made
By default, network type is assumed to be SEPA.
For SWIFT payments, networkType should be specified.
currency string
optional
Description:
Payment currency
By default, the amount is assumed to be indicated in EUR.
For SEPA and SWIFT EUR payments, the currency can be skipped.
For SWIFT non-EUR payments, the currency must be specified.
beneficiaryName string
required
Description:
Name of the payment recipient
beneficiaryAddress string
optional
Description:
Address of the recipient
The field is optional and is applicable only for SEPA payments.
For SWIFT payments the address is mandatory and should be provided in beneficiaryAddressStreet, beneficiaryAddressTown, beneficiaryAddressCountry fields.
beneficiaryAccount string
required
Description:
Recipient’s bank account number
For the testing environment, you can indicate a randomly generated account number. Such payments 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:
Purpose of payment
beneficiaryBankBic string
conditional - required if networkType is SWIFT
Description:
Recipient bank identifier
Should be provided only if networkType = SWIFT
beneficiaryBankName string
conditional - required if networkType is SWIFT
Description:
Recipient bank name
The field is optional and is applicable only for SWIFT payments.
beneficiaryAddressStreet string
conditional - required if networkType is SWIFT
Description:
Recipient street address
Should be provided only if networkType = SWIFT
beneficiaryAddressTown string
conditional - required if networkType is SWIFT
Description:
Recipient city
Should be provided only if networkType = SWIFT
beneficiaryAddressCountry string
conditional - required if networkType is SWIFT
Description:
Recipient country
Should be provided only if networkType = SWIFT
useGbxForFee boolean
optional
Description:
Should be provided if you want to cover the payment fee with GBX token
externalPaymentId string
optional
Description:
Alternative payment identifier
This is an optional field to include your own identifier. This can be a custom ID recognized by both you and your end-customer, facilitating internal tracking and reference.
transactionSignature string
required
Description:
Transaction signature
Lower-case hmac-sha512 hex representation of concatenated request parameters (name=value) delimited by the “&” symbol.
Concatenation parameters should be placed in a strict order.
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 |
|---|---|
| 200 | Mandatory parameter missing |
| 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 |
| 20050 | Invalid payment network type |
| 20060 | Beneficiary bank BIC too long |
| 20061 | Beneficiary bank BIC too short |
| 20080 | Beneficiary bank name too long |
| 20090 | Beneficiary address street too short |
| 20091 | Beneficiary address street too long |
| 20100 | Beneficiary address town too short |
| 20101 | Beneficiary address town too long |
| 20111 | Beneficiary address country invalid |
Request accepted
Payment request is created and the payment itself will be processed shortly
Request denied
Payment request is denied.
In such case please refer to the error code, fix the issue and then make the request again.
Recovery check
It is unclear whether the payment request has actually been created.
For this reason, you must do the recovery check using externalPaymentld as a payment request identifier:
First, check payment status.
If payment exists and has pending status, wait for its processing.
If payment creation failed, try to create the payment again using 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
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 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 |
|---|---|
| 20000 | paymentId or externalPaymentId parameters was not provided |
| 20010 | Both paymentId and externalPaymentId parameters was provided |
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 in ISO 8601 format of yyyy-MM-dd, e.g. "2000-10-31"
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
- 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 |
|---|---|
| 20000 | paymentId or externalPaymentId parameters were not provided |
| 20010 | Both paymentId and externalPaymentId parameters were provided |
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 in ISO 8601 format of yyyy-MM-dd, e.g. "2000-10-31"
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 currencr rate
Request:
GET /api/2/eurowallet/payments/fx-rate
Returns a rate for a provided currency
Parameters:
currency string
required
Description:
Currency for which a rate from EUR will be returned.
The following fields are returned:
fxRate string
required
Description:
FX rate for a pair of EUR to provided currency.
Get list of currencies
Request:
GET /api/2/eurowallet/payments/swift-currencies
Returns a list of supported currencies to make a SWIFT transfer
The following fields are returned:
swiftCurrencies array of string
required
Description:
List of supported currencies for SWIFT payments.
API webhook
Description
Nexpay webhooks allow you to subscribe to events that happen within your Nexpay account and receive HTTP notifications to an endpoint you configure. Webhooks are available in both the sandbox account and real account.
To start using webhooks:
- You must deploy an HTTPS endpoint capable of handling webhook notifications, according to the specification below
- Contact [email protected] to configure webhook subscriptions and credentials for you account
Specification
Each webhook notification will be sent in the following format:
Method: POST
Headers:
- Content-Type: application/json
- X-Signature: <signature>
Body:
{
"event": "<event_name>",
"payload": {
...
}
}
The "X-Signature" header contains a signature the receiver must verify to ensure that the notification has been sent by Nexpay and has not been tampered with. The signature is generated from the request body using the ECDSA-SHA512 algorithm and the NIST P-256 curve. It will be sent as a hexdecimal string in the ASN.1 DER encoding.
You will receive the PEM encoded EC public key used for signature verification after successfully contacting Nexpay and registering your webhook subscription.
Below is an example of the request body, signature and public key that can be used to test signature verification:
{"payload":{"paymentId":27,"feePaymentId":null,"externalPaymentId":null,"batchReference":null,"account":"LT953080020000000650","amount":"5.01","direction":"incoming","status":"COMPLETED","date":"2024-06-06","networkType":"SEPA","otherName":"Roach Combs LLC","otherAccount":"LT093080020000000646","details":"Test payment 501","originalAmount":null,"originalCurrency":null,"runningBalance":"18.08"},"event":"payment.status"}
3045022026cfb1ace150acf7547db537e74772950bc03a96e14d50ae085a6853cc52b033022100ed30a1a50874622b0e74fe4874ed1b72d995d647ea3be135019a8ce2a8fcbe22
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY3GPZkskfkKHCCysnSQEqgcQxs+W
oV3EubNu6uIb35QaIgFjatt+9go1ulcWRO9jdrDbKHzf+Jmb35q6yvimLA==
-----END PUBLIC KEY-----
Events
Payments
payment.status- status change event for an outgoing or incoming SEPA/SWIFT payment
Payment status
Status change events for an outgoing or incoming SEPA/SWIFT payment.
The following fields are returned in the payload:
paymentId string
required
Description:
Internal payment identifier
account string
required
Description:
The account receiving or sending funds
amount string
required
Description:
Transaction amount
direction boolean
required
Description:
Payment direction (values: incoming or outgoing)
status boolean
required
Description:
Payment status (values: COMPLETED or REJECTED)
networkType string
required
Description:
Payment network, one of SEPA or SWIFT
otherName string
required
Description:
Name of the other counterparty receiving or sending funds
otherAccount string
required
Description:
Account of the other counterparty receiving or sending funds
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)
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
date string in ISO 8601 format of yyyy-MM-dd, e.g. "2000-10-31"
optional
Description:
Transaction date
details string
optional
Description:
Transaction details
runningBalance string
optional
Description:
Account balance at the time of the transaction