Recurrent Payments service

Recurring transactions is a type of bank payments, where charges are applied to a cardholder in predetermined intervals for services or goods of an ongoing nature (memberships, subscriptions, loan payments). Prior to the charges, card must be registered in system. Charges will be made according to balancing set on project level.

Recurring payments page overview

Once recurring payments are registered in the system, you can view full list of them in “Orders - Recurring payments”

../_images/generaloverview.png

Recurrence details

../_images/recurrencedetails.png

Recurrence details section presents general information about the transaction. Recurrence ID can be found here, which is used for updating recurring payments.

Customer details

Customer details section shows general information about client (city, e-mail, etc). Note, that this info can be changed for further recurrent charges.

../_images/customerdetails.png

Actions history

Actions history page shows history of changes in this recurrent payment (schedule changes, status changes, manual charges), data and status of these actions.

../_images/actionshistory.png

Recurring schedule

../_images/recurringschedule.png
Recurring Schedule Parameters Comment
Type Recurring payments can be set as auto and manual. If set as auto, charges will be applied automatically in accordance with this schedule. If set as manual, client can be charged only manually with the help of Recur transaction/API call
Period Period can be daily, weekly and monthly. In case if daily is chosen, client will be charged every day. If weekly - 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 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
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
Finish date Date, when the client will be charged last time
Max & current 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, recurrent 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
Currency Currency of recurring payments, must be the same as currency on the project assigned. Upon reaching finish date, recurrent payment will go into stop status
Exact amount If exact amount is chosen, every charge will be of that amount
Amount from/amount to If amount from+amount to is chosen, every charge will be of random amount between these two numbers
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

exclamation Native type is reserved for future use and is not yet functional.

Status & Actions panel

../_images/statusandactions.png

Current status can be “scheduled” or “stopped” and represents if this recurring transaction is turned on or off.

Processing status can hold the following values:

idle - recurring payment is currently not queued to be processed

queued - recurring payment is in queue to be processed.

dequeued - recurring payment is taken out of the processing queue to be executed.

processing - recurring payment is currently being processed

failed - transaction has not received a final status and needs to be finalized.

Next fire date is a date when client will be charged next time.

Change card data action allows you to change data of the card to be charged.

