[POST] Create Payment

POST /v1/payment

The request is intended to create a payment object. When you execute the request, the Payment object is created. It has the not paid status. Further actions with the payment object depend on what scenario is put to use.

Usage scenarios:

NOTE: The lifetime of the payment object having the not paid status is 90 days. After that, the status changes to deleted automatically.

content-type
string
required
MIME-type
It must be equal to "application/json".
AuthorizationJWT
required
Authorization token
  • Format: Bearer [token]
  • Where [token] is substituted by the token, value obtained through the authentication API
currency
string
required
Payment currency
  • Format: ISO 4217 alpha-3. 3 characters
  • For the value options, see the reference guide
amount
string
required
Payment amount
  • Format: Numeral, up to 2 decimal places, separator - dot.
  • The payment amount must be strictly greater than zero.
return_success_url
string
required
URL on your end
The customer is redirected automatically to it after successful online payment made via the payment form provided by the Noventiq Payments API. Automatic redirection to this URL also occurs when accessing the payment form page of the Noventiq Payments API, if the payment has the "Paid" status. For the rest of the scenarios, the value is not used.

Maximum is 255 characters.
payment_method
string
required
Payment method code
  • The list of payment methods available depends on the payment currency, see the reference guide
  • If the next action executed with a payment is one-time card payment, then the payment method code must be equal to CreditCard
recurring_indicator
boolean
It is used to register parent orders to process subsequent auto-payments. For more details, see the description of auto-payment scenarios.
Value options:
  • true - a payment is a parent one to process automatic payment,
  • false - a payment is not a parent one.
It is false by default.
payment_id
string
required
Payment ID on your end
Can be displayed to the customer during payment. See the description of parameter payment_description for more details.
  • It is an information value. The identifier is not being verified for uniqueness.
  • If requests containing the same ID are made repeatedly, new payment objects are created
  • Allowed: Numerical digits, latin letters, and characters "-" and "_" are supported
payment_description
string
Payment description
Depending on the payment method, it can be displayed to the customer in the payment form, on the payment error pages. Displayed not for all payment methods.
  • Maximum is 255 characters
  • If not transferred, it will be generated to the template: "Payment [payment_id]"
locale
string
Payment form interface language
Example: en_EN.
  • For the value options, see the reference guide
  • The list of supported language codes is decided on and provided upon connection. You have to contact support team if you need to customize the list
If the field is not transferred, then the payment form is displayed in the default language (selected upon connection).
The language code received in the request is saved in the payment object if the transferred language code is correct. If the language code is correct but is not supported by the payment form, then it will be saved in the payment object, however, the payment form will open in the default language.
customer
object
required
Customer data
The customer's personal data is used to process payments and depends on the payment method selected. E.g., filling in some data on the customer's company may be required.

You can transfer fake data in these parameters, but such a payment may be rejected by the acquirer due to suspicion of fraud.
customer
/
email
string
required
Customer's email

Maximum is 80 characters.
customer
/
first_name
string
required
Customer's first name

Maximum is 255 characters.
customer
/
last_name
string
required
Customer's last name

Maximum is 255 characters.
customer
/
phone
string
required*
Customer's phone number
  • * - Whether mandatory or not depends on what payment method is selected, see the reference guide for more details
  • Maximum is 64 characters
customer
/
vat_number
string
required*
Taxpayer Personal Identification Number
E.g., it is used to transfer: company INN when payments are made in russian rubles, DNI/CUIL or CUIT when payments are made in Argentine pesos.
  • * - Whether mandatory or not depends on what payment method is selected, see the reference guide for more details
  • Maximum is 255 characters
  • Depending on the payment currency, there may be additional requirements for the value format, for more details see the reference guide
customer
/
company_name
string
required*
Company’s name
  • * - Whether mandatory or not depends on what payment method is selected, see the reference guide for more details
  • Maximum is 255 characters
customer
/
company_billing_address
string
required*
Company's registered office address
  • * - Whether mandatory or not depends on what payment method is selected, see the reference guide for more details
  • Maximum is 255 characters
customer
/
company_delivery_address
string
required*
Company’s physical address
  • * - Whether mandatory or not depends on what payment method is selected, see the reference guide for more details
  • Maximum is 255 characters
customer
/
kpp
string
required*
Company’s KPP code
It may be required when the legal person makes a payment in russian rubles.
  • * - Whether mandatory or not depends on what payment method is selected, see the reference guide for more details
  • Allowed: Digits. Lenght: 9 digits
additional_data
object
Additional parameters
The customer does not see this information in the payment form. The transferred values are stored in the payment information. More details on additional parameters. Please note that the time for storing additional parameters in payments is limited.
additional_data
/
referer7
string
Referer7 value

Maximum of 255 characters.
additional_data
/
referer8
string
Referer8 value

Maximum of 255 characters.
additional_data
/
referer9
string
Referer9 value

Maximum of 255 characters.
additional_data
/
referer10
string
Referer10 value

Maximum of 255 characters.
additional_data
/
referer11
string
Referer11 value

Maximum of 255 characters.
additional_data
/
referer12
string
Referer12 value

