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:
When it comes to payment execution handling, there are 2 different options supported by Accounting as a Service.
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.
When executing a checkout authorization and capture in 2 steps, the following sequence of steps takes place:
When executing authorization and capture in 1 step, the following sequence of steps takes place:
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.
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": ""
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentTransaction": {
"token": "275494",
"status": "Authorized",
"links": [],
"errorInfo": null
}
}
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.
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"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentTransaction": {
"token": "275494",
"status": "Captured",
"errorInfo": null
},
"captureId": "O-20210802144723"
}
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.
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": ""
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentTransaction": {
"token": "275494",
"status": "Captured",
"errorInfo": null
},
"captureId": "O-20210802144723"
}
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.
GET /payments/v1/transactions/275494 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
{
"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
}
]
}
}