Alma & Alfy Integration

Alma provides buy-now-pay-later installment payments. Alfy offers insurance-backed payment plans. Both are integrated through dedicated API clients.

Components

Component	File	Role
AlmaApi	src/CoreBundle/Api/AlmaApi.php	Alma API client
AlfyApi / AlfyApiInterface	src/CoreBundle/Api/AlfyApi.php	Alfy API client (with interface)

Configuration

Required parameters in parameters.yml:

alma:
  api_url: "https://..."
  api_key: "..."

alfy:
  api_url: "https://..."
  api_key: "..."

Alma -- BNPL Flow

View diagram source

sequenceDiagram
    participant CUST as Customer
    participant MAG as Magento Checkout
    participant ALMA as Alma API
    participant API as AlmaApi
    participant DB as Database

    CUST->>MAG: Select Alma at checkout
    MAG->>ALMA: Create payment plan
    ALMA-->>CUST: Display installment schedule
    CUST->>ALMA: Approve plan
    ALMA->>API: Payment confirmed
    API->>DB: Record transaction

Diagram

Alma works similarly to Klarna and Scalapay: the customer selects installment payment at checkout, the provider approves the plan, and Logidav receives confirmation to proceed with fulfillment.

Alfy -- Insurance-Backed Payments

Alfy adds an insurance layer to payments, providing coverage for the transaction:

View diagram source

sequenceDiagram
    participant CUST as Customer
    participant MAG as Magento Checkout
    participant ALFY as Alfy API
    participant API as AlfyApi
    participant DB as Database

    CUST->>MAG: Select Alfy option
    MAG->>ALFY: Create insured payment
    ALFY-->>MAG: Insurance + payment confirmation
    API->>DB: Record insured transaction

Diagram

Interface pattern

AlfyApi implements AlfyApiInterface, which allows for easier testing and potential alternative implementations. This is one of the few payment integrations that uses an explicit interface.

Error Handling

Scenario	Behavior
Alma plan rejected	Customer offered alternative payment methods
Alfy insurance denied	Fallback to standard payment flow
API timeout	Retry with backoff
Settlement discrepancy	Alert raised for manual reconciliation