Payment Flows
Choose the right Payflow client API flow for hosted checkout, embedded card components, or ACH bank transfers.
Payflow currently supports three main client payment paths:
| Flow | Best for | Main endpoints |
|---|---|---|
| Hosted checkout | Fast sandbox validation and redirect-based card tests. | POST /client/v1/payments |
| Payment components | Embedded card UI using Stripe Payment Element or Square Web Payments. | POST /client/v1/payments/component, POST /client/v1/payments/component/:payflowReference/confirm |
| ACH bank transfer | Server-side bank transfer initiation using tokenized customer data and Dwolla-backed ACH. | POST /client/v1/ach/customer-tokens, POST /client/v1/ach/transfers/preview, POST /client/v1/ach/transfers |
Common payment fields
Card and component flows share these fields:
| Field | Type | Notes |
|---|---|---|
amountMinor | string or integer | Positive smallest currency unit. Use strings for large values. |
currency | string | Three-letter ISO code. Payflow uppercases it. |
paymentMethod | string | Defaults to web_card; use ach for ACH-specific routes where documented. |
description | string | Optional, max 500 characters. |
customer.name | string | Optional, max 160 characters. |
customer.email | string | Optional valid email. |
metadata | object | Optional integration metadata. Do not store secrets. |
Routing and provider selection
Payflow does not make callers choose Stripe, Square, or Dwolla directly. The API evaluates organization routing rules for the credential environment and payment method.
The response includes routing metadata:
{
"provider": "stripe",
"routing": {
"provider": "stripe",
"channel": "web_card",
"matchedRuleId": null,
"matchedConditionIds": [],
"fallback": true
}
}Store the payflowReference from every prepared payment. It is the stable reference used across provider callbacks, transactions, and support investigations.
Status model
Client payment creation usually returns status: "prepared". The final transaction status is recorded later after provider confirmation or webhook updates.
Transaction statuses include:
pending
processing
succeeded
failed
canceled
refundedChoosing a flow
Use hosted checkout when:
- You want the fastest sandbox card integration.
- Redirects are acceptable.
- You want Payflow to return a provider-hosted URL.
Use payment components when:
- You want an embedded card payment UI.
- You can handle provider component rendering in the browser.
- You can confirm the component result through your backend.
Use ACH transfers when:
- You are building bank-account transfer flows.
- You can collect and protect account/routing numbers server-side or in a controlled checkout.
- Your organization has ACH routing, Dwolla credentials, and sufficient Payflow-held wallet balance where required.