Payment registration

An overview of the typical use case handling the application of recurring payments in Accounting as a Service using the concept of payment registrations.

A payment registration can either be user to story payment instruments e.g. in a webshop to avoid customers to re-type them when they come back for a following order or it can be used for recurring payments, where a customer orders once and gets charged multiple times. Subscription products are a typical field of application for using the method of recurring payments. With a subscription product, the customer pays for access to the product under a subscription and receives recurring billing. Subscription products have become popular product forms, and they will gain more popularity over time as more customers adopt this model.

When dealing with recurring payments, the payment module supports the following 3 different types: card payments, wallet payments as well as SEPA direct debit.

In all cases, a payment registration will be needed. The registration serves to persist the payment instrument (see main entities of the payment module) so that the instrument can be used for further processing of all upcoming transactions related to recurring payments.

Credentials/Card-on-File (CoF) vs. Subscription

This section gives a brief overview on how to distinguish between the concept of Credentials/Card-on-File (CoF) and Subscription. Using Accounting as a Service, both forms of payment do require the payment registration as the underlying technical concept.

Card/Credentials on File (CoF)

Card/Credentials on File (CoF) reflects the general concept of card details being stored to streamline the checkout process for returning customers. The concept can be used for one-click payments, pay-per use services, or any recurring payment that does not follow a fixed schedule.

The payment flow for CoF differentiates between the following 2 transaction types:

  • Recurring: Transactions processed with a fixed amount and fixed, regular intervals which do not exceed the period of 1 year between 2 transactions, representing an agreement between a cardholder and the merchant to purchase goods or services provided over a period of time.
  • Unscheduled: Transactions using a stored credential for a fixed or variable amount that do not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds.

The overall process for CoF is defined by VISA, MasterCard, AmEx and Discover. All of these forms of payment are based on a "TraceID"/" TransactionID" as an additional unique identifier to trace back past authentications. However, the detailed process handling differs from PSP to PSP and from card scheme to card scheme.

The following 2 different types of use cases exist:

  • Customer Initiated Transaction (CIT): The customer is in front of the device and acts as the actor triggering the process.
  • Merchant Initiated Transaction (MIT): The customer is not in front of the device, but the process is triggered by a legitimated merchant.
Subscription

Subscription represents a form of recurring payments that occur on a fixed schedule. Popular examples of subscription-based payments are music and TV streaming services.

Accounting as a Service has a dedicated subscription module to provide sophisticated subscription management.

How it works

When working with payment registration, you should be aware of the 3 following different states a registration can have (see property of registrationStatus when requesting the registration details):

  • Registering: Reflects the initial state of a registration right after the creation. The state can be considered an intermediate state, automatically transitioning into RegistrationActive or RegistrationFailed.
  • RegistrationActive: In case the creation of the registration has been successfully processed, the registration will move from Registering into this state.
  • RegistrationFailed: In case the creation of the registration has failed for some reason, the registration will move from Registering into this state.

Please note that there is no possibility to update an existing registration. In case, you need to go for changes on the registration, you will have to cancel the existing registration and request the creation of a new registration. While working with payment registrations, here is a list of the main activities that you will have to take care of.

Create a payment registration

When executing a payment registration, the following sequence of steps takes place:

  1. (Prerequisite) Customer subscribes for a product. During checkout, customer selects payment method and provides all relevant payment information.
  2. (Prerequisite) Accounting as a Service checks and validates the information provided and provides merchant with the payment token representing the payment instrument ready for use.
  3. Merchant requests creation of payment registration using the newly created payment instrument.
  4. Accounting as a Service creates new payment registration and returns the registration token.
  5. Please refer to the subscription module overview for further steps

Once the payment registration has been created, the recurring billing will automatically be triggered based on its configuration.

High-level process description
An overview using BPMN to describe the process flow
Checkout the BPMN illustration to get an overview of the process, including the various activities and participating main actors.

