Knowledge Base
Noventiq Payments
Up
Knowledge Base
Noventiq PaymentsIntegrationPayments API
[POST] Auto-Payment Processing

[POST] Auto-Payment Processing

Request Description

POST /v1/payment/recurring

The request is intended to create recurring payment objects and initiate automatic payment executions for them. To execute processing of auto-payments, the data saved earlier is used.

After the request is executed, a Payment object is created. It has the not paid status. Next, auto-payment processing is initiated.

Usage scenario:

The conditions to start processing the request are the following:

  • The first action of the scenario has been executed:
    • The payment object created earlier is registered as a parent payment (field "recurring_indicator":true is transferred).
    • The parent payment is completed successfully (payment has been processed has been completed) and has processing status paid.

The payment result check is executed separately; see the description of the scenarios.

Connection Data

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

parent_order_id
number
required
Parent payment identifier in Noventiq Payments.
payment_id
string
required
Recurring payment identifier on you end.
  • It is an information field. The identifier is not 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.
currency
string
required
Recurring payment currency.
amount
number
required
Recurring payment amount.
  • Format: Numeral, up to 2 decimal places, separator - dot.
  • The payment amount must be strictly greater than zero.
payment_description
string
Payment description.
  • The payment description can be displayed to the customer for some of the payment methods when a payment is being made, see the reference guide.
  • Maximum is 255 characters.
  • If not transferred, it will be generated to the template: "Payment [payment_id]".

Request Example

{
    "parent_order_id": 1122344,
    "payment_id": "TEST12025-2",
    "currency": "EUR",
    "amount": "112.50",
    "payment_description": "Test payment" 
}

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 recurring payment identifier.

  • The payment object having the not paid status is created in the Noventiq Payments. The lifetime of an unfulfilled payment is 90 days.
  • Automatic payment execution has been initiated.

Body Parameters

order_id
number
required
Unique payment identifier in Noventiq Payments.

Example of Successful Response

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

An additional error code (one or more) will be transferred in the response body. 
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 auto-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 auto-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 auto-payment cannot be processed.
It also includes the case when the auto-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.
6210 Recurring payment processing is not available. Parent payment [parent_order_id] has not been completed successfully. The auto-payment cannot be processed. The parent payment having the identifier transferred (parent_order_id) has not been fulfilled.
6215 Recurring payment processing is not available. Parent payment [parent_order_id] has been deleted. The auto-payment cannot be processed. The parent payment having the identifier transferred (parent_order_id) has been deleted.
6220 Recurring payment processing is not available. Parent payment was made using different currency [ISO currensy code from parent payment]. The auto-payment cannot be processed. The auto-payment currency transferred (currency) is not identical to the parent payment currency.
6230 Recurring payment processing for payment method [Payment method code from parent payment] is not available. The auto-payment cannot be processed. The auto-payment option is not supported with this payment method.
6240 Recurring payment processing is not available. During payment [parent_order_id] processing, failed to save data for next payments. The auto-payment processing cannot be processed. No payment data has been saved during processing of the parent payment.
6250 Parameter recurring_indicator = true has not been set for payment [parent_order_id]. The auto-payment cannot be processed. Parameter recurring_indicator = true has not been set for payment having the identifier transferred (parent_order_id).
6260 Recurring payment processing is not available. This payment method is not available for this payment amount. The auto-payment cannot be processed. The payment method (payment_method) is not supported with the payment amount transferred (amount).
6265 Recurring payment processing is not available. This payment method is not available. Please contact technical support. The auto-payment cannot be processed. The payment method (payment_method) is not available. You have to contact technical support.

Additional Error Codes for HTTP HTTP 401

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

Additional Error Codes for HTTP HTTP 404

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.
6200 Order [parent_order_id] is not found. The parent payment having the identifier transferred (parent_order_id) is not found, or you have no rights to process auto-payments for this payment.

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": 6210,
      "message": "Recurring payment processing is not available. Parent payment was made using different currency ARS."
    }
  ]
}
Privacy Policy
© 2024 Noventiq