recurPayment

recurPayment

recurPayment is one of the transaction-based operations (back-end operations) offered by QPAY Checkout Page and QMORE Checkout Seamless. You can either call this operation automatically from the back-end of your online shop or manually from your web interface which you have implemented for administration purposes.

The operation recurPayment is used to create a new order and a new payment attempt by reusing the payment information available in a previous order, the so-called source order.

The required order of the parameter values when computing the fingerprint for QPAY Checkout Page is: customerId, shopId, toolkitPassword, secret, command, language, orderNumber, sourceOrderNumber, autoDeposit, orderDescription, amount, currency, orderReference, customerStatement, mandateId, mandateSignatureDate, creditorId, dueDate, transactionIdentifier, useIbanBic, merchantTokenizationFlag and periodicType.

The required order of the parameter values when computing the fingerprint for QMORE Checkout Seamless is: customerId, shopId, password, secret, language, orderNumber, sourceOrderNumber, autoDeposit, orderDescription, amount, currency, orderReference, customerStatement, mandateId, mandateSignatureDate, creditorId, dueDate, transactionIdentifier, useIbanBic, merchantTokenizationFlag and periodicType.

Additional required request parameters

Parameter Data type Short description

amount

Amount

Debit amount.

currency

Alphabetic with a fixed length of 3 or numeric with a fixed length of 3.

Currency code of amount.

orderDescription

Alphanumeric with a variable length of up to 255 characters.

Textual description of order.

sourceOrderNumber

Numeric with a variable length of up to 9 digits.

Original order number used for new payment.

Additional required request parameters for credit card

According to credit card company requirements for risk minimization, there are two parameters for recurring payments for QENTA Checkout Page and QENTA Checkout Seamless:

Parameter Data type Short description

merchantTokenizationFlag

Boolean

Used to set whether credit card details are stored for later use.

periodicType

Enumeration

2 possible values: ucof, recurring.
merchantTokenizationFlag

Use this request parameter to set the recurring flaggings for specific orders.
You have to set the merchantTokenizationFlag to TRUE to save consumer’s card details for later use (e.g. one-click or auto-top-up or subscriptions).

periodicType

This request parameter may be used to set the periodic type of initial and recurring payments.
It may be set to 3 different values:

periodicType value Description

ucof

for unscheduled recurring payments (with different amounts)

recurring

for recurring payments like subscriptions (with same interval and same amount)

Regarding the fingerprint calculation, the relevant credit card parameters are appended to the payment facilitator parameters in the described order.

Additional optional request parameters

For recurring payments additional parameters are available regarding the automated depositing and order details.

Parameter Data type Short description

autoDeposit

Enumeration

Possible values are Yes and No. Yes is used for enabling and No for disabling automated deposit and day-end closing of payments.

customerStatement

Alphanumeric with a variable length of up to 254 characters that may be restricted for specific payment methods.

Text displayed on bank statement issued to your consumer by the financial service provider.

orderNumber

Numeric with a variable length of up to 9 digits.

Order number of payment.

orderReference

Alphanumeric with a variable length of up to 128 characters.

Unique order reference ID sent from merchant to financial institution.

Additionally if you are using the QENTA Fraud Prevention & Fraud Detection the following data on the consumer can be submitted for processing.

Parameter Data type Short description

consumerEmail

Alphanumeric with special characters and a variable length of up to 256.

E-mail address of consumer.

consumerBirthDate

Numeric with special characters and a fixed length of 10.

Birth date of consumer in the format YYYY-MM-DD.

consumerTaxIdentificationNumber

Alphanumeric with special characters and a variable length of up to 32.

Tax identification number of consumer.

consumerDriversLicenseNumber

Alphanumeric with special characters and a variable length of up to 32.

Drivers license number of consumer.

consumerDriversLicenseState

Alphabetic with a fixed length of 2 for US and CA, otherwise up to 40.

State which issued the drivers license of consumer.

consumerDriversLicenseCountry

Alphabetic with a fixed length of 2.

Country which issued the drivers license of consumer

