Interfaces
Integration Guide
Recurring Payments
Before you start implementing Recurring Payments, please make sure, that you read and understood the PSD2 chapter!
Recurring Payments are a feature sub-set of the Transaction Interface and enable you -the merchant- to trigger subsequent transactions, without card holder presence.
Use-cases are subscription models, installments, "no-show" transactions for hotels and more.
It is important to understand, that each subsequent transaction is triggered by your system! Saferpay does not charge the customer, without you requesting it, which also applies to recurring payments.
Requirements:
- one active Saferpay ecommerce terminal via which payment can be carried out and the associated
- Saferpay terminal number (TerminalId parameter) and Saferpay customer number (CustomerId parameter).
- valid acceptance agreement for credit cards or other payment methods, that support recurring payments.
Supported Payment Methods
- American Express
- Bonus Card
- Diners Club International & Discover
- JCB
- Mastercard
- MyOne
- SEPA Direct Debit
- Visa & V PAY
Recurring Payments with the Referenced Transactions Method
With this method, the initial transaction is performed with either the PaymentPage Interface or with the Transaction Interface leading the cardholder through a normal ecommerce payment process, including entering the CVC and 3DSecure authentication. The first transaction is flagged as initial transaction. The Transaction ID of the initial transaction can then be used for referenced/recurring transactions.
1. Initial Transaction:
The Initial Transaction can be performed with the PaymentPage Interface or via the Transaction Interface, using Transaction Initialize and Transaction Authorize .
This transaction basically captures the credit card details and sets a flag, to mark it as an initial transaction that can be used as a reference for recurring transactions.
To define a transaction as the initial transaction, you need to set a special flag with either the PaymentPage Initialize Request or Transaction Initialize Request by defining the Container Payment.Recurring/Installment.
If you are within PSD2-scope, the amount MUST NOT change, between the initial and the recurring transaction. If it does change, you'll run into a soft decline.
If you have to change the amount, you have to re-start this process over again and do a new initial-transaction.
1
{
2
"RequestHeader": {
3
"SpecVersion": "[CURRENT SPEC-VERSION]",
4
"CustomerId": "[your customer id]",
5
"RequestId": "[unique request id]",
6
"RetryIndicator": 0
7
},
8
"TerminalId": "[your terminal id]",
9
"Payment": {
10
"Amount": {
11
"Value": "100",
12
"CurrencyCode": "CHF"
13
},
14
"Recurring": {
15
"Initial": true
16
}
17
},
18
"Payer": {
19
"LanguageCode": "en"
20
},
21
"ReturnUrls": {
22
"Success": "[your shop payment success url]",
23
"Fail": "[your shop payment fail url]"
24
},
25
"Styling": {
26
"CssUrl": "[your shop css url]"
27
}
28
}
Copied!
2. Validating the transaction
Depending on the Interface used to initialize the transaction, you can validate the payment and assess transaction based information with either:
Both request will provide you with information about the Transaction including the 3D Secure response:
Here is an example of a PaymentPage Assert Response:
1
{
2
"ResponseHeader": {
3
"SpecVersion": "[CURRENT SPEC-VERSION]",
4
"RequestId": "[your request id]"
5
},
6
"Transaction": {
7
"Type": "PAYMENT",
8
"Status": "AUTHORIZED",
9
"Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
10
"Date": "2017-06-18T09:19:27.078Z",
11
"Amount": {
12
"Value": "100",
13
"CurrencyCode": "CHF"
14
},
15
"AcquirerName": "AcquirerName",
16
"AcquirerReference": "Reference"
17
},
18
"PaymentMeans": {
19
"Brand": {
20
"PaymentMethod": "SAFERPAYTEST",
21
"Name": "SaferpayTestCard"
22
},
23
"DisplayText": "9123 45xx xxxx 1234",
24
"Card": {
25
"MaskedNumber": "912345xxxxxx1234",
26
"ExpYear": 2021,
27
"ExpMonth": 9,
28
"HolderName": "Max Mustermann",
29
"CountryCode": "CH"
30
}
31
},
32
"Payer": {
33
"IpAddress": "1.2.3.4",
34
"IpLocation": "CH"
35
},
36
"ThreeDs": {
37
"Authenticated": true,
38
"LiabilityShift": true,
39
"Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
40
"VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
41
}
42
}
Copied!
You must save the Transaction.Id - value, returned in the PaymentPage Assert or Transaction Authorize response as this value will be used to reference recurring payments.
We recommend only to proceed, if the parameters Authenticated and LiabilityShift are true. This value indicates that the card holder has performed a full successful authentication (3D Secure process) at his bank. This option provides the highest level of security against fraud.
3. Recurring Transaction:
The next step is to perform the actual recurring transaction(s). The API-Function that is required is Authorize Referenced. You have to simply submit the TransactionId from your initial transaction (discussed in step 2) to perform the recurring transaction(s).
(click to enlarge)
- 1.Gather the TransactionId from the previous, initial, transaction
- 2.Aquire the necessary payment-data e.g. Amount, Currency, OrderId etc.
- 3.
- You will get the authorization-response right away
- 4.Validate the request response
- 5.Depending on the outcome of step 4 you may
- 6.Transaction is finished!
Here is an example of a Authorize Referenced Request:
1
{
2
"RequestHeader": {
3
"SpecVersion": "[CURRENT SPEC-VERSION]",
4
"CustomerId": "[your customer id]",
5
"RequestId": "[unique request id]",
6
"RetryIndicator": 0
7
},
8
"TerminalId": "[your terminal id]",
9
"Payment": {
10
"Amount": {
11
"Value": "100",
12
"CurrencyCode": "CHF"
13
},
14
"Description": "Test123",
15
"PayerNote": "Order123_Testshop"
16
},
17
"TransactionReference": {
18
"TransactionId": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA"
19
}
20
}
Copied!
The Amount is a mandatory value which can vary from the Amount of the initial transaction. A change of amount has to be communicated with the card holder and you must re-do this whole (Initial transaction and then reference to that transaction) process, to start the recurring-chain over again, otherwise, the bank may reject the recurring transaction.
Each Transaction with the Status Authorized has to be captured to initiate the actual money transfer.
Recurring Payments using an alias
A second method is to use the Saferpay Secure Alias Store aka Secure Card Data in conjunction with the AuthorizeDirect Request with previously registered Aliases.
1. Obtaining the Alias
The alias can be obtained in multiple ways, using the Saferpay Secure Card Data store. By using the Payment Page, Transaction Interface, or even a Standalone Registration, with an ONLINE_STRONG check it is possible to do an initial transaction, to validate the card (e.g. through 3D Secure), similar to the referenced transaction-process above!
Amount values that undercut a certain value, can cause problems during the 3D Secure-process, thus we recommend a value of 500 (5,00 €). As mentioned above, this transaction can be discarded. It is only, to prevend the mentioned issues with 3D Secure!
2. Recurring Transaction
Once tha alias has been obtained, you can execute the subsequent transactions using AuthorizeDirect Request. The alias has to be filled into the PaymentMeans.Alias container.
(click to enlarge)
- 1.Gather the AliasId from the previous, initial, transaction
- 2.Aquire the necessary payment-data e.g. Amount, Currency, OrderId etc.
- 3.
- You will get the authorization-response right away
- 4.Validate the request response
- 5.Depending on the outcome of step 4 you may
- 6.Transaction is finished!
Each Transaction with the Status Authorized has to be captured to initiate the actual money transfer.
Do not set the "Recurring"-exemption with the Transaction Authorize Direct request, unless you know for sure, that you are allowed to do so!
Requesting any exemption without the conset of your acquirer and allow
Automating the Recurring Payments
Automated recurring payments have to be triggered by the merchant's system. There are multiple ways to setup up the automated triggering of payments. The easiest way is to setup a Cronjob (Linux) or a Task (Windows). With cronjobs you can schedule a command or script on your server to run automatically at a specified time and date (e.g. every minute, every 15 Minutes, every hour, or every day at 10pm or even every Sunday.)
The cronjob can be linked with a script (e.g. PHP, or a Bash script) that will be executed, every time the cronjob is triggered to automatically perform transactions. You should decide when and how often the payments have to be triggered depending on your business model and the prearranged scheduling of payments.
Last modified 5d ago