Deutsche Version

Back to overview

Riverty Payments: Shop API

This documentation always describes the latest published version.

The plugin is dual-mode: the storefront and the Sylius Shop API use the same payment path. It does not ship any endpoints of its own for this.

The plugin adds no endpoints to the Shop API. There are no shop routes of its own and no API Platform resources. Instead it takes part in the payment requests that Sylius already uses for both the storefront and the Shop API. Which endpoints you call to start a payment and to query its payment request is described in the Sylius documentation, not here.

How a Riverty payment runs through the API

graph TD
    A["Client starts the payment via Sylius payment request"] --> B["Command bus: authorization"]
    B --> C["Riverty plugin calls Riverty"]
    C --> D{"Answer?"}
    D -->|Accepted| E["Payment authorized"]
    D -->|Redirect needed| F["redirect_url in the response data of the payment request"]
    D -->|Rejected| G["Payment request and payment fail"]
    F --> H["Client opens the hosted checkout"]
    H --> I["Status query or reconciliation settles the payment"]

1. The client triggers the authorization of the payment through the Sylius payment request interface. For this, the plugin is registered on Sylius' payment request command bus for the gateway riverty and supports the actions capture, authorize and status.
2. The plugin asks Riverty and moves the payment request and the payment forward together.
3. If the customer needs the hosted checkout, its address is in the response data of the payment request under redirect_url. A pure JSON client does not get an HTTP redirect: it reads the address and opens it itself, for example in a new tab or a WebView.
4. When the customer returns, the status query settles the payment. If they do not return, mmd:riverty:reconcile catches up.

The transport for payment requests must be synchronous (sync://), otherwise the authorization only runs when a worker consumes the queue and the customer gets no redirect_url. See Installation.

Errors

The plugin defines no error format of its own. A failure shows up as an error state of the payment request and the payment in Sylius; the message is in the response data of the payment request and as the error of the payment. The format is Sylius' own.

Limitation: identification number in the Nordics

Headless shops cannot pass the identification number. The field belongs to the storefront checkout. An order to Norway, Sweden, Denmark or Finland that is placed through the API without a number is not sent to Riverty: the payment fails with the clear message that an identification number is missing (visible on the payment request and as the error of the payment). A headless shop has to collect the number itself and cannot hand it to this plugin yet.

Orders to the Nordics also need the currency Riverty expects there (NOK, SEK, DKK; EUR in Finland). This limitation does not apply to countries outside the Nordics.

Admin actions

Capture, void and refund as well as the buttons of the settings are admin actions protected by a CSRF token and not part of an API. How to use them is described under Order management.