Common API elements

On this page you will find helpful information of common elements used across all modules in Accounting as a Service.

Authentication

When working with the REST API of Accounting as a Service, you will have to use one of your subscription keys as the form of authentication for all API related requests that you are going to make.

You will be provided with a primary and secondary subscription key for each of the following environments.

Available environments

You should be aware of the following environments of Accounting as a Service:

• TEST environment: The TEST environment is the right environment to work with when implementing and testing your integration with Accounting as a Service. To work with the API of the TEST environment, you will have to use https://api-uat.accounting.riverty.io as the base URL for all your requests. Also, please note that there is a dedicated API Explorer of the TEST environment that can be found under https://api-explorer-uat.accounting.riverty.io.
• PROD environment: When working with the PROD environment, you will have to use https://api.accounting.riverty.io as the base URL for all your requests. Keep in mind to make use of the GO-Live checklist before switching to LIVE mode. The API Explorer of the PROD environment can be found under https://api-explorer.accounting.riverty.io/.

How to get your subscription keys

Your subscription keys are part of your user profile related data, and as such you can find and manage them in your user profile when signing in to the API Explorer. Please note, that there is an instance of the API Explorer for each of the 2 environments (TEST and PROD). You will need a dedicated user account for each of the 2 environments (TEST and PROD).

Once you sign up for your test account, you will set up a user account in the TEST environment. You will receive an email to confirm the account.

Right after the user account has been confirmed, you can access your profile by signing in to the API Explorer of the TEST environment and check out your subscription keys as shown in the following screenshot.

If you have decided to use Accounting as a Service, and we have received and validated your technical application, you will be provided with a dedicated product that will be made available to you in the product list of the API Explorer. The product will contain specific configuration tailored to your needs based on the information from your technical application (e.g. supported payment methods and PSPs). You will need to subscribe to this product (first in TEST, later in PROD environment) by following the same procedure as for the subscription related to the sample client.

Please note that your subscription keys are sensitive data that should be securely stored in your system. If one of your subscription key is lost or compromised, a new subscription key will need to be generated. In case you require the replacement (new generation) of one of your subscription keys, you can do so via the user profile page in the API Explorer of the affected environment.

How to use your subscription key

When indicating the subscription key for making requests, you will have to provide the key by using the request header attribute X-Subscription-Key as shown in the following sample request using the endpoint /payments/{version}/token of the TEST environment and the sample subscription key 321123ab544047e795db43e5123423tz:

GET /payments/v1/token HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: 321123ab544047e795db43e5123423tz

Notifications

While communication is primarily done via requests to the REST API followed by a synchronous response, Accounting as a Service also supports the concept of notifications via webhooks. That means that in case of specific events occuring inside Accounting as a Service (e.g. a status change of a payment transaction), the system will trigger a notification callback resulting in Accounting as a Service calling an endpoint of your system that was previously defined via the Administration API (to be further explained in this section).

Configuring notification callbacks

For the purpose of managing endpoints to be used as notification callbacks, Accounting as a Service provides a dedicated API for administration offering the following types of operation:

Register a new notification callback

To register (i.e. add) a new notification callback, make a POST /administration/{version}/notification-callbacks request. You will have to provide the list of notification types (see notificationTypes) for which you would like to register a callbackUrl as the endpoint to be called by Accounting as a Service.

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

Sample request

POST /administration/v1/notification-callbacks HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
    "callbackUrl": "https://webhook.site/05fb4cfc-4d65-4c23-ac37-e176318baa20",
    "notificationTypes": [
        "accounting/refundCompleted",
        "accounting/documentCreated"
    ],
    "description": "My Test Subscription"
}

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "351b4bb4-8b0f-470e-83dd-a765d62eba73",
  "callbackUrl": "https://webhook.site/05fb4cfc-4d65-4c23-ac37-e176318baa20",
  "notificationTypes": [
    "accounting/refundCompleted",
    "accounting/documentCreated"
  ],
  "description": "My Test Subscription"
}

List all notification callbacks

To get an overview of all registered notification callbacks, make a GET /administration/v1/notification-callbacks.

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

Sample request

GET /administration/v1/notification-callbacks HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "351b4bb4-8b0f-470e-83dd-a765d62eba73",
    "callbackUrl": "https://webhook.site/405fb4cfc-4d65-4c23-ac37-e176318baa20",
    "notificationTypes": [
      "accounting/refundCompleted",
      "accounting/documentCreated"
    ],
    "description": "My Test Subscription"
  }
]

Delete notification callback

To deregister (i.e. delete) a notification callback, make a DEL /administration/{version}/notification-callbacks/{callbackId}, where callbackId is the ID of the existing notification callback that you would like to be removed.

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

Sample request

DELETE /administration/v1/notification-callbacks/351b4bb4-8b0f-470e-83dd-a765d62eba73 HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "351b4bb4-8b0f-470e-83dd-a765d62eba73",
  "callbackUrl": "https://webhook.site/05fb4cfc-4d65-4c23-ac37-e176318baa20",
  "notificationTypes": [
    "accounting/refundCompleted",
    "accounting/documentCreated"
  ],
  "description": "My Test Subscription"
}

Notification types

When registering a new notification callback, you will have to provide the list of notification types to be taken into account when triggering a callback. Each module of Accounting as a Service comes along with its own types of notification. Depending on your needs, take a look at the following pages describing the notification types of each module:

• Payment module related notifications
• Subscription module related notifications
• Accounting module related notifications

Main entities

The following list provides you with an overview of the main entities as they are commonly referred to and used in Accounting as a Service:

• merchant: Accounting as a Service has been made for the merchant considered to be the business client of Accounting as a Service. As a merchant, you are running a business (e.g. a web shop) and Accounting as a Service can be utilized by you to cover parts of your payment and accounting processes. Accounting as a Service supports multi-tenancy. Every merchant is set up as a separate instance in the system. Thereby, all configurations and the data saved is separated from all other merchants.
• customer: The term customer refers to the end consumer of the merchant (e.g. the shopper in the webshop). The customer is the one who buys (or consumes) a product from the merchant. The request of the customer to buy a product is managed by an order which needs to be executed.
• product: A product represents a good, licence or service which is offered by the merchant. A product is either physical or not. In case of a physical product, the order processing usually includes shipping activities.
• order: The order serves as the connection between the customer and the product. For managing the financial processing of an order (including services such as payment reminders, dunning process), you can rely on the accounting module. When handling the related payment, you can use the payment module for managing the process. In case of subscription-based product consumption, a contract will be needed including all required billing information. An order may result from a subscription contract or from a traditional (webshop) order. To handle subscriptions, you can use the subscription module .

In addition to the list of commonly used entities as shown above, you can also find an overview of module-specific entities or module-specific information on common entities on the overview page of each module. Depending on your needs and interests, you might visit the following sections as well:

• For main entities of the Payments module, please check here
• For main entities of the Subscriptions module, please check here
• For main entities of the Accounting module, please check here

Entity-Relationship-Model

The following simplified diagram illustrates the relationship between the common main entities.

See also

• Sign up for your test account
• Technical application
• GO-Live checklist
• Payment module
• Accounting module
• Subscription module