.. _api_v4_update-recurring-payments: /api/v4/update-recurring-payments ############################################ .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^^^^^^^^^^^^^ | If request is accepted with no errors, the Payment Gateway finds the recurring payment profile for each provided recurring-payment-id and updates these profiles. The recurring transactions will be processed according to the updated recurring payment profiles using the payment data saved in each profile. | Update recurring payment Multiple 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_update-recurring-payments_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/update-recurring-payments/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v4/update-recurring-payments/ENDPOINTID` .. _api_v4_update-recurring-payments_request_parameters: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded and :ref:`Authorization headers`. | Below is a description of each parameter that can be included in the CSV and added to :code:`payload` parameter which will be used in the request. | Any changes to recurring payment profile made with :code:`Update` command can be viewed only via UI. .. note:: | The RPI details screen (recurring payment profile) contains information about linked cardholder and customer data, recurring schedule and processed transactions with this RPI. This screen also contains change history for this RPI. The change history is currently available for source cards (SRC) only. | Type :code:`native` on UI means that The recurring payment setup and the actual charges are in the same acquirer. | 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`. | To stop the automatic recurring schedule, use :ex:`finish-date` in the past in :ref:`Request Parameters`. .. list-table:: :widths: 30, 50, 20 :header-rows: 1 :class: longtable * - CSV Parameter Name - Description - Value * - :code:`client-orderid` - Connecting Party order ID. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`recurring-payment-id` - Recurring ID assigned to the order by QA. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`credit-card-number` - Payer`s credit card number. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 19 * - :code:`card-printed-name` - Payer`s card printed name. - | ``Necessity``: Required | ``Type``: String | ``Length``: 128 * - :code:`expire-year` - Payer`s card expire year. - | ``Necessity``: Required | ``Type``: Numeric | ``Length``: 4 * - :code:`expire-month` - Payer`s card expire month. - | ``Necessity``: Required | ``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:`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:`country` - Payer`s country. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 2 * - :code:`city` - Payer`s city. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`address1` - Payer`s address. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 256 * - :code:`first-name` - Payer`s first-name. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`last-name` - Payer`s last-name. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`customer-ip` - Payer`s IP address. Supported for SRC and DST type. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 45 * - :code:`order_desc` - Description of Recurring payment. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 65K * - :code:`zip-code` - Payer`s zip-code. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 10 * - :code:`birthday` - Payer`s birthday date. - | ``Necessity``: Optional | ``Type``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Length``: 8 * - :code:`email` - Payer`s email. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`ssn` - Social security number field. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 32 * - :code:`phone` - Payer’s full international phone number, including country code. 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. - | ``Necessity``: Optional | ``Type``: 8/Numeric, :ex:`DD.MM.YYYY` | ``Length``: 8 * - :code:`finish-date` - Date, when the Payer will be charged last time. - | ``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. - | ``Necessity``: Optional | ``Type``: Int | ``Length``: - * - :code:`purpose` - Purpose of transaction. - | ``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`. - | ``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_update-recurring-payments_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. .. list-table:: :widths: 35, 65 :header-rows: 1 :class: longtable * - Response Parameters - Description * - :code:`type` - The type of response. Example: :ex:`update-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. Multiple error codes may be received: :ex:`200`, :ex:`403`, and :ex:`500`. For the :ex:`500` error code, an additional error ID will be returned. * - :code:`status` - See :ref:`status_list` for details * - :code:`serial-number` - Unique number assigned by Payneteasy server to particular request from the Merchant Request Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | **Step 1.** Create a CSV with the provided structure: .. code-block:: none "client-orderid";"recurring-payment-id";"payment-description";"first-name";"last-name";"address1";"city";"zip-code"; "country";"state";"phone";"email";"customer-ip";"period";"interval";"start-date";"finish-date";"max-repeats-number";"amount"; "amount-from";"amount-to";"amount-sequence";"currency";"card-printed-name";"credit-card-number";"expire-month";"expire-year" | **Step 2.** Encode CSV to base64 with the following command: .. code-block:: none base64 update-recurring-payments-example.csv | **Step 3**. Assign the :ex:`base64` encoded value to :code:`payload` parameter and send the request: .. code-block:: none POST /paynet/api/v4/update-recurring-payments/ HTTP/1.1 Host: sandbox.payneteasy.com User-Agent: curl/8.4.0 Accept: */* Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth_consumer_key="ErwinTestMerchant",oauth_signature_method="RSA-SHA256",oauth_timestamp="1727177782",oauth_nonce="Js4dwXkF8eI",oauth_version="1.0",oauth_signature="VwdA7BQ68v%2BmpB0N%2BUOxK%2BxYk355i1QzeUPGGGFwDEBn7Y8v1xpSolGQ45HehGmJHNjXHc7A1mP3x7V7r2pQju1LpDEvAb2MHNLSCHiCEjI95sCtrotE%2Fs5%2FmQmIJ8te%2FGFCR1uK%2BzMPG8bpHqn%2B5EIEsuLPq6TSOjD0N3RvnV%2BHdmjH5cxTcmtRrcY0u6VIpvkBUlqpKuTVJXLvbpxRexvgPMDow78QS3DLRQhi6G7Y%2FVshKpKC%2FSRThhe8L33tFckX6KaEbJ3XIMEmP7O%2F%2FQdLfWQBn4ldSp8K8lpkgZks4CZbAjDY%2BQpSfwdc1s8kJf17Ymk1R69aGBmjzJrw00tV4dzY4DE6XVqSTUR8X%2FCa0XMrtD46ichsFoRvFtIeyV%2FIud%2F%2FLSb8XDqk%2BaftSLazBokmT8Qe1FMf0UMgUYBLCl0B4O66Ys8kH4Z6guC2MXarwu%2BDlfuelrcAHevS68hewrMb%2FjppSJWAbQiBOABeW6s1Rb4dvbJnZribkKhEwrxmnT5drsTYvukC2UCoUblEOgVkFHdHk5E3OqT4wMxqXojlYr5Il7m1GkHVYELb964ukROLkohGoTjYEKj%2FUHirjybDWeynTCSaGe%2Bv3JtEbkydWXannkdtTvk0xkbT6LurBiNWy1FuSTmKod9ibqyNiEv6j%2Be14BBGXs3xc5A%3D" Content-Length: 888 Connection: keep-alive payload=cmVjdXJyaW5nLXBheW1lbnQtaWQ7dHlwZTtjbGllbnQtb3JkZXJpZDtwYXltZW50LWRlc2NyaXB0aW9uO2ZpcnN0LW5hbWU7bGFzdC1uYW1lO2FkZHJlc3MxO2NpdHk7emlwLWNvZGU7Y291bnRyeTtzdGF0ZTtwaG9uZTtlbWFpbDtjdXN0b21lci1pcDtwZXJpb2Q7aW50ZXJ2YWw7c3RhcnQtZGF0ZTtmaW5pc2gtZGF0ZTtjdXJyZW50LXJlcGVhdHMtbnVtYmVyO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTQ5MjI4NjttYW51YWw7MTIzNDU2Nzg5MDtPdXIgc3VwZXIgZ29vZHM7Sm9objtTbWl0aDsxMjM0IFBlYWNlIHN0cmVldDtDaGljYWdvOzEyMzQ1NjtVUztJTDsxMjM0NTY3ODtqb2huLnNtaXRoQGV4YW1wbGUuY29tOzEuMi4zLjQ7d2VlazsxOzAxLjAxLjIwMzA7MDEuMDEuMjA0MDswOzEwMDA7MTA7Ozs7VVNEO0pPSE4gU01JVEg7NDUzODA5NjQxNTA4NDc1NjsxMjsyMDIwOzEyMztObyBwdXJwb3NlIGF0IGFsbDtodHRwOi8vZXhhbXBsZS5jb20vbm90aWZ5LW1lOzEyMzQ7MDIuMDEuMTk4MA0K Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | The successful response has empty body and HTTP code 200. .. code-block:: none HTTP/1.1 200 Server: server Date: Tue, 24 Sep 2024 11:40:45 GMT Content-Length: 0 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Fail Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | The unsuccessful response has empty body and HTTP code 403. .. code-block:: none HTTP/1.1 403 Server: server Date: Wed, 25 Sep 2024 08:47:54 GMT Content-Length: 0 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Request Builder ^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/V4RecursUpdate.html