Your application initiates a payment, refund or other supported operation.
Developer guide
Synchronous commands. Asynchronous financial outcomes.
Financial operations often continue after the initial request returns. Use commands to initiate work, events to notify downstream systems and state queries to retrieve the latest operational truth without coupling your application to provider-specific callbacks.
01Command
02Immediate response
03Provider processing
04Event
05State query
Integration boundary
Events carry lifecycle changes, not provider complexity
Applications should react to the business meaning of an event rather than learn the callback model of every bank, PSP, acquirer or terminal provider. The platform boundary keeps provider-specific completion behavior behind a more stable integration model.
The synchronous response identifies the operation and its current state.
Authentication, terminal activity or provider processing may continue asynchronously.
A lifecycle change is delivered to systems that need to react.
The consuming system can retrieve current state when it needs authoritative operational context.
Proven pattern
Semantic event patterns
Production integration experience has shown the value of status-change and completion callbacks across online payments and other payment methods. The reusable pattern is the semantic lifecycle rather than a provider-specific event name.
- Payment status changed — an operation moved to a new payment state.
- Authentication finished — a customer authentication step reached an outcome.
- Refund updated — a post-payment adjustment changed state.
- Terminal or channel operation completed — an asynchronous channel flow reached a result.
Conceptual event envelope — not a current webhook schema
{
"event": "semantic-lifecycle-event",
"transaction_id": "durable-transaction-id",
"reference": "your-business-reference",
"state": "...",
"occurred_at": "..."
}Implementation model
Integration guidance
These patterns describe integration behavior proven in production systems. They define the technical model, not a promise that the current Zopio API will expose any specific endpoint name, field name or contract shape.
Treat events as notifications
Use the event to trigger downstream work without binding business logic to a provider callback format.
Preserve transaction identity
Keep every asynchronous update connected to the same durable transaction context.
Query when current state matters
Use a state query when a workflow needs the latest operational truth rather than relying on one callback alone.
Design consumers for repetition
Downstream systems should be able to recognize previously processed lifecycle updates and avoid duplicating business actions.
Keep channel differences behind the boundary
Online, terminal and alternate-payment flows can expose different provider behavior while sharing the same integration principles.
Continue exploring
Discuss your integration