3.30. /api/v4/update-recurring-payments

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 HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication.

API URLs

Integration

Production

https://sandbox.payneteasy.com/paynet/api/v4/update-recurring-payments/ENDPOINTID

https://gate.payneteasy.com/paynet/api/v4/update-recurring-payments/ENDPOINTID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Below is a description of each parameter that can be included in the CSV and added to payload parameter which will be used in the request.
Any changes to recurring payment profile made with Update command can be viewed only via UI.

CSV Parameter Name

Description

Value

client-orderid

Connecting Party order ID.
Necessity: Required
Type: String
Length: 128

recurring-payment-id

Recurring ID assigned to the order by QA.
Necessity: Required
Type: String
Length: 128

credit-card-number

Payer`s credit card number.
Necessity: Required
Type: Numeric
Length: 19

card-printed-name

Payer`s card printed name.
Necessity: Required
Type: String
Length: 128

expire-year

Payer`s card expire year.
Necessity: Required
Type: Numeric
Length: 4

expire-month

Payer`s card expire month.
Necessity: Required
Type: Numeric
Length: 2

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 amount-from and amount-to or amount-sequence are not used.
Necessity: Conditional
Type: Numeric
Length: 10

amount-from

If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used.
Necessity: Conditional
Type: Numeric
Length: 10

amount-to

If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used.
Necessity: Conditional
Type: Numeric
Length: 10

amount-sequence

If amount sequence is chosen, client will be charged amounts from this list. Example of setting up amount sequence: 10.5, 24.6, 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 amount-from and amount-to or amount are not used.
Necessity: Conditional
Type: Numeric
Length: 10

period

Possible values are: day, week and 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. Interval and period can only be specified or omitted together. Not supported for DST.
Necessity: Conditional
Type: String
Length: 32

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. Interval and period can only be specified or omitted together. Not supported for DST.
Necessity: Conditional
Type: Int
Length: -

country

Payer`s country.
Necessity: Optional
Type: String
Length: 2

city

Payer`s city.
Necessity: Optional
Type: String
Length: 128

address1

Payer`s address.
Necessity: Optional
Type: String
Length: 256

first-name

Payer`s first-name.
Necessity: Optional
Type: String
Length: 128

last-name

Payer`s last-name.
Necessity: Optional
Type: String
Length: 128

customer-ip

Payer`s IP address. Supported for SRC and DST type.
Necessity: Optional
Type: String
Length: 45

order_desc

Description of Recurring payment.
Necessity: Optional
Type: String
Length: 65K

zip-code

Payer`s zip-code.
Necessity: Optional
Type: String
Length: 10

birthday

Payer`s birthday date.
Necessity: Optional
Type: 8/Numeric, DD.MM.YYYY
Length: 8

email

Payer`s email.
Necessity: Optional
Type: String
Length: 128

ssn

Social security number field.
Necessity: Optional
Type: String
Length: 32

phone

Payer’s full international phone number, including country code. Not supported for DST.
Necessity: Optional
Type: String
Length: 128

state

Payer’s state. Please see 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

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, DD.MM.YYYY
Length: 8

finish-date

Date, when the Payer will be charged last time.
Necessity: Optional
Type: 8/Numeric, DD.MM.YYYY
Length: 8

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

purpose

Purpose of transaction.
Necessity: Optional
Type: String
Length: 128

notify_url

Notify url field. server_callback_url parameter can also be used. For more information please see Connecting Party Callbacks.
Necessity: Optional
Type: String
Length: 1024

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 Connecting Party callback parameters. Send either notify_url or server_callback_url, not both.
Necessity: Optional
Type: String
Length: 128

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 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 start-date and finish-date parameters. However, it can only be resumed via the UI by clicking on Resume.
To stop the automatic recurring schedule, use finish-date in the past in Request 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.

Response Parameters

Description

type

The type of response. Example: update-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. Multiple error codes may be received: 200, 403, and 500. For the 500 error code, an additional error ID will be returned.

status

See Список статусов for details

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:
"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:
base64 update-recurring-payments-example.csv
Step 3. Assign the base64 encoded value to payload parameter and send the request:
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.
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.
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