Riverty Payment: Integration API and Console Commands

Riverty for OXID eShop 7 - external REST integration API for capture/void/refund and the cron command for automatic data cleanup.

Deutsche Version

Back to overview

Riverty Payment: Integration API and Console Commands

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

Integration API (optional)

External endpoint for ERP/WMS/middleware systems to trigger capture, void and refund without using the OXID admin. The rules are the same as in the order's Riverty tab. Enabling the API and generating the secret is done in the admin (see Configuration). This section is the interface reference for the integration.

Endpoint: POST /index.php?cl=mmd_riverty_integration_api (the admin shows your shop's full URL next to the Integration API settings; call it over HTTPS only).

Auth: header X-Riverty-Integration-Secret with the secret generated in the admin (constant-time comparison). Failed authentications are written to the server error log. There is no rate limit, that belongs at the infrastructure layer (e.g. fail2ban or a WAF).

Request body (JSON):

{
  "type": "capture",
  "orderNumber": "2026070001",
  "mode": "partial",
  "items": [{"sku": "ART-001", "quantity": 1}],
  "includeShipping": false,
  "idempotencyKey": "erp-job-48213"
}

Field	Required	Meaning
`type`	yes	`capture`, `void` or `refund` (aliases `cancel` and `cancellation` for `void`)
`orderId` or `orderNumber`	yes, one of them	Order by OXID order ID or order number
`mode`	no	`full` or `partial` (default: `partial`)
`items`	for `partial`	List with `sku` (alternatively `productNumber` or `articleNumber`) and `quantity`
`includeShipping`	no	Include shipping costs in a partial capture/refund
`captureNumber`	no	Refund only: the capture to refund from. Required if an item appears in several captures
`idempotencyKey`	no	Max. 255 characters, prevents double execution on retries

Behaviour per type:

capture: full captures all items still open and additionally sets the order's ship date. partial captures only the given items and leaves the ship date untouched. After every successful capture the "mark as paid" and "folder after capture" settings apply.
void: always voids the entire remaining authorized amount. There is no partial variant via the API.
refund: full refunds all captured, not yet refunded items. partial refunds the given items.

Response: JSON with success and message. A successful capture also returns captureNumber. Errors contain error: true. Business errors additionally carry a machine-readable reason, e.g. invalid_json, order_not_found, no_transaction, cannot_capture, cannot_void, cannot_refund, sku_not_on_order, sku_not_captured, capture_number_required. Errors from the Riverty API come back as 400 without a reason, the text is in message.

Response codes:

Code	Meaning
200	Success
400	Invalid JSON, validation error, business error (e.g. order not found, status does not allow the action) or Riverty API error (without `reason`)
401	Secret missing or wrong
403	Integration API disabled
409	Idempotency key is currently being processed
422	Idempotency key reused with a different request body
503	Secret not configured
500	Unexpected error

Idempotency: If the same idempotencyKey is sent again with an identical body you get the stored response back without running the operation again. Failed requests (status 400 and above) are not stored, so a retry runs afresh. oe:riverty:cleanup removes stored keys after the API log retention period.

Console commands and cron job

Command	Description
`oe-console oe:riverty:cleanup`	Cleans up expired API logs, stored idempotency keys and abandoned pending transactions

You set the retention periods in the admin (see Configuration). The command runs three independent cleanup jobs, a failure in one does not stop the others:

Delete API logs older than the configured period.
Mark pending transactions without a linked order as expired once their reservation has expired (without an expiry date after 24 hours, and only if untouched for at least 15 minutes), and delete expired transactions once the retention period since marking has passed. Transactions with a linked order are never touched.
Delete stored idempotency keys older than the API log period.

Deletes run in batches of 5000 rows.

The --dry-run option shows the affected row counts without deleting or marking anything.

OXID has no built-in cron for modules, so the call goes through the system crontab:

0 3 * * * cd /var/www/html && vendor/bin/oe-console oe:riverty:cleanup >> /var/log/riverty-cleanup.log 2>&1

The command always runs in the context of one shop (default: shop 1). With several subshops, add one line per shop using the global --shop-id option:

0 3 * * * cd /var/www/html && vendor/bin/oe-console oe:riverty:cleanup --shop-id=2 >> /var/log/riverty-cleanup.log 2>&1

Practical examples

Example 1: Partial refund via the Integration API

curl -X POST "https://shop.example.com/index.php?cl=mmd_riverty_integration_api" \
  -H "X-Riverty-Integration-Secret: <secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "refund",
    "orderNumber": "2026070001",
    "mode": "partial",
    "items": [{"sku": "ART-001", "quantity": 1}],
    "captureNumber": "801006570",
    "idempotencyKey": "erp-refund-9911"
  }'

Example 2: Test the cron job as a dry run before enabling it

vendor/bin/oe-console oe:riverty:cleanup --dry-run