Quick Menu

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. (also see Request Submission)
  4. Confirmation: Await the EDI Error Sent 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 error handling documentation for resolution steps.

Request Submission

To create an order, make a POST request to:

/accounting/v1/businesses/{businessCode}/customers/{customerNumber}/orders
  • {businessCode}: Represents the legal entity (e.g., use "1000" in sandbox).
  • {customerNumber}: The end-customer’s unique identifier.

Request Body Structure

Below is an example of a complete request body for creating an order:

{
  "currency": "EUR",
  "orderChannel": "ECOM",
  "orderDate": "2024-09-09",
  "orderReference": "ORD9620035706",
  "orderType": "PHYSICAL_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"
  },
  "shipToAddress": {
      "countryCode": "NL",
      "firstName": "Jane",
      "lastName": "Doe",
      "language": "nl",
      "postalCode": "1111 AW",
      "postalPlace": "Amsterdam",
      "salutation": "Mrs",
      "street": "Street",
      "streetNumber": "1",
      "email": "contact.us@riverty.com"
  },
  "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.9,
      "quantity": 1, 
      "vatAmount": 0.85,
      "vatPercent": 21.0,
      "orderItemReference": 2,
      "positionType": "SHIPPING_COSTS",
      "productId": "standard-delivery-2", 
      "vatType": "NORMAL"
      }
  ],
  "paymentReference": {
      "paymentMethodName": "Ideal",
      "paymentDetails": {
          "authorizationDate": "2024-09-09T14:17:37Z",
          "authorizedAmount": 30.89,
          "merchantAccountId": "NL_Adyen",
          "settlementReference": "0d-4720-95a4-afb35a98db9c",
          "externalPaymentToken": "DLBPRKBNPGLF7970"
      }
  },
  "carrier": "DHL"
}

Response Handling

Make sure you received feedback to the request validation via EDI Error Sent 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. For more details: Error Handling section.

Use Cases for the create order interface

Shipments

Description

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.

Example 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"
    }
  ]
}

Example 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"
    }
  ]
}

Example 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"
    }
  ]
}

Taxes

Description:

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 vatPercentso that we can make sure this is set up in the system.

Example:

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

Discounts

Description:

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.

Example

"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"
    }
]

Service Fees

Description:

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.

Example:

"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
    }
    ]

Gift Cards

Description:

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 Sales: Provide the order position with the positionType GIFT_CARD_VOUCHER_SALE. The vatType needs to be TAXLESS.
  • Gift Card Payments:
    • Partial Gift Card Payment:Provide the order position with the positionType GIFT_CARD_VOUCHER_PAYMENT. The vatType needs to be TAXLESS.
    • Full Gift Card Payment:Set the paymentMethodName to Giftcard within paymentReference. A separate order item is not needed. For more information look in the payment section Loyalty and Gift Card (full payment)

Example (Gift Card 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"}
    }
]

Example (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"}
    }
]

Example (Full Payment):

Please look in the payment section Loyalty and Gift Card (full payment)

Loyalty Cards

Description:

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 to LoyaltyCard within paymentReference. A separate order item is not needed. For more information look in the payment section Loyalty and Gift Card (full payment)

Example (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
    }
]

Example (Full Payment):

Please look in the payment section Loyalty and Gift Card (full payment)

Subscription Orders

Description:

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 to SUBSCRIPTION_ORDER and include subscription details like startDate and endDate. Additional contract information is also required.

Example (contract)

"contract": {
    "basicCharge": 10.00,
    "contractID": "z18aykLldF",
    "customerContractEndDate": "2024-10-03",
    "customerContractStartDate": "2024-09-03",
    "description": "Monatsabo",
    "minimumTerm": 6
  },

Example (Order positions):

"items": [
    {"description": "Monthly Magazine Subscription",
    "grossUnitPrice": 15.00,
    "quantity": 1, "vatAmount": 2.85,
    "vatPercent": 19,
    "orderItemReference": 1,
    "positionType": "SUBSCRIPTION_ORDER", 
    "productId": "SUB123",
    "vatType": "NORMAL", 
    "subscription": {
        "endDate": "2024-10-03",
        "startDate": "2024-09-03"}
        },
    {"description": "Subscription Discount",
    "grossUnitPrice": -3.00,
    "quantity": 1,
    "vatAmount": -0.57,
    "vatPercent": 19, 
    "orderItemReference": 2, 
    "positionType": "DISCOUNT_FOR_SUBSCRIPTION_ORDER", 
    "productId": "SUB-DISC", 
    "vatType": "NORMAL", 
    "subscription": 
        {"endDate": "2024-10-03",
        "startDate": "2024-09-03"}
        }
]

B2B Orders

Description:

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.Designed for business-to-business transactions.

Implementation:

Add BusinessScenario as B2B and replace billing address with a company address.

  • Reverse Charge: For vatType, use reverseCharge to indicate that the reverse charge mechanism needs to be applied on position level.

Example (B2B order + Company Address):

"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": ""
},

Example (reverse Charge position):

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

Digital Orders

Description:

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 to DIGITAL_GOODS. No shipping address is required unless mixed with physical goods.

Example:

{
  "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

Online and wallet Payments

Description:

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: 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.

Example:

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

Supported Payment Methods:

Use the following as paymentMethodName

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

Card Payments

Description

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 information:

  • 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. ApplePay and GooglePay will be handled like credit cards.

Example:

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

Supported Payment Methods:

Use the following as paymentMethodName

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

Cash on Delivery

Description

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)

paymentMethodNamemust be CashOnDelivery

Example without bank details:

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

Example with bank details:

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

Supported Carriers:

Use the following as carrier

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

Direct Debit

Description

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 account owner's name, IBAN, and a mandate reference 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.

paymentMethodNamemust be ArvatoDirectDebitSepa

Example:

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

Loyalty and Gift Card (full payment)

Description

End-customers can fully pay an order using a loyalty- or a gift card.

Implementation:

The paymentMethodName must be Giftcard or LoyaltyCard. Please note: If only parts of the order is paid with a loyalty card or gift card, this reduction must be provided as a line item (see here).

Example:

"paymentReference": {"paymentMethodName": "Giftcard"}

Supported Payment Methods:

Use the following as paymentMethodName

  • Giftcard
  • LoyaltyCard

End-customer triggered payments

Description

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 timeframen (Use NO_PAYMENTas cancellationReason in the cancel order request. For Open Invoice, a dunning process should be established.

Example:

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

Supported Payment Methods:

Use the following as paymentMethodName

  • OpenInvoice
  • PrePayment

Omnichannel payments

Description

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.

Implementation:

There is no specific detail needed. You can provide the settlement-file as a file (format needs to be agreed) or you can use the [create payment]() request to provide the data.

Example:

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

Supported Payment Methods:

Use the following as paymentMethodName

  • InStoreOpenInvoice
  • InStorePickup
  • InStorePrepayment

Collected payments

Description

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 similar details as for other payment methods, including

  • 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.

Example:

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

Supported Payment Methods:

Use the following as paymentMethodName

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

InApp Payments

Description

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.

Example:

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

Supported Payment Methods:

Use the following as paymentMethodName

  • InAppAmazon
  • InAppApple
  • InAppGoogle