consumerBillingFirstName

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 128.

First name of consumer.

consumerBillingLastName

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 128.

Last name of consumer.

consumerBillingAddress1

Alphanumeric with special characters and a variable length of up to 256.

Name of street and optionally the house number.

consumerBillingAddress2

Alphanumeric with special characters and a variable length of up to 256.

The house number if not already set in consumerBillingAddress1.

consumerBillingCity

Alphanumeric with special characters and a variable length of up to 40.

Billing city.

consumerBillingState

Alphabetic with a fixed length of 2 for US and CA, otherwise p to 40.

Billing state.

consumerBillingCountry

Alphabetic with a fixed length of 2.

Billing country code (ISO 3166-1).

consumerBillingZipCode

Alphanumeric with special characters and a variable length of up to 40.

Billing zip code.

consumerBillingPhone

Alphanumeric with a variable length of up to 20.

Phone number of consumer.

consumerBillingFax

Alphanumeric with a variable length of up to 20.

Fax number of consumer.

consumerShippingFirstName

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 128.

First name of consumer.

consumerShippingLastName

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 128.

Last name of consumer.

consumerShippingAddress1

Alphanumeric with special characters and a variable length of up to 256.

Name of street and optionally the house number.

consumerShippingAddress2

Alphanumeric with special characters and a variable length of up to 256.

The house number if not already set in consumerShippingAddress1.

consumerShippingCity

Alphanumeric with special characters and a variable length of up to 40.

Shipping city.

consumerShippingState

Alphabetic with a fixed length of 2 for US and CA, otherwise a variable length of up to 40.

Shipping state.

consumerShippingCountry

Alphabetic with a fixed length of 2.

Shipping country code (ISO 3166-1).

consumerShippingZipCode

Alphanumeric with special characters and a variable length of up to 40.

Shipping ZIP code.

consumerShippingPhone

Alphanumeric with a variable length of up to 20.

Shipping phone number.

consumerShippingFax

Alphanumeric with a variable length of up to 20.

Shipping fax number.

consumerIpAddress

Numeric with special characters.

IP address of consumer.
Note that this parameter is not part of the fingerprint.

Continuing the fingerprint order described above, the required order of the parameter values when computing the fingerprint is: consumerEmail, consumerBirthDate, consumerTaxIdentificationNumber, consumerDriversLicenseNumber, consumerDriversLicenseState, consumerDriversLicenseCountry, consumerBillingFirstName, consumerBillingLastName, consumerBillingAddress1, consumerBillingAddress2, consumerBillingCity, consumerBillingState, consumerBillingCountry, consumerBillingZipCode, consumerBillingPhone, consumerBillingFax, consumerShippingFirstName, consumerShippingLastName, consumerShippingAddress1, consumerShippingAddress2, consumerShippingCity, consumerShippingState, consumerShippingCountry, consumerShippingZipCode, consumerShippingPhone and consumerShippingFax.

Note that the parameter consumerIpAddress is not part of the fingerprint.

Payment facilitator model

When making a recurring payment e.g. in a marketplace, the payment facilitator parameters must be provided for the back-end operation recurPayment using the data of the marketplace.

Regarding the fingerprint calculation, the relevant payment facilitator parameters are appended to the consumer data parameters in the described order.

Source orders based on SEPA Direct Debit

For all acquirers
Parameter Data type Short description

mandateId

Alphanumeric with a variable length of up to 35 characters.

Identifier of mandate.

mandateSignatureDate

Date as DD.MM.YYYY

Date when mandate was signed by the consumer.

transactionIdentifier

Enumeration

request_parameters#SINGLE (used by default if no transaction type is stated) or #RECUR or request_parameters#INITIAL.
Only for Wirecard Bank as acquirer
Parameter Data type Short description

creditorId

Alphanumeric with a variable length of up to 35 characters.

Unique identifier of creditor.

dueDate

Date as DD.MM.YYYY

Date when payment is debited from consumer’s bank account.

Source orders based on PayPal

For all acquirers
Parameter Data type Short description

