Common API Patterns
The Merchant API is most effective when used as part of a clear backend integration model.
This page outlines common patterns that help keep your implementation predictable, secure, and easier to maintain.
1. Keep the API on the backend
The Merchant API is a privileged backend surface, your frontend should never call it directly. See Authentication for the full backend-only model and the safe request pattern.
2. Use unique merchant identifiers consistently
Where the API supports merchant-supplied unique identifiers (merchantUniquePaymentID aka MUPID), use them consistently.
These identifiers make it easier to:
- deduplicate retries
- reconcile state safely
- query the result of an earlier action
- avoid duplicate creation bugs
Do not treat them as optional bookkeeping. They are a practical part of robust API design.
3. Separate creation from retrieval
For many integrations, it helps to think in two modes:
- write operations — create or update something
- read operations — confirm what happened
A good pattern is:
- create or request the action
- store your local identifier mapping
- retrieve or query later for confirmation or reconciliation
This is especially useful for payments, refunds, preauth flows, and customer operations.
4. Treat the API as operational, not just transactional
The Merchant API is not only for "make a payment": it also covers customer management, token and proxy workflows, batch processing, request-to-pay, and diagnostics (see Authentication for the full list). That means it's often part of your backend operations layer, not just your checkout flow.
5. Use Sessions when the browser launches checkout
If your frontend launches Hosted Checkout, do not move trust into browser code. See Sessions and Hosted Checkout for the full session flow.
6. Do not treat redirect as final truth
Redirect is useful for user experience, but it is not the source of payment truth, backend-confirmed state is (callbacks, webhooks, or API GET calls). See Sessions and Hosted Checkout → Redirect and callback still matter for details.
This is one of the most important patterns in the whole documentation set.
7. Design for retries and idempotency
Networks fail, users retry, and backend actions can be repeated.
Your integration should be designed so that repeated requests or repeated notifications do not cause duplicate side effects.
Common ways to support this include:
- stable merchant unique identifiers
- backend state tracking
- safe retry logic
- explicit reconciliation queries
8. Keep environment configuration separate
API integrations usually fail in messy ways when sandbox and production details are mixed. See Authentication → Environment separation for what to keep environment-specific.
9. Use /openapi for reference, not for design guidance
The generated API reference is the source of truth for:
- paths
- schemas
- examples
- response codes
Use these hand-written docs for:
- architecture decisions
- trust boundaries
- safe integration patterns
- choosing the right flow
That split keeps your documentation cleaner and easier to maintain.
10. Build observability in from the start
A production API integration should let you answer questions like:
- what did we try to do?
- what happened?
- what state is the payment or customer in now?
- can we safely retry?
- can support reconcile this issue?
That usually means robust logging, identifier mapping, and some form of operational query or audit trail in your backend.
Related pages
Summary
The Merchant API works best when it is treated as a trusted backend integration surface.
Keep authentication and trust on the backend, use sessions for browser-launched checkout, design for retries and reconciliation, and rely on /openapi for exact reference detail.