Recur transaction action is a manual charge of a client. It won`t increase repeats number counter. Manual charges made this way do not interact with automatic charges in any way.

Suspend action lets you stop future charges on current recurring transaction.

Batch operations

Creating and updating recurring payments

Recurrent payments are added and updated in the system in batches. In order to do it, navigate to “Tools - Batch operations”.

Note

To add or update recurring payments, download an example presented, fill in your clients, following an example, and upload it.

Warning

Microsoft Excel can display .csv files wrong, for better user experience a different office suite, for instance, LibreOffice. Only “amount” OR “amount from” + “amount to” OR “amount sequence” should be filled in.

../_images/recurrentsexample.png

Update of recurring payments is done on “Update recurring payments” page in the same way. Recurrent transactions will be updated based on “Recurring payment id” parameter.

API

The End point ID is an entry point for incoming Merchant’s transactions.

https://sandbox.payneteasy.com/paynet/api/v4/create-recurring-payments/ENDPOINTID – for create transaction
https://sandbox.payneteasy.com/paynet/api/v4/process-recurring-payments/ENDPOINTID – for process transaction
https://sandbox.payneteasy.com/paynet/api/v4/update-recurring-payments/ENDPOINTID – for update transaction

Recurrent payments create

Creation Request Parameters

Generate Public and Private key pair

You need only private and public key to authorize your transaction. To generate it please got to https://www.openssl.org/ download latest version of openssl and run following commands:

openssl genpkey -algorithm RSA -out test-private-2048.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in test-private-2048.pem -out test-public-2048.pem

Share your Private key with no one, you should be the only person to know it. Your Public key, on the contrary, should be sent to your manager, so he can register it in the system. Use different keys for production and for testing purposes to avoid its comprometation.

For using this demo you need private key in PKCS#8 container.

Debug form
URL
Merchant login
Endpoint
client-orderid
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
cvv2
purpose
notify-url
ssn
birthday

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

Recurrent payments update

Update Request Parameters

period 32/String Period can be 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 Optional
client-orderid 128/String Merchant order id Optional
recurring-payment-id long ID assigned by Payneteasy Mandatory
type auto/manual Recurring payments can be set as auto and manual. If set as auto, charges will be applied automatically in accordance with this schedule. If set as manual, client can be charged only manually with the help of Recur transaction/API call Mandatory
Merchant login 20/String Merchant’s login name Mandatory
Endpoint 40/Numeric Endpoint ID Mandatory
payment-description 65K/String Description of recurrent payment Optional
first-name 128/String Clients first name Optional
last-name 128/String Clients last name Optional
address1 256/String Clients address Optional
zip-code 10/String Clients zip-code Optional
country 2 exactly Clients country Optional
state [2;3] Clients state Optional
phone 128/String Clients phone number Optional
email 128/String Clients email Optional
interval int 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 Optional
start-date yyyy-MM-dd 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 Optional
finish-date yyyy-MM-dd Date, when the client will be charged last time Optional
max-repeats-number int 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, recurrent 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 Optional
amount 255/String Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, recurrent payment will go into stop status Optional
amount-from 255/String Clients IP address Optional
amount-to 255/String Clients IP address Optional
amount-sequence 255/String Clients IP address Optional
currency 3 Exactly Currency type Optional
card-printed-name 128/String Clients card printed name Optional
credit-card-number [13;19]/Digit Clients credit card number Optional
expire-month 2/Digit Clients card expire month Optional
expire-year 255/String Clients card expire year Optional
cvv2 [3;4]/Digit Clients cvv2 code Optional
purpose 128/String Purpose of transaction Optional
notify-url 1024/String Notify url field Optional
ssn 32/String Social security number field Optional
birthday yyyy-MM-dd Clients birthday date Optional
Generate Public and Private key pair

You need only private and public key to authorize your transaction. To generate it please got to https://www.openssl.org/ download latest version of openssl and run following commands:

openssl genpkey -algorithm RSA -out test-private-2048.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in test-private-2048.pem -out test-public-2048.pem

Share your Private key with no one, you should be the only person to know it. Your Public key, on the contrary, should be sent to your manager, so he can register it in the system. Use different keys for production and for testing purposes to avoid its comprometation.

For using this demo you need private key in PKCS#8 container.

Debug form
URL
Merchant login
Endpoint
recurring-payment-id
type
client-orderid
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
cvv2
purpose
notify-url
ssn
birthday

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

Recurrent payments process

Processing Request Parameters

Add Document request parameters Length/Type Comment Necessity
client-orderid 128/String Merchant order id Optional
recurring-payment-id long ID assigned by Payneteasy Mandatory
Merchant login 20/String Merchant’s login name Mandatory
Endpoint 40/String Endpoint ID Mandatory
payment-description 65K/String Description of recurrent payment Mandatory
first-name 128/String Clients first name Optional
last-name 128/String Clients last name Optional
address1 256/String Clients address Optional
zip-code 10/String Clients zip-code Optional
country 2 exactly Clients country Optional
state [2;3]/String Clients state Optional
phone 128/String Clients phone number Optional
email 128/String Clients email Optional
amount 255/String Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, recurrent payment will go into stop status Mandatory
currency 3 exactly Currency type Mandatory
purpose 128/String Purpose of transaction Optional
notify-url 1024/String Notify url field Optional
ssn 32/String Social security number field Optional
birthday yyyy-MM-dd Clients birthday date Optional

Process recurring payment debugger can be used to initiate a manual charge from a customer. Manual charges made this way do not interact with automatic charges in any way and they don`t increase any counters.

To reproduce your API call, input all of the data from your original request, including the authentication tokens. Don’t forget to set the nonce and timestamp to the values you used. An OAuth signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your OAuth signature code. Due to current PCI DSS restrictions only OAuth 1.0a RSA-SHA256 signature is allowed. Other signature methods are restricted. So to send command to the server your request should be: sent as POST, contains OAuth 1.0a headers, signed with RSA-SHA256.

Generate Public and Private key pair

You need only private and public key to authorize your transaction. To generate it please got to https://www.openssl.org/ download latest version of openssl and run following commands:

openssl genpkey -algorithm RSA -out test-private-2048.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in test-private-2048.pem -out test-public-2048.pem

Share your Private key with no one, you should be the only person to know it. Your Public key, on the contrary, should be sent to your manager, so he can register it in the system. Use different keys for production and for testing purposes to avoid its comprometation.

For using this demo you need private key in PKCS#8 container.

Debug form
URL
Merchant login
Endpoint
recurring-payment-id
client-orderid
payment-description
first-name
last-name
address1
city
zip-code
country
state
phone
email
customer-ip
amount
currency
purpose
notify-url
ssn
birthday

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.