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.
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) 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:
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:
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.
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.
When executing a payment registration, the following sequence of steps takes place:
Once the payment registration has been created, the recurring billing will automatically be triggered based on its configuration.
When checking for the details of a payment registration, the following sequence of steps takes place:
When cancelling an existing payment registration, the following sequence of steps takes place:
Once a payment registration has been cancelled, the recurring billing process will be stopped immediately.
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.
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"
}
}
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"
}
}
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.
GET /payments/v1/registrations/275496 HTTP/1.1
Host: api-test-aqount.finance.arvato.com
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
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"
}
}
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.
DELETE /payments/v1/registrations/275496 HTTP/1.1
Host: api-test-aqount.finance.arvato.com
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
HTTP/1.1 200 OK