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”
Recurrence details¶
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.
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.
Recurring schedule¶
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 |
Native type is reserved for future use and is not yet functional.
Status & Actions panel¶
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.
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.
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
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 |
---|
Base64 Encoded Signature |
---|
|
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 |
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
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 |
---|
Base64 Encoded Signature |
---|
|
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 |
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
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 |
---|
Base64 Encoded Signature |
---|
|
|