Main Endpoints

Create payment

This endpoint allows you to create an outgoing payment from your Nexpay account
POST/api/2/eurowallet/payments

This endpoint is a core functionality of the Nexpay API. Before you begin integrating this endpoint, please carefully review the instructions for managing the payment flow.

Request

Mandatory parameters

requestTime
integer required
Request time
Format: unix timestamp
Precision: milliseconds
account
string required
Your IBAN account at Nexpay, from which the funds will be transferred
amount
string required
Payment amount
Format: Decimal string with at most two fractions and value greater than 0.00
beneficiaryName
string required
Name of the payment recipient
beneficiaryAccount
string required
Recipient’s bank account number
beneficiaryReference
string required
Payment reference (transaction details)
transactionSignature
string required
Transaction signature (see detailed description here)

Conditional Parameters

If you make a payment via the SWIFT network (networkType = SWIFT), you will need to specify additionally:

beneficiaryBankBic
string required
Recipient’s bank BIC code
beneficiaryBankName
string optional
Recipient’s bank name
beneficiaryEntityType
string required
Recipient’s entity type.
Possible values: PRIVATE, CORPORATE

In case of PRIVATE, fields beneficiaryFirstName and beneficiaryLastName need to be provided.
In case of CORPORATE, field beneficiaryName needs to be provided.
beneficiaryFirstName
string optional
Recipient’s first name.
Required if beneficiaryEntityType is set to PRIVATE.
beneficiaryLastName
string optional
Recipient’s first name.
Required if beneficiaryEntityType is set to CORPORATE.
beneficiaryAddressStreet
string required
Recipient’s street address
beneficiaryAddressTown
string required
Recipient’s city address
beneficiaryAddressCountry
string required
Recipient’s country
beneficiaryAddressState
string optional
Recipient’s address state
Required based on rules described in section SWIFT payment field rules
beneficiaryAddressPostCode
string optional
Recipient’s address post code
Required based on rules described in section SWIFT payment field rules
purposeOfPayment
string optional
Payment description or purpose
Required based on rules described in section SWIFT payment field rules
currency
string optional
Payment currency (this parameter should be indicated for non-EUR payments sent through the SWIFT network)
The full list of supported currencies can be fetched here
Default: EUR

Optional parameters

The parameters listed below are optional:

networkType
string optional
Payment rails through which the payment should be made
Possible values: SEPA, SWIFT
If the parameter is not provided, the SEPA network is chosen by default
commissionAccount
string optional
Your IBAN account at Nexpay, from which the commission will be charged
The account should be marked as commission account in the client portal beforehand
beneficiaryAddress
string optional
Recipient’s full address
This parameter can be optionally provided when making payment through the SEPA network
externalPaymentId
string optional
The custom internal identifier shared between you and your end-customer (it is strongly recommended to always include this parameter into request)
Allowed characters: a-z, A-Z, &, -, %, whitespace and tab
Maximum variable size: 36
executionTime
string optional
The date and time when the payment should be scheduled to execute.
Format: yyyy-MM-ddThh:mm:ss (ISO 8601), UTC time zone, no longer than three months from the current date
scheduledRejectionTime
string optional
The date and time at which the payment should be automatically cancelled.
Format: yyyy-MM-ddThh:mm:ss (ISO 8601), UTC time zone
Please note that having a PENDING status does not guarantee that payment will rejected after the selected time. The payment can be considered as rejected only after receiving the REJECTED status either through the payment status endpoint or after receiving a webhook. In some cases, the payment amount might be returned to your account with a delay.

Response

paymentId
string required
The payment identifier generated by Nexpay (identical to clientPaymentId)
status
string required
Payment status
Possible values: PENDING, COMPLETED, REJECTED

Error codes

CodeMessage
200Mandatory parameter missing
20000Invalid request time
20010Beneficiary name too long
20020Beneficiary name too short
20030Reference information for beneficiary too long
20040Invalid transaction signature
20050Invalid payment network type
20060Beneficiary bank BIC too long
20061Beneficiary bank BIC too short
20080Beneficiary bank name too long
20090Beneficiary address street too short
20091Beneficiary address street too long
20100Beneficiary address town too short
20101Beneficiary address town too long
20111Beneficiary address country invalid
20120Invalid execution date time

SWIFT payment field rules

Due to specific requirements for different currencies and countries, some SWIFT payment fields are required only under certain conditions. This section describes all context specific field rules that are required for SWIFT payments.

Payments to Canada, The United States, and Mexico

Beneficiaries in Canada, The United States, and Mexico require the full address:

  • beneficiaryAddressStreet
  • beneficiaryAddressTown
  • beneficiaryAddressCountry
  • beneficiaryAddressState
  • beneficiaryAddressPostCode

Payments to The United Arab Emirates

The purposeOfPayment field is required, if the bank country is The United Arab Emirates.

Examples

POST url: /api/2/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=223102a35db34864b2057fa1fb1089000000&transactionSignature=c8888edc979b3ef4a54a6bb6c3fbc11e37df42ff1c9fe2fc2a12df70d68c9a22

Commentaries

Network type

Currently, you can make a payment via the following payment networks (rails): SEPA, SEPA Instant, and SWIFT.

When making a payment, you can specify through which payment network it should be sent - networkType parameter.

  • This parameter is optional
  • If the parameter is not provided, the payment will go through SEPA or SEPA Instant
  • If the networkType = SEPA, the payment will go through SEPA or SEPA Instant
  • The system automatically determines which channel to send the payment through: SEPA or SEPA Instant
  • If the SEPA Instant conditions are met, the payment will be sent through this channel by default. Otherwise, it will be sent through SEPA
  • SEPA Instant conditions include, but are not limited to: (a) whether this payment channel is available to your account, (b) whether the recipient bank is a member of this payment network, and (c) whether the payment amount complies with the Nexpay internal limit.
  • To send a payment via the SWIFT system, it is necessary to specify this parameter

Signature

Parameter order

When preparing the payment creation request, it is critically important to place parameters in the exact order as it is written below.

  1. requestTime
  2. account
  3. commissionAccount (optional)
  4. amount
  5. networkType (optional)
  6. beneficiaryName
  7. beneficiaryAddress (optional)
  8. beneficiaryAccount
  9. beneficiaryReference
  10. externalPaymentId (optional, recommended)
  11. executionTime (optional)
  12. scheduledRejectionTime (optional)
  13. transactionSignature (required)

SEPA pseudo-code example
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=223102a35db34864b2057fa1fb1089000000

Get accounts information

This endpoint allows you to get detailed information about each of your accounts (IBANs)

Get payment status

This endpoint allows you to retrieve payment status