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: |
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 |
---|---|
|
for unscheduled recurring payments (with different amounts) |
|
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 |
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. |
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 |
Date when mandate was signed by the consumer. |
Enumeration |
request_parameters#SINGLE (used by default if no transaction type is stated) or #RECUR or request_parameters#INITIAL. |
Source orders based on PayPal
For all acquirers
Parameter | Data type | Short description |
---|---|---|
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 |
---|---|---|
Enumeration |
Possible values are |
|
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 |
---|---|---|
Enumeration |
request_parameters#SINGLE (used by default if no transaction type is stated) or #RECUR or request_parameters#INITIAL. |
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. |
Parameter | Data type | Short description |
---|---|---|
dueDate |
Date as |
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 |
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.