Maximum of 255 characters.
{
  "currency": "EUR",
  "amount": "112.50",
  "return_success_url": "https://shop.com/successful_payment",
  "payment_method": "CreditCard",
  "recurring_indicator": false,
  "payment_id": "TEST12025",
  "payment_description": "Test payment",
  "locale": "en_EN",
  "customer": {
    "email": "customer@gmail.com",
    "first_name": "Marcel",
    "last_name": "Laporte",
    "phone": "7999991111",
    "vat_number": "12345654321",
    "company_name": "My company",
    "company_billing_address": "Trocadéro, Avenue Anatole-France, 5",
    "company_delivery_address": "Trocadéro, Avenue Anatole-France, 5",
    "kpp": "123456789"
  },
  "additional_data": {
    "referer7": "test",
    "referer8": "testA",
    "referer9": "testB",
    "referer10": "testC",
    "referer11": "testD",
    "referer12": "testF"
  }
}
{
  "currency": "EUR",
  "amount": "112.50",
  "return_success_url": "https://shop.com/successful_payment",
  "payment_method": "CreditCard",
  "payment_id": "TEST12025",
  "customer": {
    "email": "customer@gmail.com",
    "first_name": "Marcel",
    "last_name": "Laporte"
  }
}

In response to the request, you receive the server response code corresponding to the processing result. Depending on the code, the response body may contain additional parameters.

If processing is successful, the following will return in response server response code: HTTP/1.1 200 OК and json with the payment data.

NOTE: The payment object having the not paid status is created in the Noventiq Payments. The lifetime of an unfulfilled payment is 90 days.

payment_url
string
required
Payment form link
. It includes an additional GET parameter:
  • lang - payment form interface language code, e.g, en_EN, es_MX. If the transferred request contains a correct language code in the locale field, then the language code is saved in the payment object and returns in this parameter.
NOTE: The payment form can open in the default language if the language represented by the code that is saved in the payment object is not enabled. You have to contact support team to resolve the issue.

The link is valid within the payment object lifetime (90 days) or until the payment is fulfilled. If the payment is fulfilled - no second payment fulfillment is possible.

When working in the test environment, payment form links intended for the test environment will return in response (such links will have the .demoslweb.com suffix added).
order_id
number
required
Unique payment identifier in Noventiq Payments.
{
  "payment_url": "https://.../order/status/[order_id]/[hash]?lang=[local]",
  "order_id": 123456
}

If an error occurs while processing the request, you receive a server response code corresponding to the result of processing. 
Depending on the code, the response body may contain additional parameters.

HTTP code Description
HTTP/1.1 400 Bad Request The request is not valid (error in parameters; necessary data is not transferred, etc.).
An additional error code (one or more) will be transferred in the response body.
HTTP/1.1 401 Unauthorized Unsuccessful authorization.
An additional error code (one or more) will be transferred in the response body.
HTTP/1.1 404 Not found Invalid request URL or payment not found.
HTTP/1.1 500 Request Error Internal Server Error. Please try again later or contact support.
Error Message Description
If at least one error from the list below is found, then it returns in response to a request, other errors are not validated.
110 JSON is not valid. The payment cannot be processed. Request field structure is not valid. Check the fields in the request body against the JSON format.
111 Invalid data format (Content-type). The payment cannot be processed. Invalid request header. Content-type must be equal to application/json.
6000 Unable to generate payment. Please contact technical support. The payment cannot be processed.
It also includes the case when the payment currency transferred (currency) is not available.
You have to contact technical support.
If at least one error from the list below is found, then the request checking is not interrupted. Several errors may return in response.
6010 Invalid field value: [parameter name] The request is not valid, e.g., the required parameter is not filled out, the parameter name is incorrect, the parameter value does not match with the data type provided, or the value format is incorrect. Moreover, the error will return if null is transferred in the parameter, and this value option is not set as valid in the parameter description.
6020 Locale not found. Payment could not be created. The payment cannot be processed. The payment form interface language (locale) is not found.
6030 Сreation of zero-amount payments is not available. Enable recurring_indicator = true or set the amount strictly greater than zero. The payment cannot be processed. The payment amount transferred (amount) does not meet the requirements. You can transfer zero-value amounts only for payments having "recurring_indicator":true.
6060 Email field is filled out incorrectly. Expected format: [name]@[domain].[zone] The payment cannot be processed. An invalid email address has been transferred (customer.email).
6080 This payment method is not available. Change payment method (payment_method). The payment cannot be processed. The payment method transferred (payment_method) is not supported. It also includes the case when payment via the payment method selected is available only for legal persons, and no name of the customer’s company is transferred in the request (customer.company_name). Change payment method.
6090 This payment method is not available for this payment amount. Change payment method (payment_method). The payment cannot be processed. The payment method (payment_method) is not supported with the payment amount transferred (amount). Change payment method.
6100 This payment method does not support recurring payments. Change payment method (payment_method). The payment cannot be processed. You transferred "recurring_indicator":true, but the payment method transferred (payment_method) is not supported auto-payments. Change payment method.

The errors are the same for all the APIs that use token authorization.

errors
array [objects]
required
Error list.
errors / [error object]
/
error
number
required
Error code.
errors / [error object]
/
message
string
Error description.
{
  "errors": [
    {
      "error": 63010,
      "message": "Invalid field value: currency." 
    },
    {
      "error": 6010,
      "message": "Invalid field value: amount." 
    }
  ]
}