request_parameters#transactionIdentifier

Enumeration

request_parameters#SINGLE (used by default if no transaction type is stated) or #RECUR.

SEPA Direct Debit for source orders based on Sofort

The following parameters are applicable for recurring transactions using SEPA Direct Debit for Sofort source orders.

Only for Wirecard Bank as acquirer
Parameter Data type Short description

useIbanBic

Enumeration

Possible values are Yes or No.

request_parameters#transactionIdentifier

Enumeration

request_parameters#SINGLE (used by default if no transaction type is stated) or #RECUR or request_parameters#INITIAL.
For Computop as acquirer

Recurring transactions for Computop do not require the parameter useIbanBic.

Parameter Data type Short description

request_parameters#transactionIdentifier

Enumeration

request_parameters#SINGLE (used by default if no transaction type is stated) or #RECUR or request_parameters#INITIAL.
For Hobex as acquirer

Recurring transactions for Hobex do neither require the parameter useIbanBic nor the parameter transactionIdentifier.

Detailed description of parameters

dueDate

If you choose Wirecard Bank as your acquirer, you can calculate the due date yourself. QENTA requires from you to submit recurring and final direct debit payments four (4) banking days before the due date.

Please refer to SEPA Direct Debit for further information and details on the due date calculation.

transactionIdentifier

Only within recurring transactions besides the values SINGLE and INITIAL there is another value possible:

RECUR

Subsequent transaction based on a previous transaction (source order) for which the transactionIdentifier value INITIAL was used.

Please note that NO recurring transactions may be carried out if the transactionIdentifier value SINGLE is used in the source order.

For recurring transactions based on SEPA Direct Debit, a given authorization by the consumer is used for regular direct debits initiated by the creditor, e.g payment for monthly rent. The initial mandateId signed by the consumer is used as a basis for all recurring transactions.

The transaction type "final" defines the last transaction of a series of transactions. After a final payment has been processed for a mandate, it is not possible to generate more transactions for that mandate. At the moment QENTA does not support final transactions. Please set your transaction to RECUR instead.

useIbanBic

For merchants who wish to carry out recurring transactions based on Sofort but may not derive any IBAN/BIC from the source order, because it was made too long ago in the past and therefore no IBAN/BIC data are retrievable, Wirecard Bank offers the possibility to convert the available account number and bank sorting code into IBAN and BIC, thus allowing a recurring transaction based on SEPA Direct Debit.

Therefore, if No is set by the merchant, conversion of account number and bank sorting code is carried out and a recurring payment based on SEPA Direct Debit is made. If Yes is set by the merchant, IBAN/BIC are taken from the Sofort source order and a recurring transaction based on SEPA Direct Debit is made.

Please contact our Sales teams for enabling this feature.

Additional response parameters

The following parameters are used in addition to the response parameters needed for all back-end operations (QPAY Checkout Page and QMORE Checkout Seamless).

Parameter Data type Short description

orderNumber

Numeric with a variable length of up to 9 digits.

Order number of payment.
Table 1. Source orders based on SEPA Direct Debit
Parameter Data type Short description

dueDate

Date as DD.MM.YYYY

Date when payment is debited from consumer’s bank account.

mandateId

Alphanumeric with a variable length of up to 35 characters.

Identifier of displayed mandate.

mandateSignatureDate

Date as DD.MM.YYYY

Date when the mandate was signed by the consumer.

FAQ

It is not possible to extend an authorization, therefore I will use a recurring payment which returns a new orderId. Does the original authorization then expire immediately?

No, the original authorization does not change its state and it will still be authorized.

This means that in such situation there are then two authorizations for one transaction?

Yes, but we encourage you to cancel the original authorization as soon as possible. Additionally if the transaction(s) will exceed the limit, they will be declined by the issuing bank.

What is the time frame for creating a recurring payment based on an already existing order?

You are able to to a recurring payment on an existing order which is not older than 400 days.

Is it possible to use expired or reversed orders as source orders for recurring payments?

Yes, it is possible within a time frame of 400 days.