Direct integration - Create Order

The "Create Order" interface is the starting point for processing transactions in the Accounting as a Service platform. This API allows businesses to submit order data, which is then used as the basis for invoicing, capturing payments, and matching incoming payments. It's applicable across various scenarios, such as web shop orders, point-of-sale transactions, and subscription orders.

Standard Orders

Suitable for regular purchases of physical goods. The order data includes details like customer information, product items, shipping, and billing details. This data is saved in Accounting as a Service and will be the reference for all subsequent processes (create invoice, cancel order, return order, add goodwill)

Key Points: Ensure all mandatory fields are completed as per the API-Explorer definition.

General Workflow

1. Data Collection: Gather order details, including customer information, item specifics, and any applicable discounts or fees.
2. Validation: Cross-check the data against the API-Explorer's mandatory fields and validation rules.
3. Request Submission: Send the prepared data in a POST request to the order creation endpoint.
4. Confirmation: Await the Qualitative Response notification to confirm successful processing. Only upon receiving a status of "OK" should further steps, such as invoicing or order returns, be initiated.
5. Error Handling: If errors occur, review the validation and resend with the same transactionID if neccessary.

Response handling

Make sure you received feedback to the request validation via Qualitative Response notification. Errors related to validation or processing are returned with descriptive messages to facilitate troubleshooting.If the order could be processed without errors, a confirmation will be sent. It is important that the order has been processed correctly, or the subsequent processes will end up in errors as well.

Use Cases in create order interface

The following use cases are samples of how to use the create order interface

Orders with Shipments

Shipments are a critical component of order management, which means, various shipping options such as standard delivery, express delivery, and free shipping have to be supported. Each shipment type is represented as a line item in the order with distinct positionType values.

Shipment Types

• Standard Delivery: Represents regular shipping methods like ground or standard postal services.
• Express Delivery: For expedited or priority shipping options.
• Free Delivery: Use this if you do not want to charge the client for the shipment.

Implementation:

Shipment details are represented as line items in the order with the positionType set to SHIPPING_COSTS (standard delivery) or SHIPPING_COSTS_EXPRESS (express delivery). If you want to provide a free delivery, provide the line item with a grossUnitPrice and vatAmount of 0.00. Each shipment line must include information such as costs, VAT-information, and a description.

Sample request (Standard Delivery)

{
  "items": [
    {"description": "Set van drie slips",
      "grossUnitPrice": 25.99,
      "quantity": 1,
      "vatAmount": 4.51,
      "vatPercent": 21.0,
      "orderItemReference": 1,
      "positionType": "SALES_ARTICLE",
      "productId": "95848610040",
      "vatType": "NORMAL"
    },
    {"description": "Standard Delivery",
      "grossUnitPrice": 4.90,
      "quantity": 1,
      "vatAmount": 0.85,
      "vatPercent": 21.0,
      "orderItemReference": 2,
      "positionType": "SHIPPING_COSTS",
      "productId": "standard-delivery-2",
      "vatType": "NORMAL"
    }
  ]
}

Sample request (Express Delivery)

{
  "items": [
    {"description": "Set van drie slips",
      "grossUnitPrice": 25.99,
      "quantity": 1,
      "vatAmount": 4.51,
      "vatPercent": 21.0,
      "orderItemReference": 1,
      "positionType": "SALES_ARTICLE",
      "productId": "95848610040",
      "vatType": "NORMAL"
    },
    {"description": "Express Delivery",
      "grossUnitPrice": 4.90,
      "quantity": 1,
      "vatAmount": 0.85,
      "vatPercent": 21.0,
      "orderItemReference": 2,
      "positionType": "SHIPPING_COSTS_EXPRESS",
      "productId": "express-delivery",
      "vatType": "NORMAL"
    }
  ]
}

Sample request (Free Delivery)

{
  "items": [
    {"description": "Set van drie slips",
      "grossUnitPrice": 25.99,
      "quantity": 1,
      "vatAmount": 4.51,
      "vatPercent": 21.0,
      "orderItemReference": 1,
      "positionType": "SALES_ARTICLE",
      "productId": "95848610040",
      "vatType": "NORMAL"
    },
    {"description": "Free Delivery",
      "grossUnitPrice": 0.00,
      "quantity": 1,
      "vatAmount": 0.00,
      "vatPercent": 0.0,
      "orderItemReference": 2,
      "positionType": "SHIPPING_COSTS",
      "productId": "free-delivery",
      "vatType": "TAXLESS"
    }
  ]
}

