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 - POST
/api/1/eurowallet/account/commission
- sets account that will be used for all commissions charge - 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
Generates a new International Bank Account Number (IBAN)
Parameters:
accountType string
required
- OPERATIONAL
- CLIENT_FUNDS
- SETTLEMENT
tagName string
optional
Description:
Title for an International Bank Account Number (IBAN)
The following fields are returned:
iban string
required
Description:
International Bank Account Number (IBAN)
status string
required
Description:
International Bank Account Number (IBAN) status
balance string
required
Description:
International Bank Account Number (IBAN) balance
tagName string
required
Description:
International Bank Account Number (IBAN) title
accountType string
required
Description:
Type of a created account
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.
Set commission IBAN
Request:
POST /api/1/eurowallet/account/commission
Set an IBAN for the commissions' charge.
Parameters:
iban string
required
Description:
The IBAN that will be used for all commission charges
The following fields are returned:
iban string
required
Description:
International Bank Account Number (IBAN)
status string
required
Description:
International Bank Account Number (IBAN) status
balance string
required
Description:
International Bank Account Number (IBAN) balance
tagName string
required
Description:
International Bank Account Number (IBAN) title
accountType string
required
Description:
Type of a created account
Get account information
Request:
GET /api/1/eurowallet/status
Returns details of either all accounts or the default account
Parameters:
allAccounts Boolean
optional
Description:
This parameter needs to be submitted in the request if you want to get information about all accounts
The following fields are returned:
accounts array of objects
required
Description:
Array of accounts
Account entry structure:
iban string
required
Description:
International Bank Account Number (IBAN)
status string
required
Description:
International Bank Account Number (IBAN) status
balance string
required
Description:
International Bank Account Number (IBAN) balance
tagName string
required
Description:
International Bank Account Number (IBAN) title
swiftAccount string
optional
Description:
Number of a virtual bank account
Get banking details
Request:
GET /api/1/eurowallet/deposit-details
Returns banking details for receiving SEPA/SWIFT deposits
Parameters: no parameters
The following fields are returned:
clientName string
required
Description:
Your name as registered in our system
bankName string
required
Description:
Nexpay name
bankAddress string
required
Description:
Nexpay address
bicCode string
required
Description:
Nexpay BIC code
swift object
required
Description:
Deposit details for receiving SWIFT payments
accounts array of string
required
Description:
List of all active dedicated IBANs
swiftAccounts array of string
required
Description:
List of all active virtual IBANs
SWIFT deposit detail structure:
beneficiaryName string
required
Description:
Recipient’s name
Sender must indicate Nexpay name as recipient
beneficiaryAddress string
required
Description:
Recipient’s address
Sender must indicate Nexpay address as recipient
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.
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
optional
Description:
Recipient bank name
This field is applicable only for SWIFT payments.
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.
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 if networkType = SWIFT
The field is optional and applicable also for SEPA payments.
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.
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 list of currencies
Request:
GET /api/2/eurowallet/payments/swift-currencies
Returns the list of currencies in which SWIFT payment can be made
The following fields are returned:
swiftCurrencies array of string
required
Description:
Array of available currencies
Get currency rate
Request:
GET /api/2/eurowallet/payments/fx-rate
Returns FX rate for selected currency against euro
Parameters:
currency string
required
Description:
Base currency for rate calculation
The following fields are returned:
fxRate string
required
Description:
FX rate
Get commission amount
Request:
GET /api/1/eurowallet/payments/commission
Calculates commission
Parameters:
beneficiaryBankAccount string
required
Description:
Beneficiary bank account number
amount string
required
Description:
Payment amount
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.
The following fields are returned:
commissionAmount string
required
Description:
Commission amount
Get payment status
Request:
GET /api/1/eurowallet/payments/status
Returns information about specific payment status
Parameters:
clientPaymentId integer
required
Description:
Payment identifier generated by Nexpay system
Info
clientPaymentId is identical to paymentId returned in POST /api/2/eurowallet/payments response
This parameter does not need to be provided if externalPaymentId is passed in the request
externalPaymentId integer
required
Description:
Alternative payment identifier
The following fields are returned:
paymentId integer
required
Description:
Payment identifier generated by Nexpay system
paymentId is identical to clientPaymentId
status string
required
Description:
Payment status
- 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 information about specific payment
Parameters:
clientPaymentId integer
required
Description:
Payment identifier generated by Nexpay system
Info
clientPaymentId is identical to paymentId returned in POST /api/2/eurowallet/payments response
This parameter does not need to be provided if externalPaymentId is passed in the request
externalPaymentId integer
required
Description:
Alternative payment identifier
This parameter does not need to be provided if clientPaymentId is passed in the request
The following fields are returned:
networkType string
required
Description:
Payment network through which the payment was made
- SEPA
- SWIFT
date string
required
Description:
Payment processing date
beneficiaryName string
required
Description:
Recipient/sender’s name
account string
required
Description:
Recipient/sender’s bank account number
details string
required
Description:
Purpose of payment
amount string
required
Description:
Payment amount
originalAmount string
conditional - if networkType is SWIFT
Description:
Original payment amount
originalCurrency string
conditional - if networkType is SWIFT
Description:
Original payment currency
runningBalance string
required
Description:
Your account balance after making/recieving the payment
direction boolean
required
Description:
Payment direction
- INCOMING
- OUTGOING
status string
required
Description:
Payment status
- PENDING
- COMPLETED
- REJECTED
paymentId string
required
Description:
Payment identifier generated by Nexpay system
paymentId is identical to clientPaymentId
feePaymentId string
optional
Description:
Reference to the commission charge that is linked to this payment
externalPaymentId string
optional
Description:
Alternative payment identifier
batchReference string
optional
Description:
Reference to the batch file of which this payment is a part
otherAddressLine string
required
Description:
Recipient/sender’s house/apartment number
otherAddressStreet string
required
Description:
Recipient/sender’s street address
otherAddressTown string
required
Description:
Recipient/sender’s city
otherAddressPostCode string
required
Description:
Recipient/sender’s postal code
otherAddressCountry string
required
Description:
Recipient/sender’s country
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 payments history for a specified account
Parameters:
fromDate string
optional
Description:
Date from which to show account statement
toDate string
optional
Description:
Date until which to show account statement
account string
optional
Description:
Account number (IBAN) for which to generate a statement
The following fields are returned:
debitTurnover string
required
Description:
Debit turnover
creditTurnover string
required
Description:
Credit turnover
balanceStart string
required
Description:
Balance at the beginning of the selected period
balanceEnd string
required
Description:
Balance at the end of the selected period
clientName string
required
Description:
Your name as registered in our system
account string
required
Description:
Account number (IBAN) for which the statement is generated
entries array of objects
required
Description:
Array of payments
Payment entry structure:
networkType string
required
Description:
Payment network through which the payment was made
- SEPA
- SWIFT
date string
required
Description:
Payment date
beneficiaryName string
required
Description:
Recipient/sender’s name
account string
required
Description:
Payment account number (IBAN)
details string
required
Description:
Payment description
amount string
required
Description:
Payment amount
originalAmount string
conditional - if networkType is SWIFT
Description:
Original payment amount
originalCurrency string
conditional - if networkType is SWIFT
Description:
Original payment currency
runningBalance string
required
Description:
Your account balance after making/recieving the payment
direction string
required
Description:
Payment direction
- INCOMING
- OUTGOING
paymentId string
required
Description:
Payment identifier generated by Nexpay system
paymentId is identical to clientPaymentId
externalPaymentId string
optional
Description:
Alternative payment identifier
feePaymentId string
optional
Description:
Reference to the commission charge that is linked to this payment
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