Skip to content
TilloTech Docs

Processor Integration Workflow

Use this page as the durable reference for processor integration work. Use the processor-integration-workflow skill for the full implementation plan, processor-documentation when creating or refreshing operations-facing processor pages in docs/processors/, and backend-guidelines for Laravel conventions.

Scope

Processor work covers third-party gift-card providers, issuer configuration, catalogue collection, issuance, balance, cancellation, retrieval, retries, and processor interaction auditing.

Common locations:

text
app/DataIssuer.php
app/Processors/
app/Processors/Interaction/
app/Http/Clients/
config/
database/
tests/

Architecture Fit

Processor resolution is issuer and brand driven. Endpoints should not select concrete processor classes ad hoc. Keep provider protocols isolated in processor adapters and HTTP clients.

Use the shared processor interaction layer for typed requests and responses. Keep auditing, retries, and error mapping consistent with sibling processors.

Integration Checklist

  • Issuer/config/env entries are defined.
  • Data issuer mapping resolves the processor.
  • Processor class follows the appropriate sync or async base class.
  • HTTP client isolates provider protocol details.
  • Interaction DTOs model request and response data explicitly.
  • Error mapping is deterministic and tested.
  • Catalogue collector behavior is documented and tested when applicable.
  • Processor interaction auditing is wired consistently.
  • Feature and unit tests cover happy paths, failures, retries, and edge cases.

Documentation Expectations

Do not create provider-specific docs for every routine implementation detail. Do capture:

  • unusual provider semantics;
  • retry or idempotency decisions;
  • non-obvious catalogue mapping rules;
  • production rollout constraints;
  • ADR-worthy tradeoffs.

Verification

Run focused processor tests first. Broaden to integration or characterisation suites when the change touches shared processor behavior.

shell
docker compose exec -T core.web php artisan test --compact --filter=ProcessorOrClientTestName