--- sidebar_label: 'External Payment - Flow Descriptions' sidebar_position: 3 --- # External Payment - Flow Descriptions :::note Information in this article is in preview status. Do not use information in this article without being in contact with Future Ordering. ::: This document describes the expected interaction patterns between *Future Ordering* and a *Partner* payment provider. It is intended to guide Partner integrations by defining the required request/response contracts, event delivery expectations, and timeout behaviours. All payment operations are initiated by FO Payment System via an HTTP POST to a Partner-configured endpoint (shown as `POST /payments` in the diagrams below) and are completed asynchronously. The Partner responds with `202 Accepted` and subsequently delivers a completion event to the FO Payment Notifications endpoint. The URL is configurable per merchant. ## Standard Flow ### Full Transaction Lifecycle _Complete flow from registration through authorization to capture._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (registration_succeeded) deactivate P FO->>+P: POST /payments {operationType: "authorization"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (authorization_succeeded) deactivate P FO->>+P: POST /payments {operationType: "capture"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (capture_succeeded) deactivate P ``` ### Variants #### User Cancellation During Registration _User cancels the payment while registration is being processed._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: User cancels P-)N: POST /events (registration_cancelled) deactivate P ``` #### Annulment After Authorization _Authorization is annulled when order placement fails after a successful authorization._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (registration_succeeded) deactivate P FO->>+P: POST /payments {operationType: "authorization"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (authorization_succeeded) deactivate P FO->>+P: POST /payments {operationType: "annulment"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (annulment_succeeded) deactivate P ``` ## Failure Scenarios ### Validation Error _Partner rejects the request immediately with 400 Bad Request due to malformed JSON or a missing required field. No event is sent as the operation was never accepted._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner FO->>+P: POST /payments {operationType: "capture"} Note over P: Invalid JSON or missing required field P-->>-FO: 400 Bad Request Note over FO: No event expected — request rejected before processing ``` ### Registration Failed _Partner accepts the registration but it fails downstream, e.g. the request to the payment provider times out._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: Request to payment provider timed out P-)N: POST /events (registration_failed) deactivate P ``` ### Authorization Declined _Partner accepts the operation but the payment is declined downstream, e.g. by the card scheme._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "authorization"} P-->>FO: 202 Accepted Note over P: Payment declined downstream P-)N: POST /events (authorization_failed) deactivate P ``` ### Capture Failed _Partner accepts the capture but it fails downstream, e.g. the payment provider rejects the settlement._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "capture"} P-->>FO: 202 Accepted Note over P: Settlement rejected downstream P-)N: POST /events (capture_failed) deactivate P ``` ### Non-Retryable Capture Failure _Partner accepts the capture but it fails permanently downstream, e.g. due to a fiscalization error at the terminal. The capture cannot be retried. FO Payment System may retry the capture, but each attempt fails. When the reservation expires, FO Payment System sends an annulment to release the reserved funds._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (registration_succeeded) deactivate P FO->>+P: POST /payments {operationType: "authorization"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (authorization_succeeded) deactivate P FO->>+P: POST /payments {operationType: "capture"} P-->>FO: 202 Accepted Note over P: Capture fails permanently (e.g. fiscalization error) P-)N: POST /events (capture_failed) deactivate P FO->>+P: POST /payments {operationType: "capture"} P-->>FO: 202 Accepted Note over P: Capture still not possible P-)N: POST /events (capture_failed) deactivate P Note over FO: Reservation expired FO->>+P: POST /payments {operationType: "annulment"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (annulment_succeeded) deactivate P ``` ### Annulment Failed _Partner accepts the annulment but it fails downstream, e.g. the payment provider rejects the reversal._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (registration_succeeded) deactivate P FO->>+P: POST /payments {operationType: "authorization"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (authorization_succeeded) deactivate P FO->>+P: POST /payments {operationType: "annulment"} P-->>FO: 202 Accepted Note over P: Annulment fails downstream P-)N: POST /events (annulment_failed) deactivate P ``` ### Conflicting Operation _Partner accepts the operation but the transaction is in an incompatible state, e.g. a capture operation when the transaction is annulled._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "capture"} P-->>FO: 202 Accepted Note over P: Transaction in annulled state P-)N: POST /events (capture_failed) ``` ### Stalled Authorization _Partner accepts but never sends a completion event within the timeout window. FO Payment System transitions the payment to a failed state and sends an annulment request._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "authorization"} P-->>-FO: 202 Accepted Note over FO: Awaiting completion event... Note over FO: Timeout exceeded — no event received FO->>FO: Transition to failed state FO->>+P: POST /payments {operationType: "annulment"} P-->>FO: 202 Accepted Note over P: Processing... P-)N: POST /events (annulment_succeeded) deactivate P ``` ### Unacknowledged Registration _The Partner completes registration but the event delivery to FO Payment Notifications fails. The Partner aborts the registration as a compensating action. FO Payment System receives no registration event and transitions the payment to a failed state on timeout._ ```mermaid sequenceDiagram participant FO as FO Payment System participant P as Partner participant N as FO Payment Notifications FO->>+P: POST /payments {operationType: "registration"} P-->>FO: 202 Accepted Note over P: Processing... P->>N: POST /events (registration_succeeded) N-->>P: 500 Internal Server Error Note over P: Abort registration (compensating action) deactivate P Note over FO: Registration timeout exceeded FO->>FO: Transition to failed state ```