.. _api_v4_create-recurring-payment: /api/v4/create-recurring-payment ################################# .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^ | /api/v4/create-recurring-payment is a synchronous API command. If request is accepted with no errors, the Payment Gateway creates a recurring payment profile and assigns a new recurring-payment-id to it. The recurring transactions will be processed according to the created recurring payment profile using the payment data saved in this profile. | Create recurring payment is initiated through :code:`HTTPS POST` request by using :ref:`URLs` and the :ref:`parameters` specified below. Use :ref:`RSA-SHA256` for authentication. .. _api_v4_create-recurring-payment_request_url: API URLs ^^^^^^^^ .. note:: | The path in API URL should not be hardcoded, as it may be changed in future. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Integration - Production * - :ex:`https://sandbox.payneteasy.com/paynet/api/v4/create-recurring-payment/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v4/create-recurring-payment/ENDPOINTID` .. _api_v4_create-recurring-payment_request_parameters: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded and :ref:`Authorization headers`. .. note:: | If the recurrent has switched to Stopped, you can update its schedule using the :ex:`start-date` and :ex:`finish-date` parameters. However, it can only be resumed via the UI by clicking on :code:`Resume`. | Type :code:`native` on UI means that The recurring payment setup and the actual charges are in the same acquirer. | To create recurring payment profile with automatic recurring schedule, send :code:`interval` and :code:`period` parameters. To create recurring payment profile without automatic recurring schedule, do not send :code:`interval` and :code:`period` parameters. To stop the automatic recurring schedule, use :ref:`/api/v4/update-recurring-payment`. Available only for SRC. .. list-table:: :widths: 30, 50, 20 :header-rows: 1 :class: longtable * - Parameter Name - Description - Value * - :code:`rp_card_type` - SRC - Sender's source card. DST - Receiver's destination card. - | ``Necessity``: Required | ``Type``: Enum | ``Length``: 3 * - :code:`client-orderid` - Connecting Party order ID. Supported for SRC and DST type. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`credit-card-number` - Payer`s credit card number. Supported for SRC and DST type. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 19 * - :code:`cvv2` - Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number printed on the back of the card in the signature area. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 3-4 * - :code:`card-printed-name` - Payer`s card printed name. Required for SRC, optional for DST. - | ``Necessity``: Conditional | ``Type``: String | ``Length``: 128 * - :code:`expire-year` - Payer`s card expire year. Required for SRC, optional for DST. - | ``Necessity``: Conditional | ``Type``: Numeric | ``Length``: 4 * - :code:`expire-month` - Payer`s card expire month. Required for SRC, optional for DST. - | ``Necessity``: Conditional | ``Type``: Numeric | ``Length``: 2 * - :code:`amount` - Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if :code:`amount-from` and :code:`amount-to` or :code:`amount-sequence` are not used. - | ``Necessity``: Conditional | ``Type``: Numeric | ``Length``: 10 * - :code:`currency` - Currency type. Supported for SRC and DST type. - | ``Necessity``: Required | ``Type``: String | ``Length``: 3 * - :code:`country` - Payer`s country. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 2 * - :code:`city` - Payer`s city. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`zip-code` - Payer`s zip-code. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 10 * - :code:`address1` - Payer`s address. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 256 * - :code:`first-name` - Payer`s first-name. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`last-name` - Payer`s last-name. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`email` - Payer`s email. Not supported for DST. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`amount-from` - If the combination of :code:`amount-from` and :code:`amount-to` is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if :code:`amount` or :code:`amount-sequence` are not used. - | ``Necessity``: Conditional | ``Type``: Numeric | ``Length``: 10 * - :code:`amount-to` - If the combination of :code:`amount-from` and :code:`amount-to` is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if :code:`amount` or :code:`amount-sequence` are not used. - | ``Necessity``: Conditional | ``Type``: Numeric | ``Length``: 10 * - :code:`amount-sequence` - If amount sequence is chosen, client will be charged amounts from this list. Example of setting up amount sequence: :ex:`10.5`, :ex:`24.6`, :ex:`32.0`. If repeats number is higher than amount sequence number of elements, every new charge will be with last amount in amount sequence. In order for charges to begin from the first amount in the chain, current repeats number must be set as 0. Supported for SRC and DST type. Required if :code:`amount-from` and :code:`amount-to` or :code:`amount` are not used. - | ``Necessity``: Conditional | ``Type``: Numeric | ``Length``: 10 * - :code:`period` - Possible values are: :ex:`day`, :ex:`week` and :ex:`month`. In case if daily is chosen, client will be charged every day. If week - every 7 days. If monthly is chosen, client will be charged on the same date of the month, from the starting date, no matter how many days there are in a month. :code:`Interval` and :code:`period` can only be specified or omitted together. Not supported for DST. - | ``Necessity``: Conditional | ``Type``: String | ``Length``: 32 * - :code:`interval` - Interval is a multiplier applied to the period. For example, if interval of 2 and period ‘Daily’ is selected, client will be charged once every 2 days. :code:`Interval` and :code:`period` can only be specified or omitted together. Not supported for DST. - | ``Necessity``: Conditional | ``Type``: Int | ``Length``: - * - :code:`order_desc` - Description of Recurring payment. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 65K * - :code:`customer-ip` - Payer`s IP address. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 45 * - :code:`ssn` - Social security number field. Not supported for DST. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 32 * - :code:`birthday` - Payer`s birthday date. Not supported for DST. - | ``Necessity``: Optional | ``Type``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Length``: 8 * - :code:`phone` - Payer`s phone number. Not supported for DST. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`state` - Payer’s state. Please see :ref:`Mandatory State codes` for a list of valid state codes. Required for USA, Canada and Australia.Not supported for DST. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 2-3 * - :code:`start-date` - Date, when first charge is scheduled. If start date is set as a current date and type is set as auto, first charge will be made today. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Length``: 8 * - :code:`finish-date` - Date, when the Payer will be charged last time. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Length``: 8 * - :code:`max-repeats-number` - Index of recurring transaction, first charge will hold the index of 0. Current repeats number increases even if a charge was unsuccessful. When current repeats number reaches max repeats number, Recurring payment goes into stop status and client is charged no more. If a charge was made automatically, no additional charges will be made(unless done manually), even if a recurring payment is stopped and rescheduled again. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: Int | ``Length``: - * - :code:`purpose` - Purpose of transaction. Not supported for DST. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`notify_url` - Notify url field. :code:`server_callback_url` parameter can also be used. For more information please see :ref:`Connecting Party Callbacks`. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 * - :code:`server_callback_url` - Connecting Party URL which will receive callback request once the transaction reaches final status. Connecting Party may use Server Callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. See callback details in :ref:`Connecting Party callback parameters`. Send either :ex:`notify_url` or :ex:`server_callback_url`, not both. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 .. _api_v4_create-recurring-payment_response_parameters: Response Parameters ^^^^^^^^^^^^^^^^^^^ .. note:: | Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value. .. warning:: /api/v4/create-recurring-payment is a synchronous API command. The response will be returned after the recurring payment profile will be created on Payment Gateway side. .. list-table:: :widths: 35, 65 :header-rows: 1 :class: longtable * - Response Parameters - Description * - :code:`type` - The type of response. May be :ex:`create-recurring-payment-response`, :ex:`validation-error`, :ex:`error`. If type equals :ex:`validation-error` or :ex:`error`, :ex:`error-message` and :ex:`error-code` parameters contain error details. * - :code:`recurring-payment-id` - Recurring ID assigned to the order by Payneteasy. * - :code:`status` - If request is accepted, this parameter has :code:`approved` value. This is not a transaction status. * - :code:`serial-number` - Unique number assigned by Payneteasy server to particular request from the Connecting Party. * - :code:`error-message` - If status is :ex:`declined` or :ex:`error` this parameter contains the reason for decline or error details. * - :code:`error-code` - The error code in case of :ex:`declined` or :ex:`error` status. Request Example ^^^^^^^^^^^^^^^ .. code-block:: none POST /paynet/api/v4/create-recurring-payment/ HTTP/1.1 User-Agent: curl/8.4.0 Accept: */* Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="qdyD66xc8sDEQwo3r12VjJfJhAOXuj6O", oauth_signature="eZve%2FSvPCTBXtQM%2BEwTEROtsQE27gZJr36EThL8ECCrnWH9Xw8JxcysNEPTG5HfcYwR2IOjDk3uiSNFa1oT2bQT9XONQTl1JVTOhIiMrMJT7GT1rGuLSsEvghaBoRLrcth6SC0c%2F%2FINyOxmIc%2B79E3T8hkpH6J6VI%2BSRG162%2BlHBPc1u1SGGnhkkRYU621AUGu2FDrc4neob4QJSm%2BaF3a0AgWDGiLbeQ0Ivn3YJ441EKd99kBWdaCuUp0eSfcmh3U2Js66edCjWXDEW7uuywP%2BU%2FBEeq06XxoVNGE2NF2LArXgoNqfzz2Tpisq35%2FE7Yg%2F9hphww75HMoJCECe0yVIHmKXd8HBDNMyT7gg3w5bnKbo%2FURX0m%2Fpe7bxkJ1mLNsKouHVkvjLZKpWVVUyCl%2BJ3x0BoEN5QK7xh0fNbV4Ue9TUOz59q0v%2B7lz5E1B4TvxQ9pa%2FmNCl4P2JgTosLvXNcdGn9Dq0TC0gb62O2W81MoZAljJQew%2FcKAUFTXBMZK6eIXzA81BPQVejv8nIVsvHKNo2Ko0s3hJPKGaeVAN0gyUAPw0%2BsJI3bnN2CPSW92xysGRWJYBtsHhqDhmgtoDNvw7LFB6BzRk5GPa9iQju34l47GsCUUIs3%2ByipIl7Q3HnM%2Bet9L8JSl7K02MwR6zlLxtd9UXHDq3pnmKzly6I%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721312072", oauth_version="1.0" Content-Length: 595 Content-Type: application/x-www-form-urlencoded Connection: keep-alive address1=1234%20Peace%20street &amount=55 &birthday=1980-01-02 &card-printed-name=JOHN%20SMITH &city=Chicago &client-orderid=1575634981130 &country=US &credit-card-number=4464920026265488 ¤cy=USD &customer-ip=1.2.3.4 &cvv2=123 &email=john.smith%40example.com &expire-month=12 &expire-year=2040 &finish-date=2040-01-01 &first-name=John &interval=1 &last-name=Smith &max-repeats-number=1000 ¬ify-url=http%3A%2F%2Fexample.com%2Fnotify-me &order_desc=testing%20purposes &period=week &phone=12345678 &purpose=No%20purpose%20at%20all &rp_card_type=SRC &ssn=1234 &start-date=2030-01-01 &state=IL &zip-code=123456 &server_callback_url=https://httpstat.us/200 Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 Server: server Date: Thu, 18 Jul 2024 14:16:20 GMT Content-Type: text/html;charset=utf-8 Connection: keep-alive Keep-Alive: timeout=60 Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 137 type=create-recurring-payment-response &serial-number=00000000-0000-0000-0000-000002f36d81 &recurring-payment-id=1492124 &status=approved Fail Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 500 Server: server Date: Thu, 18 Jul 2024 14:24:28 GMT Content-Length: 61 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Internal server error [8485772c-21d6-42aa-b2eb-3b5ae4e07d19] Request Builder ^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/V4RecurCreate.html