# Vermilion

> Vermilion is a B2B payment orchestration platform: one REST API and dashboard
> in front of multiple payment service providers (Stripe, Adyen, Shift4, plus a
> deterministic sandbox simulator). It routes each payment by merchant-defined
> rules, falls back between providers when one is definitively unavailable,
> normalizes statuses/errors/webhooks across PSPs, and abstracts stored cards
> behind platform tokens so a card saved once can be charged on any connected
> provider.

Key facts for integrating:

- Base URL (sandbox): https://api.vermil.dev/v1 — authenticate with
  `Authorization: Bearer sk_sandbox_…` (keys are environment-scoped).
- Every mutating request requires an `Idempotency-Key` header; replaying the
  same key returns the original result instead of acting twice.
- Money is always integer minor units plus an ISO-4217 currency code
  (1000 + EUR = €10.00). Never send floats.
- Payment statuses: created → processing → requires_action → authorized →
  captured / voided / failed / partially_refunded / refunded. Errors use one
  normalized taxonomy across all PSPs (e.g. insufficient_funds, psp_timeout).
- Cross-PSP fallback happens only when a provider definitively did not receive
  the charge. Ambiguous failures (timeout after send, PSP 5xx) hold the payment
  in `processing` — poll the payment or consume webhooks for the final state.
- Merchant webhooks are HMAC-signed (`vermilion-signature: t=…,v1=…`, SHA-256,
  5-minute replay window). Endpoint URLs must resolve to public addresses;
  redirects are not followed.
- Sandbox test matrix is deterministic: with the simulator (`payment_method.type
  = "sim_card"`), the last two digits of the amount script the outcome
  (…05 declines, …61 requires 3DS, …19 ambiguous timeout).

## Docs

- [Quickstart](https://docs.vermil.dev/docs/): first sandbox payment in five minutes
- [Authentication](https://docs.vermil.dev/docs/authentication/): API keys, environments
- [Payments](https://docs.vermil.dev/docs/payments/): create, capture, void, refund
- [Routing & fallback](https://docs.vermil.dev/docs/routing/): rules, PSP chains, fallback semantics
- [Customers & tokens](https://docs.vermil.dev/docs/tokens/): store once, charge on any PSP
- [Webhooks](https://docs.vermil.dev/docs/webhooks/): endpoint rules, signatures, retries, delivery log
- [Errors](https://docs.vermil.dev/docs/errors/): normalized error taxonomy
- [Test cards & sandbox](https://docs.vermil.dev/docs/test-cards/): deterministic test matrix
- [API reference](https://docs.vermil.dev/docs/api/): endpoint catalogue
- [OpenAPI 3.1 spec](https://docs.vermil.dev/openapi.json): machine-readable API description
- [Changelog](https://docs.vermil.dev/docs/changelog/)

## Optional

- [Product overview](https://vermil.dev/product/)
- [PSP catalogue & partner program](https://vermil.dev/partners/)
- Contact: hello@vermil.dev