[POST] Create Payment — Noventiq Payments

Noventiq PaymentsIntegrationPayments API

[POST] Create Payment

Request Description

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.

Connection Data

Endpoints URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/payment
- Test environment: https://api.ecommerce.noventiq.com.demonqweb.com/v1/payment
Request Method: POST
Format: JSON
Authorization: token-based

Header Parameters

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

Body Parameters

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

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

Customer's phone number

Maximum is 64 characters. There are no additional format requirements or restrictions.

customer

company_name

string

required*

Company’s name

* - This parameter must be transferred for companies
When being paid by an individual, the parameter is not transferred.
Maximum is 255 characters

customer

vat_number

string

required*

Taxpayer Personal Identification Number
E.g., it is used to transfer: DNI/CUIL or CUIT when payments are made in Argentine pesos.

* - When being paid by a company, parameter transferring requirements depend on the payment method selected; for more details, see the reference guide
When being paid by an individual, the parameter is not transferred
Maximum is 255 characters
Format: depending on the payment currency, see the reference guide for more details

customer

company_billing_address

string

required*

Company's registered office address

* - When being paid by a company, parameter transferring requirements depend on the payment method selected; for more details, see the reference guide
When being paid by an individual, the parameter is not transferred
Maximum is 255 characters

customer

company_delivery_address

string

Company’s physical address

* - When being paid by a company, parameter transferring requirements depend on the payment method selected; for more details, see the reference guide
When being paid by an individual, the parameter is not transferred
Maximum is 255 characters

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.

Request Example (complete set of parameters)

{
  "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"
  },
  "additional_data": {
    "referer7": "test",
    "referer8": "testA",
    "referer9": "testB",
    "referer10": "testC",
    "referer11": "testD",
    "referer12": "testF"
  }
}

Request Example (minimum set of parameters)

{
  "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"
  }
}

Response Description

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.

Successful Response

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.

Body Parameters

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.

Example of Successful Response

{
  "payment_url": "https://.../order/status/[order_id]/[hash]?lang=[local]",
  "order_id": 123456
}

Error Response

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 Server Response Error Code

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.

Additional Error Codes for HTTP 400

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.

Additional Error Codes for HTTP 401

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

Body Parameters

errors

array [objects]

required

Error list.

errors / [error object]

error

number

required

Error code.

errors / [error object]

message

string

Error description.

Example of Error Response

{
  "errors": [
    {
      "error": 63010,
      "message": "Invalid field value: currency." 
    },
    {
      "error": 6010,
      "message": "Invalid field value: amount." 
    }
  ]
}