Reference
Provider Callback Reference
Reference for provider callback behavior related to Payflow client API payment status updates.
Provider callbacks are not client API calls, but they are directly related to client API payment lifecycle. They let payment providers notify Payflow after a hosted checkout, component payment, or ACH transfer changes state.
Callback sources
| Provider | Related client API flow | Expected behavior |
|---|---|---|
| Stripe | Hosted checkout, payment components | Payflow verifies the provider signature and maps supported payment events to Payflow status updates. |
| Square | Hosted checkout, payment components | Payflow verifies the provider signature and maps supported payment events to Payflow status updates. |
| Dwolla | ACH transfers | Payflow parses ACH transfer events and maps supported transfer states to Payflow status updates. |
Acknowledgement
Successful provider callback handling returns:
{
"received": true
}This acknowledgement intentionally does not use the Payflow client API envelope because providers expect a compact callback response.
Invalid callbacks
Payflow rejects callbacks that fail provider-specific validation. Common causes include:
- Missing signature header.
- Invalid signature.
- Malformed JSON or provider payload.
- Callback secret not configured for the environment.
- Provider event type not mapped to a Payflow payment update.
Integration guidance
Your application should not call provider callback URLs directly. Instead:
- Store the
payflowReferencereturned by the client API. - Store your own order, invoice, transfer, or customer reference.
- Store the provider returned in the Payflow response.
- Make your status update path idempotent.
- Expect provider callbacks to arrive later than the original client API response.
- Keep a manual support path for matching Payflow references to provider references.