Core Concepts
Understand the Payflow objects that appear in client API credentials, payment calls, routing outcomes, provider callbacks, and transaction records.
Payflow client API access is organized around applications, environments, credentials, routing outcomes, payment preparations, provider callbacks, and transactions.
Application
An application represents one integration surface for an organization. Each application has sandbox and production environments, each with its own credentials and allowed browser origins.
Use separate applications when distinct products need separate keys, browser origins, rate limits, request history, or launch boundaries.
Environment
Payflow supports:
| Environment | Key prefix | Purpose |
|---|---|---|
| Sandbox | pk_test_, sk_test_ | Local development, QA, demos, and provider sandbox flows. |
| Production | pk_live_, sk_live_ | Live payment traffic after Payflow enables production use. |
Environment is encoded in every API key. A sandbox key cannot call production resources, and a production key cannot call sandbox resources.
Credentials
Payflow has two client API credential types:
| Credential | Prefix | Intended location | Capabilities |
|---|---|---|---|
| Publishable key | pk_test_, pk_live_ | Browser or mobile client | Browser-safe setup calls protected by origin checks and rate limits. |
| Secret key | sk_test_, sk_live_ | Server only | Server-side payment creation, ACH tokenization, ACH transfer creation, credential-sensitive workflows. |
All client API credentials are sent as Bearer tokens.
Payment preparation
Before a final transaction exists, Payflow creates a payment preparation. It stores the intended amount, currency, method, selected provider, provider references, expiration window, and routing metadata.
Preparations let Payflow connect a client-side provider result back to the same Payflow reference.
Payflow reference
payflowReference is the stable public reference returned by client payment APIs.
Examples:
pf_test_9d4e2d7f7b5b4dbe8f4b42034c881d77
pf_live_aa33a0d39a944694a0b7d20c69a1d1e2
pf_test_ach_69f14d7e1d3b4d5a9cfbb887adfc34c0Store this reference on your order, invoice, payout, transfer, or support record.
Transaction
A transaction is the durable result of a payment attempt. It includes environment, provider, payment method, amount, status, customer fields, metadata, provider references, and failure details.
Transaction statuses include:
pending
processing
succeeded
failed
canceled
refundedRouting outcome
Your application does not choose Stripe, Square, or Dwolla directly in client API calls. Payflow evaluates routing for the application environment and payment method, then returns the selected provider and routing metadata.
If routing is disabled or unavailable, the client API returns a readable conflict response instead of attempting a provider call.
Wallet-aware ACH flows
Payflow wallets represent Payflow-held funds only. Card payments do not automatically become Payflow-held wallet funds. ACH transfers may check wallet availability when Payflow-held funds are the funding source.
Integration identifiers
Keep these identifiers in your own records:
| Identifier | Where it appears | Why it matters |
|---|---|---|
payflowReference | Client API responses | Primary support and reconciliation reference. |
idempotencyKey | ACH transfer requests | Safe retries for the same business action. |
X-Request-Id | Request headers | Debugging and log correlation. |
| Provider reference | Provider callbacks and Payflow responses | Provider-side investigation and settlement lookup. |