Payment request

An overview of the typical use case handling the payment execution part of the checkout procedure when using Accounting as a Service.

In webshops, the checkout refers to the virtual checkout, where the customer - once the selection of products is completed - is prompted to select his preferred payment method and enter his address. The checkout is considered a critical point in online retailing. In most cases, you will have to deal with sensitive data related to the payment method.

Using Accounting as a Service, the integration of our pre-built UI solution will enable you to fulfil PCI requirements by autonomously rendering all payment method forms and fields while encapsulating sensitive data in an iFrame and handling all communication with Accounting as a Service's REST API independently of your web shop. This way, you will not get in touch with sensitive payment information such as the credit card number. Instead, you will work with the payment token as the unique identifier of the payment instrument which encapsulates all sensitive data in the context of a received payment request (see main entitities of the payment module).

Following standard checkout scenarios, the request for payment execution comes right after the customer having selected his preferred payment method and provided all necessary payment data. Using Accounting as a Service, the data will be validated and stored as a payment instrument inside the system. For PCI compliance reason, sensitive payment information stored inside the payment instrument will not be accessible by the merchant. Instead, the merchant is supposed to make use of the payment token as the unique identifier to refer to the payment instrument for all further processing. In case of a normal checkout, the merchant will request the payment execution for a payment instrument at the time when the customer has finally confirmed his order.

The following is an example of a standard checkout flow:

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.

Payment execution options

When it comes to payment execution handling, there are 2 different options supported by Accounting as a Service.

  • Authorize and capture in 2 steps: Using this option, you will follow a 2-steps approach by authorizing the payment in first place. This way, you get the feedback and confirmation about the payment request being validated and approved onside of the customer's payment provider. The capture process takes place at a later stage (e.g. the moment you have processed the order and the products are shipped). When using this method, you are provided with the flexibility to cancel the authorization for whatever reason (e.g. the customer has cancelled the order) as long as the capture has not yet been performed. This option is applicable for card payments and wallet payments.
  • Authorize and capture in 1 step: Using this option, the customer will be charged immediately with the related amount. A cancellation of this operation is not possible. Instead, you will have to use a one of the refund options you can find here: refund to roll back the transaction. This option is applicable for card payments, online payments and wallet payments.

Authorizing a request for payment is the starting point for each payment transaction as it will be processed by the payment module. When working with payment transactions, be aware of the status field as a central element to keep track of the overall process state of the related transaction.

To get an overview of all states, have a look at the transaction state machine. Furthermore, you will find additional information on the page for handling notifications of the payment module, as the notification mechanism is closely linked to the transaction state model.

How it works

Authorize and capture later

When executing a checkout authorization and capture in 2 steps, the following sequence of steps takes place:

  1. (Prerequisite) During checkout, customer selects a 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 authorization based on the received payment token.
  4. Accounting as a Service handles the payment authorization request. Using notifications, Accounting as a Service will trigger an event about the status change of the related payment transaction.
  5. Merchant processes the order of the customer until all requirements for capture are fulfilled and sends the information via the Create Webshop Order API
  6. The Accounting as a Service accounting module takes care of capturing the money incl. exception handling and reconciliation Note: If your business model requires that you initiate the capture e.g. before unlocking a service we offer this option as well
  7. Additionally, status information can be provided via different Notifications

Authorize with immediate capture

When executing authorization and capture in 1 step, the following sequence of steps takes place:

  1. (Prerequisite) During checkout, customer selects a 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 authorization with direct capture based on the received payment token.
  4. Accounting as a Service handles the payment authorization request followed by the direct capture. Using notifications, Accounting as a Service will trigger an event about the status change of the related payment transaction.
  5. Merchant processes the order of the customer until all requirements for capture are fulfilled and sends the information via the Create Webshop Order API
  6. Additionally, status information can be provided via different Notifications

How to implement

Authorize a transaction without capturing

To authorize a transaction, make a POST /payments/{version}/authorize request. Beside other information, you will have to provide the payment token to indicate the related payment instrument.

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

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

