Authentication

API key header

Every request to the V1 API must include your API key in the epro-api-key header:

curl -X POST https://api.sandbox.settleflow.io/v1/payment/direct \
  -H "epro-api-key: pk_test_1a2b3c4d5e6f..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

The header name is epro-api-key (all lowercase, hyphen-separated) — this differs from the common X-Api-Key convention and is required for E-PRO compatibility.

Key format and environments

Prefix	Environment	Host	Description
`pk_test_`	Sandbox / test	`https://api.sandbox.settleflow.io`	Use for integration and QA. No real money.
`pk_live_`	Production	`https://api.settleflow.io`	Use against real PSP acquirers.

The host and the prefix must match — a pk_test_ key is only valid on the sandbox host, a pk_live_ key only on the production host. A mismatch is rejected with Code: 3. See Sandbox & test cards for test behaviour.

Key lifecycle

Each successful authentication updates lastUsedAt, so you can identify stale keys from your dashboard.
Keys may carry an expiresAt — expired keys are rejected with error code 3.

Rotating keys

Generate a new key from your dashboard.
Deploy it to your servers.
Delete or let the previous key expire.

Keep both keys active during the rollout window — several active keys per merchant app are accepted.

Authentication errors

Code	HTTP	Message	Cause
`3`	200	`Invalid API key`	Key not found, hash mismatch, or key expired.
`4`	200	`API key is not supplied`	`epro-api-key` header missing or empty.

Remember: all V1 errors are returned as HTTP 200 with { "Code": N, "Error": "..." }. Inspect Code — not the HTTP status — to determine success.

{
  "Code": 3,
  "Error": "Invalid API key"
}

Security recommendations

Never expose API keys in client code. All requests must come from your server.
Scope by environment — never use pk_live_ keys in dev or staging deployments.
Rotate on leak suspicion. Treat API keys as you would OAuth client secrets.
Restrict network egress so only your payment service can reach the API host.