Recurring

Charge your customer on a regular basis.

Introduction

Recurring payments is a feature which lets you debit a customer’s account with a fixed amount on a regular basis for recurring services. These could be for example:

  • Membership fees
  • Subscription to a regular or varying service
  • Registration within a shop to avoid re-entering of payment data
  • Trial periods, which require an initial registration for a possible later service

As seen in the examples above, recurring payments can be used to for single debit transactions as well - It’s important to note, that by using recurring payments a customer can be charged without him/her being present at the time of the transaction.

Overview

The Unzer API treats recurring payments in two different ways:

  1. Recurring payments without the customer being present during the transaction
  2. Saving a customer’s payment method and corresponding details (only applies to payment pages)

In case your business model revolves around a subscription service, recurring payments will make the regular charging much easier and more convenient. If your Unzer integration encompasses either an Embedded Payment Page or a Hosted Payment Page, you can give your customers the option to save their preferred payment method for later use. That way a returning customer can conveniently choose his saved and (partially) pre-filled payment method, without having to re-enter all their payment details from scratch.

Supported payment types

Certain payment types require customer interaction during the recurring-registration, while others can be registered without. The table down below shows all payment types compatible with recurring payments:

Payment type Recurring
Credit Card Yes
Paypal Yes
Unzer Direct Debit Yes
(automatically after successful charge)

Registering a payment type as recurring

To register a supported payment type as recurring, the following call has to be executed:

curl https://api.unzer.com/v1/types/<paymentId>/recurring
  -u s-priv-xxxxxxxxxx: \
  -d returnUrl=https://www.unzer.com
POST https://api.unzer.com/v1/types/<paymentId>/recurring

Body:
{
  "returnUrl" : "https://www.unzer.com"
}
Authentication
Note: Calling /types/<id>/recurring is only possible with a private key!

When done correctly, the response should look something like this:

Recurring response

{
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "redirectUrl": "https://dev-payment.unzer.com/v1/redirect/3ds/s-I98KIK9alGzO",
    "message": {
        "code": "COR.000.200.000",
        "customer": "Transaction pending"
    },
    "returnUrl": "https://www.unzer.com",
    "date": "2019-03-07 11:42:47",
    "resources": {
        "customerId": "",
        "metadataId": ""
    },
    "processing": {
        "uniqueId": "31HA07BC8110C3EE06224EB9C3FC44C2",
        "shortId": "4158.8536.7528"
    }
}

It is also possible to pass a customer resource and metadata inside a resources object during a recurring call. Here’s an overview of all possible parameters:

Parameter Mandatory Description
redirectUrl Yes The URL to which the customer gets redirected in case of a 3ds transaction
resources.customerId No A customer resource ID
resources.metadataId No A metadata resource ID

Credit Card

When you call the types/{payment_type_id}/recurring endpoint to register a credit card as a recurring payment, the following happens:

  1. The Unzer API authorizes €1 to validate the credit card.
    If there’s no EUR currency available, the next best configured currency is used.
  2. The customer gets redirected to pass their 3-D Secure validation.
  3. After successful 3-D Secure validation, the credit card is registered as a recurring payment.
    The 3ds flag is set to false for all future transactions. This allows you to charge the credit card with no user interaction.
  4. The Unzer API cancels the €1 authorization immediately after the 3-D Secure validation.

Paypal

When trying to register a PayPal types resources as recurring, two things are necessary:

1. PayPal configuration

In order to execute recurring payments via PayPal, customers have to go to their PayPal settings and set a flag to allow recurring payments on their account. Without that option enabled, a direct charge without customer interaction (for example a subscription service on a monthly basis) will be blocked by PayPal and return an error.

2. Register the types resource as recurring

If the PayPal account of a customer is properly configured, you can register their account as recurring. To do so, simply create a new PayPal types resource and execute the following call afterwards: /types/<pay_pal_id>/recurring as shown in the section above. After you’ve forwarded your customer to the redirect URL (received in the response of the recurring call), he/she will be asked to log into their PayPal account and chose their preferred payment option (if applicable). No authorize or charge takes place at this stage. After that, this PayPal types resource is successfully registered as recurring and can be used for direct charges without further customer interactions.

Unzer Direct Debit

Although it’s not possible to register a Unzer Direct Debit (or Unzer Direct Debit Secured payment type manually, you can still use the recurring feature. Instead of calling types/<id>/recurring directly, an Unzer Direct Debit resource is automatically set as recurring after a successful charge.

Registering with the Unique ID

In case you’re familiar with Unzer’s old API and it’s specific recurring implementation, you know that registering a payment type as recurring required the unique ID (UUID) of an individual transaction. The new API still supports this functionality in addition to everything above. You can find a short guide on how to do so here.

PayPal recurring registration
Note: Unlike credit card or Unzer Direct Debit recurring-registrations, PayPal doesn’t authorize or charge and cancel 1€.