[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:

• Payment via payment forms provided by Noventiq Payments

• Auto-payments with payment being processed first

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 / 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

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

Additional Error Codes for HTTP 400

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." 
    }
  ]
}

Noventiq Payments