Orders with Taxes

Taxes are an essential part of the financial processing in any order to ensure compliance with local tax regulations. When creating an order, you have to specify the correct tax details for each line item, as different goods or services may have varying tax rates. There are several tax types you need to account for, including:

• NORMAL: The standard tax rate applied to most products and services.
• REDUCED: A lower tax rate applied to specific items (e.g., essentials).
• TAXLESS: For items that are exempt from taxes.
• REVERSE: Reverse charge mechanism where the customer handles the tax reporting.

Even in countries where multiple reduced tax rates exist, you still need to label all reduced taxes under the REDUCED tax type, specifying the correct percentage.

Implementation:

You have to provide tax information for each line item within an order. This includes the following fields:

• taxType: The applicable tax category for the line item. The valid options are:
  • TAXLESS: No tax applied.
  • NORMAL: Standard tax rate.
  • REDUCED: Reduced tax rate.
  • REVERSE: Reverse charge mechanism, where tax responsibility shifts to the buyer.
• vatPercent: The applicable percentage for the given tax type. This percentage determines the tax rate that is applied to the line item.
• vatAmount: The total calculated tax for that line item. You must calculate this value by applying the tax percentage to the gross total of the line item.

You have to ensure that each line item has the correct vatAmount, vatPercent, and taxType to guarantee that the correct tax codes are used in Accounting as a Service for booking.

Please let us know when you want to provide a new value in vatPercent so that we can make sure this is set up in the system.

Sample

"items": [
    {
        "grossUnitPrice": 20.00,
        "orderItemReference": 1,
        "quantity": 4.0,
        "vatAmount": 3.47,
        "vatPercent": 21,
        "vatType": "NORMAL"
    }
]

Orders with Discounts

Discounts reduce the order value and are represented as separate line items in the order. Discounts can apply to specific items or the entire order, with their values always provided as negative amounts. The discount’s positionType and tax settings depend on the product category it reduces.

• Order-Level and Line-Item Discounts:
  • Discounts are handled as line items with positionType set to DISCOUNT.
  • Line-item discounts can be associated with specific products by creating multiple entries if needed.

Implementation:

Discounts are provided with a negative grossUnitPrice and vatAmount and the appropriate positionType such as DISCOUNT for regular discounts or DISCOUNT_FOR_SUBSCRIPTION_ORDER for subscription-related discounts.

Please note: In the create Invoice call, you will have to provide the positions that you want to invoice (or that have been invoiced). You need to differentiate the discounts already in the create order.

Sample

"items": [
    {"description": "Shirt",
    "grossUnitPrice": 25.95,
    "quantity": 1,
    "vatAmount": 4.14,
    "vatPercent": 19,
    "orderItemReference": 1,
    "positionType": "SALES_ARTICLE",
    "productId": "146888",
    "vatType": "NORMAL"
    },
    {"description": "10% Discount on shirts",
    "grossUnitPrice": -2.60,
    "quantity": 1,
    "vatAmount": -0.42,
    "vatPercent": 19, 
    "orderItemReference": 2, 
    "positionType": "DISCOUNT", 
    "productId": "1004",
    "vatType": "NORMAL"
    }
]

Orders with Service Fees

Service fees cover additional costs such as handling, setup, or processing fees. They are represented as separate line items in the order, similar to shipment costs (e.g. gift-wrapping, consulting, product personalization)

Implementation:

Include service fees as line items with positionType set to SERVICE_CHARGE. Each fee should have appropriate details for description, pricing, and VAT.

Sample

"items":[
    {"productId":"327831",
    "description":"Monopoly Junior",
    "orderItemReference":1,
    "positionType":"SALES_ARTICLE",
    "quantity":1,
    "grossUnitPrice":113.00,
    "vatType":"NORMAL",
    "vatPercent":21,
    "vatAmount":19.61
    },
    {"productId":"099990",
    "description":"Gift wrapping",
    "orderItemReference":2,
    "positionType":"SERVICE_CHARGE",
    "quantity":1,
    "grossUnitPrice":10.00,
    "vatType":"NORMAL",
    "vatPercent":21,
    "vatAmount":1.74
    }
    ]

