[POST] Auto-payment processing

Request Description

CODE

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:

Auto-payments with payment being processed first

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

Endpoints URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/payment/recurring
- Test environment: https://api.ecommerce.noventiq.com.demonqweb.com/v1/payment/recurring
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

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.

Format: ISO 4217 alpha-3. 3 characters.
It must be identical to the parent 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

CODE

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

CODE

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

CODE

{
  "errors": [{
      "error": 6210,
      "message": "Recurring payment processing is not available. Parent payment was made using different currency ARS."
    }
  ]
}

Noventiq Payments

Support

merchants.help@noventiq.com