View payment registration details

When checking for the details of a payment registration, the following sequence of steps takes place:

  1. (Prerequisite) Payment registration has been created and merchant has been provided with the registration token.
  2. Merchant requests details of payment registration for the provided registration token.
  3. Accounting as a Service sends backs the details of the payment registration to the merchant.

Cancel a payment registration

When cancelling an existing payment registration, the following sequence of steps takes place:

  1. (Prerequisite) Payment registration has been created and merchant has been provided with the registration token.
  2. Merchant requests cancellation of payment registration with specific registration token.
  3. Accounting as a Service processes the cancellation of the registration.

Once a payment registration has been cancelled, the recurring billing process will be stopped immediately.

How to implement

Create payment registration

To create a payment registration, make a POST /payments/{version}/registrations request. Beside information about the customer, you will have to provide the payment token to refer to the payment instrument for which you would like to create a payment registration.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
POST /payments/v1/registrations HTTP/1.1
Host: api-test-aqount.finance.arvato.com
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
    "paymentInstrument": {
        "id": "a36c4b6b-f880-4e07-acb0-797b1449f0e3",
        "paymentMethodName": "MasterCard"
    },
    "billingCustomer": {
        "address": {
            "addressType": "main address",
            "careOf": "Mr. Bloom",
            "countryCode": "DE",
            "postalCode": "53332",
            "postalPlace": "Bornheim",
            "street": "Am Muenchshof",
            "streetNumber": "2",
            "streetNumberAdditional": "b"
        },
        "birthDate": "1984-11-11",
        "companyName": "myCompany",
        "customerCategory": "CUST-2",
        "customerNumber": "cust1234",
        "email": "john@mycompany.com",
        "firstName": "John",
        "identificationNumber": "1873387",
        "lastName": "Doe",
        "mobilePhone": "+49 160 123456",
        "phone": "+49 80 123456",
        "salutation": "MR"
    }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentMerchantAccount": "SAMPLEMERCHANT123",
  "registrationToken": "275496",
  "registrationStatus": "RegistrationActivated",
  "dateCreated": "2021-08-31T12:47:31.027",
  "dateModified": "2021-08-31T12:47:31.027",
  "paymentToken": "a36c4b6b-f880-4e07-acb0-797b1449f0e3",
  "paymentMethodName": "MasterCard",
  "details": {
    "last4Digits": "1096",
    "expirationMonth": 9,
    "expirationYear": 2023,
    "cardHolder": "John Doe"
  }
}

View payment registration details

To view the details of a payment registration, make a GET /payments/{version}/registrations/{paymentRegistrationId} request, where {paymentRegistrationId} is the unique identifier of the registration (i.e. the registration token) as it has been returned as part of the response from the request to create a registration.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
GET /payments/v1/registrations/275496 HTTP/1.1
Host: api-test-aqount.finance.arvato.com
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentMerchantAccount": "SAMPLEMERCHANT123",
  "registrationToken": "275496",
  "registrationStatus": "RegistrationActivated",
  "dateCreated": "2021-08-31T12:47:31.027",
  "dateModified": "2021-08-31T12:47:31.027",
  "paymentToken": "a36c4b6b-f880-4e07-acb0-797b1449f0e3",
  "paymentMethodName": "MasterCard",
  "details": {
    "last4Digits": "1096",
    "expirationMonth": 9,
    "expirationYear": 2023,
    "cardHolder": "John Doe"
  }
}

Cancel payment registration

To view the details of a payment registration, make a DEL /payments/{version}/registrations/{paymentRegistrationId} request, where {paymentRegistrationId} is the unique identifier of the registration (i.e. the registration token) as it has been returned as part of the response from the request to create a registration.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
DELETE /payments/v1/registrations/275496 HTTP/1.1
Host: api-test-aqount.finance.arvato.com
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Sample response
HTTP/1.1 200 OK

See also