{
    "returnURL": "https://www.my-shop.com/return?id=12343",
    "countryCode": "DE",
    "paymentInstrument": {
        "id": "a36c4b6b-f880-4e07-acb0-797b1449f0e3"
    },
   "order":{
        "totalGrossAmount": 119.00,
        "currency": "EUR",
        "totalNetAmount": 100.00,
        "items": [
            {
                "quantity": 1,
                "grossUnitPrice": 119,
                "description": "test Description",
                "netUnitPrice": 100,
                "productID": "A0",
                "vatAmount": 19,
                "vatPercent": 19
            }
        ],
        "orderReference": "O-20210802144731",
        "orderChannel": "INTERNET",
        "deliveryType": "NORMAL",
        "shipToAddress": {
            "street": "Gartenstraße",
            "streetNumber": "2",
            "streetNumberAdditional": "",
            "postalCode": "33333",
            "postalPlace": "Gütersloh",
            "countryCode": "DE",
            "addressType": "string",
            "careOf": ""
        }
    }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentTransaction": {
    "token": "275494",
    "status": "Authorized",
    "links": [],
    "errorInfo": null
  }
}

Capture

IMPORTANT NOTE: Following the default setup and configuration of the payment module, this endpoint is NOT needed to be called by your system as the capture operation is normally handled internally when working with our accounting module. Please consider to use this call only if your business model requires a capture out of your system.

To execute a capture on a previously authorized transaction, make a POST /payments/{version}/transactions/{paymentTransactionToken}/capture request, where {paymentTransactionToken} is the unique identifier of the transaction (i.e. the transaction token) as it has been returned as part of the response from the request to authorize.

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

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

{
    "order": {
        "totalGrossAmount": 119,
        "currency": "EUR",
        "orderReference": "O-20210802144731"
    }

}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentTransaction": {
    "token": "275494",
    "status": "Captured",
    "errorInfo": null
  },
  "captureId": "O-20210802144723"
}

Authorize with immediate capture

To execute an authorize operation with immediate capture, make a POST /payments/{version}/authorize request. Beside other information, you will have to provide the payment token to indicate the related payment instrument. Also, in comparison to the authorization without immediate capture, you will have to set the optional property directCapture to true.

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

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

{
    "returnURL": "https://www.my-shop.com/return?id=12343",
    "countryCode": "DE",
    "directCapture": true,
    "paymentInstrument": {
        "id": "a36c4b6b-f880-4e07-acb0-797b1449f0e3"
    },
   "order":{
        "totalGrossAmount": 119.00,
        "currency": "EUR",
        "totalNetAmount": 100.00,
        "items": [
            {
                "quantity": 1,
                "grossUnitPrice": 119,
                "description": "test Description",
                "netUnitPrice": 100,
                "productID": "A0",
                "vatAmount": 19,
                "vatPercent": 19
            }
        ],
        "orderReference": "O-20210802144731",
        "orderChannel": "INTERNET",
        "deliveryType": "NORMAL",
        "shipToAddress": {
            "street": "Gartenstraße",
            "streetNumber": "2",
            "streetNumberAdditional": "",
            "postalCode": "33333",
            "postalPlace": "Gütersloh",
            "countryCode": "DE",
            "addressType": "string",
            "careOf": ""
        }
    }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentTransaction": {
    "token": "275494",
    "status": "Captured",
    "errorInfo": null
  },
  "captureId": "O-20210802144723"
}

Get transaction details (optional call)

To get detailed information for a specific payment transacation, make a GET /payments/{version}/transactions/{paymentTransactionToken} request, where {paymentTransactionToken} is the unique identifier of the transaction (i.e. the transaction token) as it has been returned as part of the response from the request to authorize.

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

Sample request
GET /payments/v1/transactions/275494 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

{
  "paymentTransaction": {
    "token": "276675",
    "status": "Authorized",
    "totalCapturedAmount": 0.0,
    "totalRefundedAmount": 0.0,
    "miscPspSpecificDetails": {
      "pspOrderId": "O-20210904093225"
    },
    "links": [],
    "errorInfo": null
  },
  "paymentInstrument": {
    "id": "e7a04b38-fc96-4cca-9f37-295b8b8b7a60",
    "paymentMethodName": "MasterCard",
    "details": {
      "last4Digits": "1096",
      "expirationMonth": 9,
      "expirationYear": 2023,
      "cardHolder": "John Doe"
    }
  },
  "order": {
    "totalGrossAmount": 119,
    "currency": "EUR",
    "items": [
        {
            "quantity": 1,
            "grossUnitPrice": 119,
            "description": "test Description",
            "netUnitPrice": 100,
            "productID": "A0",
            "vatAmount": 19,
            "vatPercent": 19
       }
    ]
  }
}

See also