Authentication

Authenticate client API requests with Bearer API keys, understand key prefixes, CORS checks, rate limits, and request IDs.

Payflow client API requests use Bearer credentials:

Authorization: Bearer sk_test_key_id_secret

The credential determines organization, application, environment, permission level, rate limit, and request logging scope.

Key formats

Type	Format	Notes
Sandbox publishable	`pk_test_<48 hex chars>`	Browser-safe when paired with allowed origins.
Production publishable	`pk_live_<48 hex chars>`	Requires production access.
Sandbox secret	`sk_test_<24 hex key id>_<64 hex secret>`	Server-side only.
Production secret	`sk_live_<24 hex key id>_<64 hex secret>`	Server-side only and requires production access.

Secret keys are shown once when created or rotated. Payflow stores only a digest and suffix.

Publishable keys

Publishable keys are intended for browser or mobile flows. When a browser sends an Origin header, Payflow verifies that the origin is registered for the application environment.

Sandbox origins may use HTTPS or local loopback HTTP:

https://example.test
http://localhost:3003
http://127.0.0.1:3003

Production origins must use HTTPS and must not include paths, query strings, fragments, usernames, or passwords.

Secret keys

Secret keys are intended for backend systems. Use secret keys for:

Hosted checkout creation from a server.
Server-mediated payment component confirmation.
ACH customer token creation.
ACH transfer preview and creation.
Any workflow where a compromised browser credential would be unacceptable.

Never expose a secret key in client JavaScript, mobile binaries, screenshots, logs, support tickets, or analytics events.

Credential state

A key is accepted only when:

The organization is active.
The application is active.
The key environment matches the requested environment.
Sandbox onboarding is ready for sandbox calls.
Production access is enabled for production calls.
The secret key is not revoked or past its retiring overlap window.

If any of those checks fail, Payflow returns:

{
  "success": false,
  "data": null,
  "message": "API credential is not active."
}

Rate limits

Client API calls are rate limited per application environment and credential type. Publishable calls also have an IP-level limiter.

When a request is limited, Payflow returns 429:

{
  "success": false,
  "data": null,
  "message": "Rate limit exceeded."
}

Rate limits can vary by environment and credential type. Design clients to back off on 429 instead of retrying aggressively.

Request IDs

Payflow attaches request IDs to logs and error handling. You can send your own:

X-Request-Id: checkout-ord_1001

Use a stable request ID per upstream attempt. Do not put secrets, full account numbers, or customer personal data in request IDs.

SDK identification headers

The client API CORS preflight allows these optional headers for SDKs:

X-Payflow-SDK
X-Payflow-SDK-Version

Use them to identify official or internal SDK versions in request logs.