Riverty Payment: Technical Details

Technical details of Riverty for OXID eShop 7 - checkout/redirect flow, order management flow, module structure and chain extending.

Deutsche Version

Back to overview

Riverty Payment: Technical Details

Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net

Overview

Property	Value
Composer package	`mmd/oxid7-riverty`
Module ID	`mmd_riverty`
Namespace	`Mmd\Riverty`
API	Riverty BNPL API v3 (`/api/v3/...`): `checkout/authorize`, `checkout/payment-methods`, `orders/{nr}`, `orders/{nr}/captures`, `orders/{nr}/voids`, `orders/{nr}/refunds`, `version`
Payment type in authorize	Invoice and direct debit send `Invoice` (direct debit additionally `directDebit.available`), instalments and Pay in 3 send `PartPayment`
HTTP client	Guzzle

Flow 1: Checkout and redirect

graph TD
    A["Customer selects Riverty payment method"] --> B["Build authorize request"]
    B --> C["RivertyClient: authorize()"]
    C --> D{"Outcome?"}
    D -->|Accepted| K["OXID order finalization proceeds"]
    D -->|Pending| E["Save basket in session, redirect to Riverty"]
    D -->|Rejected| F["Error message, back to payment selection"]
    E --> G["Customer confirms at Riverty"]
    G --> H["Return controller mmd_riverty_return"]
    H --> I["Verify signature or order lookup"]
    I -->|Accepted| J["Restore basket, complete order"]
    I -->|Rejected or error| F
    J --> K
    K --> L["Thank-you page with Riverty info box"]

Depending on the return, the return step either verifies the signature (parameters ordernumber, orderstatus, signature, checked with the country's API key) or queries the order status via lookup. If the lookup fails, the payment is rejected to be safe.

Flow 2: Order management (admin or Integration API)

graph TD
    A["Admin action or Integration API request"] --> B{"Origin?"}
    B -->|Integration API| C["Secret auth and idempotency check"]
    B -->|Admin tab| D["Execute order action"]
    C --> E["Calculate remaining quantities"]
    D --> E
    E --> F["Call Riverty API"]
    F --> G["Update transaction status"]
    G --> H["Post-capture or post-void actions depending on the action"]
    F --> L["Log API call"]

Controllers

Class / `cl`	Purpose
`mmd_riverty_return`	Return from Riverty, verification and order completion
`mmd_riverty_order`	Riverty tab in the order view (capture, void, refund)
`mmd_riverty_api_log`, `mmd_riverty_api_log_list`, `mmd_riverty_api_log_detail`	API log in the admin
`mmd_riverty_integration_api`	External Integration API

Database tables

Table	Purpose
`mmd_riverty_transactions`	Transactions with status, amounts and item tracking
`mmd_riverty_api_logs`	Log of API calls
`mmd_riverty_idempotency_keys`	Idempotency keys of the Integration API

In addition, the payment method sync writes entries to oxpayments and oxobject2payment.

Module structure

src/
├── Core/              Activation events, tables
├── Controller/
│   ├── Admin/         Order tab, API log
│   └── Api/           Integration API
├── Api/
│   ├── Request/
│   └── Response/
├── Payment/           Payment type and status enums, PaymentHandler
├── Console/           oe:riverty:cleanup
├── Exception/
├── Config/            Configuration objects and factories
├── Service/
│   └── IntegrationApi/
├── Repository/
├── Model/
│   └── IntegrationApi/
└── Extension/
    ├── Controller/
    └── Model/

Chain extending

Class	Extends	Purpose
`OrderControllerExtension`	`OrderController`	Intervenes on order completion, starts the Riverty authorization and redirects to Riverty when needed
`PaymentControllerExtension`	`PaymentController`	Filters the payment list against the Riverty availability query, provides info box, identification number field and instalment example
`ThankYouControllerExtension`	`ThankYouController`	Provides the data for the Riverty info box on the thank-you page
`ModuleConfigurationExtension`	`Admin\ModuleConfiguration`	Form actions (`fnc`) on the settings page followed by a reload: generate secret, test API keys, fetch and sync payment methods
`ExtendedPaymentGateway`	`PaymentGateway`	Returns `true` for an already authorized Riverty payment so OXID does not discard the order
`OrderOverviewExtension`	`Admin\OrderOverview`	Hooks into `sendorder()`. The capture mode is fixed to manual, so the extension does not capture any payment