Payments¶

Vectis provides a full payment lifecycle — from authorization through capture, void, and refund — with pluggable gateway strategies and built-in support for Authorize.net CIM.

Payment Flow Overview¶

flowchart TD
    CO[Checkout / Admin Create Order] --> PS[PaymentService]
    PS -->|capture_mode=authorize| AUTH[strategy.authorize]
    PS -->|capture_mode=capture| CHARGE[strategy.charge]
    AUTH --> AUTHORIZED[status: authorized]
    CHARGE --> CAPTURED[status: captured]
    AUTH -->|responseCode=4| HELD[status: held_for_review]
    AUTHORIZED -->|admin action| CAP[strategy.capture → captured]
    AUTHORIZED -->|order cancelled| VOID[strategy.void → voided]
    CAPTURED -->|order refunded| REF[strategy.refund → refunded]
    HELD -->|admin release| AUTHORIZED
    HELD -->|order cancelled| VOID

Capture Modes¶

Every payment method has a capture mode configured in the admin:

The capture mode is stored in PaymentMethod.config.capture_mode and defaults to "authorize" for credit card gateways.

Transaction Types¶

Every payment operation creates a PaymentTransaction record with both a status and a type:

Automatic Void & Refund¶

When an order transitions to Cancelled or Refunded, the system automatically processes the appropriate payment reversal:

• Authorized transactions are voided (no settlement occurred, so no refund needed).
• Captured transactions are refunded (full amount returned to the buyer).
• Held for review transactions are voided.

This happens as a side effect of the order state machine — no manual action is required. Failed reversals are logged but do not block the order transition.

Fraud Filter Handling¶

When Authorize.net's FDS (Fraud Detection Suite) flags a transaction:

1. The transaction is stored with status="held_for_review".
2. The order moves to the HeldForReview state.
3. The order's fraud_status is set to "held_for_review" and FDS filter details are stored in fraud_details.
4. The admin order detail page shows an orange Fraud Hold banner with the filter names.

Releasing a Fraud Hold¶

From the admin order detail page:

1. Review the fraud details and FDS filter information.
2. Click Release Fraud Hold to approve the transaction.
3. The system calls updateHeldTransactionRequest on Authorize.net.
4. The transaction status changes to "authorized" and the order moves to AwaitingFulfillment.

Alternatively, you can cancel the order, which voids the held transaction.

Saved Payment Methods (CIM)¶

Customers can save credit cards for future use. Cards are tokenized client-side using Accept.js and stored as gateway profile references — Vectis never stores raw card data.

Storage Model¶

Each saved card stores:

• Gateway profile IDs — CIM customer and payment profile IDs
• Display fields — brand, last four digits, expiry (safe to display)
• Account and location scope — which B2B account and optionally which location the card belongs to

Location Scoping (B2B)¶

For B2B customers with multiple locations:

• Cards can be scoped to a specific location using location_id.
• Location employees see only their location's cards.
• Account owners and admins see all cards across all locations.
• Cards without a location_id are account-wide and visible to everyone in the account.

Managing Cards¶

Storefront — customers manage cards at /account/payment-methods:

• Add new cards (tokenized via Accept.js)
• Delete cards
• Set a default card

Admin — staff manage cards in the customer detail page (Saved Cards tab):

• View all cards across locations
• Charge a saved card directly
• Delete cards

Admin Order Creation¶

Staff can create orders directly from the admin panel without going through the storefront checkout:

1. Navigate to Orders → Create Order.
2. Select an account, channel, and optionally a location.
3. Add line items by variant ID and quantity.
4. Set shipping and billing addresses.
5. Choose a saved card or payment method, and select the capture mode.
6. Click Create Order.

The system resolves prices from the catalog, creates the order, and processes payment through the same PaymentService pipeline as checkout.

Order Modification & Reauthorization¶

For orders with payment_status="authorized" (not yet captured), staff and B2B buyers can modify the order:

1. Add, remove, or update line items.
2. The system recalculates totals.
3. The old authorization is automatically voided.
4. A new authorization is placed for the updated grand total.

This is exposed via the modifyOrder mutation and is only available when the order is in an editable state.

Configuring Payment Gateways¶

From Payments in the admin panel:

1. Click Add Method to create a new payment gateway configuration.
2. Choose a gateway (Authorize.net or Test).
3. Set environment (Sandbox or Production).
4. Set capture mode (Authorize Only or Authorize + Capture).
5. Enter API credentials.
6. Choose accepted card brands (Visa, Mastercard, etc.).
7. Set supported currencies.
8. Enable or disable CVV and billing address requirements.
9. Test Connection to verify credentials.

Each payment method has a unique code used during checkout to route to the correct gateway.

Accept.js Integration¶

Vectis uses Authorize.net's Accept.js for PCI-compliant client-side card tokenization:

1. The storefront loads Accept.js dynamically.
2. Card data is entered in the browser and never touches the server.
3. Accept.js returns an opaque data token (descriptor + value).
4. The token is sent to the server with the checkout mutation.
5. The server uses the token to authorize or charge via the Authorize.net API.