Selling Giftcards

If you want to offer Giftcards for sale in your webshop, which can be used to pay an order later on, these have to be reflected in your accounting as well.

Implementation

Gift Card Sales: Provide the order position with the positionType GIFT_CARD_VOUCHER_SALE. The vatType needs to be TAXLESS.

Sample (GiftCard Sales)

"items": [
    {"productId": "009995",
    "description": "Gift Card Sale No. 1234543",
    "orderItemReference": 1, 
    "positionType": "GIFT_CARD_VOUCHER_SALE", 
    "quantity": 1, 
    "grossUnitPrice": 50.00, 
    "vatType": "TAXLESS", 
    "vatPercent": 0,
    "vatAmount": 0.00, 
    "reportingPositionData": 
        {"giftCardVoucherId": "298uwfj88"}
    }
]

Orders paid by Giftcards

Gift Cards can be used as a payment method within an order or sold as an item. When used as a payment method, we have to differentiate between partial payments and full payments via Gift Card.

Implementation:

• Gift Card Payments:
  • Partial Gift Card Payment: Provide the order position with the positionType GIFT_CARD_VOUCHER_PAYMENT. The vatType needs to be TAXLESS. You can provide the used gift card ID in the reportingPositionData on line item level in the field giftCardVoucherId.
  • Full Gift Card Payment: Provide the giftcard as an order position as described for partial gift card payments. As the total of the order is 0 in this case, you have to use the paymentMethodName : OpenInvoice.

If you have multiple gift cards, please provide each gift card as a separate line item

Sample (Gift card partial payment):

"items": [
    {"productId": "328831",
    "description": "Shirt long-sleeve", 
    "orderItemReference": 1, 
    "positionType": "SALES_ARTICLE", 
    "quantity": 1, 
    "grossUnitPrice": 113.00,
    "vatType": "NORMAL", 
    "vatPercent": 21,
    "vatAmount": 19.61
    },
    {"productId": "009997", 
    "description": "Gift Card No. 1234543", 
    "orderItemReference": 2,
    "positionType": "GIFT_CARD_VOUCHER_PAYMENT", 
    "quantity": 1, 
    "grossUnitPrice": -50.00, 
    "vatType": "TAXLESS", 
    "vatPercent": 0, 
    "vatAmount": 0.00, 
    "reportingPositionData": 
        {"giftCardVoucherId": "298uwfj88"}
    }
]

Sample (Gift card full payment)

"items": [
    {"productId": "328831",
    "description": "Shirt long-sleeve", 
    "orderItemReference": 1, 
    "positionType": "SALES_ARTICLE", 
    "quantity": 1, 
    "grossUnitPrice": 113.00,
    "vatType": "NORMAL", 
    "vatPercent": 21,
    "vatAmount": 19.61
    },
    {"productId": "009997", 
    "description": "Gift Card No. 1234543", 
    "orderItemReference": 2,
    "positionType": "GIFT_CARD_VOUCHER_PAYMENT", 
    "quantity": 1, 
    "grossUnitPrice": -50.00, 
    "vatType": "TAXLESS", 
    "vatPercent": 0, 
    "vatAmount": 0.00, 
    "reportingPositionData": 
        {"giftCardVoucherId": "298uwfj88"}
    }
]
"paymentReference": {
        "paymentMethodName": "OpenInvoice"
    },

Orders with loyalty card payments

Loyalty Cards can be used as a payment method within an order. It can either be used as a partial payment (e.g. number of points are used to reduce the overall cart-value) or as full payment (e.g. number of points have a higher value than the cart value).

Implementation

• Partial Loyalty Card Payment: Provide the order position with the positionType : LOYALTY_CARD. The vatType needs to be TAXLESS.
• Full Loyalty Card Payment: Set the paymentMethodName : LoyaltyCard within paymentReference. A separate order item is not needed. For more information look in the payment section Loyalty and Gift Card (full payment)

Sample (Loyalty card - partial payment)

"items": [
    {"productId": "328831",
    "description": "Shirt long-sleeve", 
    "orderItemReference": 1, 
    "positionType": "SALES_ARTICLE", 
    "quantity": 1, 
    "grossUnitPrice": 113.00,
    "vatType": "NORMAL", 
    "vatPercent": 21,
    "vatAmount": 19.61
    },
    {"productId": "009997", 
    "description": "Loyalty Card No. 33234543", 
    "orderItemReference": 2,
    "positionType": "LOYALTY_CARD", 
    "quantity": 1, 
    "grossUnitPrice": -10.00, 
    "vatType": "TAXLESS", 
    "vatPercent": 0, 
    "vatAmount": 0.00
    }
]

