Integration architecture
In one sentence
Pehmen accepts authenticated requests, records a durable decision before dispatch, connects to payment providers through isolated adapters, and returns outcomes through signed events. Sensitive credentials and payloads remain encrypted behind non-public data interfaces.
Written for engineers evaluating or integrating Pehmen.
The diagram is intentionally an integration view. It describes the guarantees a customer can rely on without publishing deployment hostnames, internal ports, service placement or operational recovery details.
The integration boundary
| Component | Responsibility | Integration contract |
|---|---|---|
| Merchant systems | Your dashboard users and server-side API clients | Call the documented HTTPS API with a session or environment-bound API key |
| Secure API edge | Terminates encrypted traffic and applies request controls | Only documented HTTP interfaces are public |
| Pehmen control plane | Authenticates, validates and orchestrates requests | Re-authorizes every request for one workspace and environment |
| Decision services | Apply trust, policy and routing controls | Produce a stored verdict and trace before provider dispatch |
| Provider adapters | Communicate with licensed payment providers | Use the workspace's validated provider connection |
| Durable records | Store tenant-scoped state and the audit trail | Not exposed as a public integration endpoint |
| Protected evidence | Store encrypted payloads and evidence | Accessed only through authorized application workflows |
| Key management | Encrypts sensitive material and signs outbound artifacts | Uses capabilities separated from application storage |
| Merchant endpoints | Receive Pehmen events | Verify signed webhook deliveries using the published public keys |
A confirmed payment
- Your server creates and confirms a payment intent through the API.
- Pehmen authenticates the caller, checks its workspace, environment and permission, and applies idempotency controls.
- Trust, policy and routing services produce a durable decision and candidate trace.
- An approved instruction is dispatched through the selected provider adapter.
- The provider outcome updates the durable record.
- Pehmen sends the subscribed event to your HTTPS endpoint with an Ed25519 signature.
The HTTP response and later webhook refer to stored records; the dashboard does not recompute a historical decision.
Security boundaries
- Public clients reach only documented HTTPS interfaces.
- Data and evidence services are not public integration endpoints.
- Every tenant request is authorized for one workspace and one environment.
- Test and Live use separate credentials, policies, keys and records.
- Provider credentials and sensitive payloads are encrypted; key-management capabilities are separated by workload.
- Outbound webhooks are signed and can be verified without a shared secret.
For request and event details, continue with the API overview and webhook verification guide.