Recurring Transaction

Implement recurring payments

The Recurring Transaction model is ideal for subscription business models as it allows you to retrieve funds without cardholders being present during the transaction.
The recurring transaction works based on tokenization. It means that you can store one or more payment details per customer. This allows you to offer subscription payments and give your shoppers a faster checkout experience by using their stored cards.

Benefits of tokenization

  • Let customer store their payment details for a faster checkout experience later.
  • Save payment details for a subscription or a non-fixed schedule contract.

To save your customer's payment details, you need to pass some additional parameters when making a payment. In the first payment, we collect the payment information from the shopper and generate a token for it. The token is then sent to your server for future use. For later payments, you need to make a request with the shopper reference and the token.

If you plan to use a recurring billing model, please notify our onboarding team, this functionality needs to be approved by our team.

🚧

PCI compliance

To collect raw card data, you need to be fully PCI DSS compliant. If you are fully PCI DSS compliant, you can either create your own token server or store raw card data to offer faster checkout options.

PSD2 regulations may have additional requirements for processing recurring transactions. Please check with our Risk department regarding it.


Step 1. Create a recurring transaction

To flag the type of recurring transaction, use the following parameter:

**recurring_id**: The recurring_id field is needed if you want to send recurring transactions. Therefore the first transaction needs to be classified with INIT. In that transaction the cvc_code is mandatory. The recurring transactions don't need to contain any payment details (ccn, exp_month, exp_year, cvc_code, cardholder_name) anymore, but need to send the initial transaction ID in the recurring_id field.

From your server, make a POST request /payment_authorize - for Direct Gateway or /init - for iFrame .

POST https://sandbox.payabl.com/pay/backoffice/payment_authorize

And include the following values:

  • merchantid: The merchant identification number.
  • orderid: The field orderid is optional and exclusively for the merchants convenience.
  • amount:The amount field contains the transaction’s total amount. This is the amount that will be transmitted to the authorizing system.
  • currency: The currency field contains the alphanumeric currency code for the transaction, according to ISO 4217, e.g. EUR, USD, AUD, CAD, NOK, SEK, CHF.
  • payment_method: Valid payment method ID.
  • signature: The signature field contains a 40-figure hexadecimal value. This signature value is a checksum designed to protect the merchant account from unauthorized access.
  • recurring_id : Classify the first of recurring transactions with INIT. Following recurring transactions need the transaction ID of the initial transaction
  • email: The customer's email address
  • customerip: The customer's IP (IPv4)
  • firstname
  • lastname
  • street
  • zip
  • city
  • state
  • country

Initial request example

merchantid=gateway_test&amount=1.23&currency=USD&orderid=PowerPay21Test&language=en&gender=M&
lastname=Mann&street=AnderWelle4&zip=60322&city=Frankfurt&country=DEU&customerid=&salutation=Herr&
title=&firstname=Muster&company=PowerPay21&birthday=07071971&house=19&postbox=&state=HE&
[email protected]&phone=XXXXXXXXXX8501&fax=&mobile=&customerip=127.0.0.1&payment_method=1&
ccn=XXXXXXXXXXXX4242&cvc_code=XXX&cardholder_name=GatewayTest&exp_month=12&
exp_year=2017&recurring_id=INIT&signature=SIGNATURE

The recurring ID is created after a successful payment authorization to ensure that the payment details the customer provided are linked to an active, chargeable account.

🚧

ApplePay, GooglePay

Please note that recurring is not supported for ApplePay and GooglePay. To make a subscription for these methods use Credentials on File (tokenization).

Step 2. Receive a response notification

If the payment was successful, you will get a response with the transaction id. You need to save this transaction id for future subscription payments.

Response for the Initial request

transactionid=80780000&transid=80780000&status=0&errormessage=&errmsg=&amount=1.23&price=1.23&
currency=USD&orderid=PowerPay21-Test&user_id=10088265

Step 3. Make a subscription payment

From your server, make a POST /payment_authorize request.

POST https://sandbox.payabl.com/pay/backoffice/payment_authorize

🚧

If you are using Hosted PP, follow-up transactions need to be sent to the authorization interface /payment_authorize link

And include the following values:

  • merchantid: The merchant identification number.
  • orderid: The field orderid is optional and exclusively for the merchants' convenience.
  • amount:The amount field contains the transaction’s total amount. This is the amount that will be transmitted to the authorizing system.
  • currency: The currency field contains the alphanumeric currency code for the transaction, according to ISO 4217, e.g. EUR, USD, AUD, CAD, NOK, SEK, CHF.
  • payment_method: Valid payment method ID.
  • email: The customer's email address
  • signature: The signature field contains a 40-figure hexadecimal value. This signature value is a checksum designed to protect the merchant account from unauthorized access.
  • recurring_id : Classify the first of recurring transactions with INIT. Following recurring transactions need the transaction ID of the initial transaction

Recurring request example

merchantid=gateway_test&amount=1.23&currency=USD&orderid=PowerPay21Test&language=en&gender=M&
lastname=Mann&street=AnderWelle4&zip=60322&city=Frankfurt&country=DEU&customerid=&salutation=Herr&
title=&firstname=Muster&company=PowerPay21&birthday=07071971&house=19&postbox=&state=HE&
[email protected]&phone=XXXXXXXXXX8501&fax=&mobile=&customerip=127.0.0.1&payment_method=1&
ccn=XXXXXXXXXXXX4242&cvc_code=XXX&cardholder_name=GatewayTest&exp_month=12&
exp_year=2017&recurring_id=80780000&signature=SIGNATURE

If the payment was successful, you'll receive a successful response.

Recurring response example

transactionid=80780001&transid=80780001&status=0&errormessage=&errmsg=&amount=1.23&price=1.23&
currency=USD&orderid=PowerPay21-Test&user_id=10088265

Recurring Migration

Now you can migrate your recurring payment from the previous acquirer to payabl..
To move your recurring payment you need to request a few parameters from your current/previous provider + cardholder card details. This will allow you to continue recurring payments without cardholder participation and passing 3DS again.

You need to send a transaction with recurring_id = INIT (see previouse chapter) to /payment_authorize link with additional parameters in request below:

Parameter nameFormatLengthDescription
banknet_dateMMDD4 digitsMastercard Settlement date
banknet_ref_numberalphanumericup to 12 digitsMastercard Financial Product Code and Banknet Reference
visa_transaction_idnumeric15 digitsVisa transaction Identifier
+ full credit card data without CVV

And add the parameter:

  • Amount: with 0.00 value for only migration
  • Amount: > 0.00 value for migration and authorization

When payabl. receives the recurring_id = INIT for the initial transaction and validates the request. If all fields present with correct values, payable. will register an initial transaction that will not be sent to any scheme. All the provided data will be stored for future recurring transactions.
With this, you will need to retrieve our transaction_id and use it for subsequent recurring transactions by now sending recurring_id = transaction_id without any special fields.

🚧

Please contact your Account manager or Technical support team to enable Recurring migration function for your account


Our Technical Support team is there to help you:
Email: [email protected]
Available Monday – Friday between 09:00 and 17:00 CET/CEST