Sample (Loyalty Card - full payment)

"paymentReference": {
  "paymentMethodName": "LoyaltyCard"
}

Order for subscriptions

Handles recurring charges for subscription-based products. This accounts for oders, where the subscription and billing is managed in your systems. In case you are using the Accounting as a Service Billing and Subscription Service, you will need to use different requests.

Implementation:

• Set positionType : SUBSCRIPTION_ORDER
• Provide Contract Information: In the contract section, you have to provide additional information about the subscription
  • basicCaharge - provide a value if a basic charge needs to be applied
  • contractID- the contract ID of the subscription
  • customerContractStartDate - Start date of the subscription
  • customerContractEndDate - End date of the subscription (e.g. if this subscription is a yearly subscription, the contract end date is in the future
  • description - name of the subscription contract
  • minimumTerm - run time of the contract
• Information on line item level:
  • Set the positionType: SUBSCRIPTION_ORDER
  • Include subscription details with additional information like startDate and endDate. This will define the revenue recognition in the accounting.

If you want to add a discount to the subscription, you have to add the discount as a separate line item with the positionType: DISCOUNT_FOR_SUBSCRIPTION_ORDER. In this case the subscription- section also has to be provided with startDate and endDate so that the revenue recognition works.

Sample (Subscription - w/o discount)

{
    ...
    "contract": {
        "basicCharge": 12,
        "contractID": "A545axe58",
        "customerContractEndDate": "2016-01-09T00:00:00.0000000",
        "customerContractStartDate": "2015-12-10T00:00:00.0000000",
        "description": "10 month contract",
        "endDate": "2019-03-15T00:00:00.0000000",
        "minimumTerm": 3,
        "startDate": "2018-12-05T00:00:00.0000000"
    },
   ...
    "items": [
        {
            "grossUnitPrice": 119.00,
            "orderItemReference": 1,
            "quantity": 1,
            "vatAmount": 19,
            "vatPercent": 19,
            "vatType": "NORMAL",
            "productId": "BEF12346512AAA",
            "description": "Monthly download volume (Package M)",
            "positionType": "SUBSCRIPTION_ORDER",
            "subscription": {
                "endDate": "2019-03-15T00:00:00.0000000",
                "startDate": "2018-12-05T00:00:00.0000000"
            }
        }
    ],
    ...
}

Sample (Subscription w/ discount)

{
    ...
    "contract": {
        "basicCharge": 12,
        "contractID": "A545axe58",
        "customerContractEndDate": "2016-01-09T00:00:00.0000000",
        "customerContractStartDate": "2015-12-10T00:00:00.0000000",
        "description": "10 month contract",
        "endDate": "2019-03-15T00:00:00.0000000",
        "minimumTerm": 3,
        "startDate": "2018-12-05T00:00:00.0000000"
    },
   ...
    "items": [
        {
            "grossUnitPrice": 119.00,
            "orderItemReference": 1,
            "quantity": 1,
            "vatAmount": 19,
            "vatPercent": 19,
            "vatType": "NORMAL",
            "productId": "BEF12346512AAA",
            "description": "Monthly download volume (Package M)",
            "positionType": "SUBSCRIPTION_ORDER",
            "subscription": {
                "endDate": "2019-03-15T00:00:00.0000000",
                "startDate": "2018-12-05T00:00:00.0000000"
            }
        },
         {
            "grossUnitPrice": -11.90,
            "orderItemReference": 2,
            "quantity": 1,
            "vatAmount": -1-90,
            "vatPercent": 19,
            "vatType": "NORMAL",
            "productId": "DISCO334",
            "description": "Welcome discount (10%)",
            "positionType": "SUBSCRIPTION_ORDER",
            "subscription": {
                "endDate": "2019-03-15T00:00:00.0000000",
                "startDate": "2018-12-05T00:00:00.0000000"
            }
        }
    ],
    ...
}

Order for B2B customers

B2B orders cater to business customers, often involving special tax treatments and company addresses. These orders require additional fields such as businessScenario and specific companyAddress information.

Implementation:

• Set BusinessScenario : B2B
• Replace billToAddress with a companyAddress with company related fields

Reverse Charg: Set vatType : reverseCharge to indicate that the reverse charge mechanism needs to be applied on position level.

Sample (B2B order)

{
"BusinessScenario": "B2B",
"companyAddress": {
    "companyName": "Riverty Administration Services GmbH",
    "street": "Chöltenweg",
    "streetNumber": "35",
    "CareOf": "David Schophaus",
    "PostCode": "48155",
    "City": "Münster",
    "countryCode": "DE",
    "language": "de",
    "email": "contactus@riverty.com",
    "taxIdentificationNumber": ""
},
...
}

Sample (reverse Charge line items)

"items": [
   {"description": "boxer shorts", 
   "grossUnitPrice": 25.99, 
   "quantity": 1, 
   "vatAmount": 4.15, 
   "vatPercent": 19.0, 
   "orderItemReference": 1, 
   "positionType": "SALES_ARTICLE",
   "productId": "933610040",
   "vatType": "ReverseCharge"
   }
]

orders with only digital distribution

Digital orders cover the sale of non-physical products like e-books, software, or services. These orders typically require no shipping details.

Implementation:

• Set orderType : DIGITAL_GOODS.
• No shipping address is required unless mixed with physical goods.

Sample for digital orders

{
  "currency": "EUR",
  "orderChannel": "ECOM",
  "orderDate": "2024-09-09",
  "orderReference": "ORD9620035708",
  "orderType": "DIGITAL_GOODS",
  "supplyingCountry": "NL",
  "vatDeclarationCountry": "NL",
  "processAfterDunning": "HAND_OVER_FOR_DEBT_COLLECTION",
  "billToAddress": {
      "countryCode": "NL",
      "lastName": "Doe",
      "firstName": "John",
      "language": "nl",
      "postalCode": "1111 AW",
      "postalPlace": "Amsterdam",
      "salutation": "Mr",
      "street": "Street",
      "streetNumber": "1",
      "email": "contact.us@riverty.com"
  },
  "items": [
      {"description": "white Rose", 
      "grossUnitPrice": 25.99,
      "quantity": 1, 
      "vatAmount": 4.51,
      "vatPercent": 21.0,
      "orderItemReference": 1, 
      "positionType": "SALES_ARTICLE",
      "productId": "95848990040", 
      "vatType": "NORMAL"
      },
  ],
  "paymentReference": {
      "paymentMethodName": "Ideal",
      "paymentDetails": {
          "authorizationDate": "2024-09-09T14:17:37Z",
          "authorizedAmount": 30.89,
          "merchantAccountId": "FAS_NL_Adyen",
          "settlementReference": "PUC_NL#df24a54a-010d-4720-95a4-afb35a98db9c",
          "externalPaymentToken": "DLSPWKBNPGLF6975"
      }
  },
}

Payment specific data

Accounting as a Service allows many different payment methods. To process the payment on Riverty side, some additional information has to be provided for some of these payment methods. This is independent from the PSP used.
If the payment is captured already before sent to Accounting as a Service AND the refund is done by you, , the information is not needed.
If the payment (capture OR refund) is processed by Riverty, the information is mandatory.

the following information may be requred (will be specified by payment method) in the paymentReference - section:

• authorizedAmount: Value that has been authorized or captured in the order process
• merchantAccountId: AccountId at the PSP, that we can refer to in the communication to direct the capture/refund call to the correct instance at the PSP
• settlementReference: information that we will find in the settlement file. We will match the payment in the settlement file with this information. This will be defined with the authorization
• externalPaymentToken: token generated by the PSP and communicated in the authorization or capture call, that will be used in the communication with the PSP. It will identify the payment details on PSP side.

Sample

"paymentReference": {
    "paymentMethodName": "Blik",
    "paymentDetails": {
        "authorizationDate": "2024-08-16T10:19:07Z",
        "authorizedAmount": 139.89,
        "merchantAccountId": "PSP1-DE",
        "settlementReference": "85063298-5355-4d17-99d3-12b3dfd68b31",
        "externalPaymentToken": "L8CFMTRP7CRW24V5"
    }
}

Paying with online and wallet payments

Online payment methods allow making and accepting payments without the need to share financial details, offering extra security for online transactions. Wallet payment methods are digital payment methods offered by specific providers, such as AmazonPay, which allow customers to use stored payment methods from their accounts to pay for goods and services.

Implementation:

These payment methods are usually handled through a Payment Service Provider (PSP) like Stripe or Adyen, or integrated directly as a checkout payment method and are usually captured directly in the process. To implement these, you have to provide specific details such as authorizedAmount, merchantAccountId, settlementReference, and externalPaymentToken.

The following paymentMethodNames are possible:

• AmazonPay
• Bancontact
• Blik
• BlikCodeOnly
• Eps
• Giropay
• Ideal
• Multibanco
• PayPal
• PayPalExpressCheckout
• PayU
• Przelewy24
• Trustly

Sample:

"paymentReference": {
    "paymentMethodName": "Blik",
    "paymentDetails": {
        "authorizationDate": "2024-08-16T10:19:07Z",
        "authorizedAmount": 139.89,
        "merchantAccountId": "PSP1-DE",
        "settlementReference": "85063298-5355-4d17-99d3-12b3dfd68b31",
        "externalPaymentToken": "L8CFMTRP7CRW24V5"
    }
}

Paying with a Credit-/DebitCard

Card payments involve using a credit/debit card to make purchases. CardPayments are usually provided through aquirer or PSPs to hold the Credit Card data secured and PCI compliant.

Implementation:

Card payments, including special cases like ApplePay and GooglePay, require the PSP or Aquirer specific details such as authorizedAmount, merchantAccountId, settlementReference, and externalPaymentToken.

The following paymentMethodNames are possible:

• AmericanExpress
• DinersClub
• Discover
• MasterCard
• Visa
• special cases (ApplePay/GooglePay)
  • ApplePayExpressCheckout
  • GooglePay

Sample

"paymentReference": {
    "paymentMethodName": "Visa",
    "paymentDetails": {
        "authorizedAmount": 42.94,
        "authorizationDate": "2024-09-12T10:32:25.495Z",
        "settlementReference": "ORDNL-8100249069",
        "externalPaymentToken": "CGWT9RC9XB5FX875",
        "merchantAccountId": "PSP1-DE"
    }
}

Paying with cas on delivery

Cash on Delivery (COD) allows customers to pay for their purchases at the time of delivery. This is common in e-commerce, where payment is made directly to the carrier upon receipt of goods.

Implementation:

For COD, specify the carrier and optionally include customer bank details for potential refunds (this information can also be provided, when the refund is requested). Payment reconciliation depends on how the carrier processes payments:

• individually by order ID
• in weekly payment runs (separate file needs to be provided with the single transactions)

set paymentMethodName : CashOnDelivery

Supported carrier:

• DHL
• DPD
• Hermes
• General Logistics Systems
• Bartolini
• Poste Italiane

Sample

"paymentReference": {
    "paymentMethodName": "CashOnDelivery"
},
"carrier": "DPD"

Special Case:

If you want to provide the IBAN of the consumer with the order so that a refund may take place, you can provide this directly in the paymentReference - section:

"paymentReference": {
    "paymentMethodName": "CashOnDelivery",
    "paymentDetails": {
        "iban": "DE436345345344742",
        "accountOwner": "John Doe",
        "bic": "BOFIIE2DXXX"
    }
},
"carrier": "DPD"

Paying with direct debit

Direct Debit allows companies to withdraw funds directly from a customer's bank account, typically used for recurring payments like subscriptions or bills. Only available in SEPA countries.

Implementation:

Provide the accountOwner name, IBAN, and a mandateReference together with the ``àuthorizedAmount``` for the direct debit setup. The mandate reference is crucial for processing payments through the bank. You need to make sure that with Direct Debit the Bank provides the CAMT.054 (for single Direct Debit transactions) and the CAMT.053 (for the sum). Accounting as a Service will provide the requested direct debits in a pain.008 file.

set paymentMethodName : ArvatoDirectDebitSepa

Sample:

"paymentReference": {
    "paymentMethodName": "ArvatoDirectDebitSepa",
    "paymentDetails": {
        "accountOwner": "John Doe",
        "iban": "DE02370502990000689912",
        "mandateReference": "400000805123",
        "authorizedAmount": 595
    }
}

End-Consumer initiates payment

Open Invoice allows customers to buy now and pay later, while Pre-payment requires payment before order shipment. This may be used for tailor-made-products or individualized items, high-value items, or for individual services like classes or appointments.

Implementation:

For Pre-payment, you must subscribe to payment received notifications and set up a cancellation process if no payment is received within a set timeframe (Use NO_PAYMENT as cancellationReason in the cancel order request.

For Open Invoice, a dunning process should be established.

possible paymentMethodName:

• ``ÒpenInvoice```
• PrePayment

Sample

"paymentReference": {
    "paymentMethodName": "OpenInvoice"
}

Using omnichannel payments

Omnichannel payments provide flexibility by allowing customers to pay through different channels, seamlessly integrating online and in-store experiences. There are three distinct methods within this category:

• InStorePrepayment: This method involves the customer paying for a product or service in a physical store before receiving it. It's often used for customized or high-value items where payment is required upfront. This method minimizes the risk for the seller as the payment is secured before the order is fulfilled.
• InStoreOpenInvoice: With this method, customers receive goods or services from a physical store before making a payment. An invoice is provided with the goods, allowing the customer to pay at a later date, typically by going to the store. This is commonly used for trusted customers who frequently visit the store and prefer paying in the stores.
• InStorePickup: This payment method allows customers to order and pay for products online and then pick them up at a physical store location. Known as "Buy Online, Pick up in Store" (BOPIS), this method merges online convenience with the immediate availability of in-store shopping. Payment is completed online, so the pickup process is typically quick and efficient.

Impelmentation:

There is no specific detail needed.

possible paymentMethodName:

• InStoreOpenInvoice
• InStorePickup
• InStorePrepayment

Sample

"paymentReference": {
    "paymentMethodName": "InStorePickup"
}

Using a collecting partner

Collected payments are managed by third-party providers who collect payments on their own account, handling all aspects of payment processing, including authorization, capture, and settlement. This method includes options like RivertyPay and Klarna, which offer various payment terms such as immediate direct debit, installments, or delayed payments. As the providers usually take over the risk of failing transactions, they often perform credit checks to assess customer reliability and take responsibility for collection efforts in case of payment default, minimizing the financial risk for the seller.

The following options are supported (with different names):

• Installment: End-customer can pay in multiple installments
• Direct Debit: the provider withdraws the amount from the end-customers account
• Open Invoice: the provider receives the money from the end-customer

In any case, the provider transfers the full amount (usually including a fee for the transaction) to your bank account.

Implementation:

You have to provide specific details such as authorizedAmount, merchantAccountId, settlementReference, and externalPaymentToken.

possible paymentMethodName:

• AfterPayDirectDebit
• AfterPayInstallmentsDirectDebit
• AfterPayInstallmentsOpenInvoice
• AfterPayOpenInvoice
• KlarnaDirectDebit
• KlarnaPayLater
• KlarnaPayOverTime

Sample

"paymentReference": {
    "paymentMethodName": "AfterPayDirectDebit",
    "paymentDetails": {
        "authorizedAmount": 42.94,
        "authorizationDate": "2024-09-12T10:32:25.495Z",
        "settlementReference": "ORDNL-8100249069",
        "externalPaymentToken": "CGWT9RC9XB5FX875",
        "merchantAccountId": "PSP1-DE"
    }
}

Paying via App-Stores

In-App Payments allow customers to make purchases directly within mobile apps or digital platforms, such as Amazon, iTunes, or Google Play. These payments are typically processed through secure, platform-specific systems that conceal the underlying payment method, providing a seamless user experience. For businesses, these payments are easy to manage since the app provider handles the payment process and ensures that funds are collected, eliminating the need for complex integration or reconciliation efforts.

Implementation:

There is no specific detail needed.

possible paymentMethodName:

• InAppAmazon
• InAppApple
• InAppGoogle

Sample

"paymentReference": {
    "paymentMethodName": "InAppGoogle"
}

Provide generic information per order

Accounting as a Service allows up to 5 additional fields that can be added for each order and in addition for each order item. This information can be used for reporting purposes on your side. Please use the fields genericField... to be found under reportingPositionData.

Sample:

"reportingPositionData": {
        "genericField1": "Some value A",
        "genericField2": "Some value B",
        "genericField3": "Some value C",
        "genericField4": "Some value D",
        "genericField5": "Some value E",
}