Short answer
A reliable payment integration separates orders from payment attempts, stores identifiers server-side, processes repeated notifications idempotently and reconciles API states against transaction registers.
- API secrets remain server-side.
- Orders and payment attempts are separate records.
- Webhooks may be repeated or arrive out of order.
- Financial reconciliation is still required when the API works.
Design the data model first
Create separate records for the order, payment attempt and notification event. One order may have a failed or expired attempt followed by a new payment, so the order number cannot be the only transaction identifier.
Store amount and currency server-side and do not trust browser values. Order changes should pass through business logic rather than redirect URL parameters.
- merchant_order_id for the internal order;
- provider_payment_id for the payment attempt;
- event_id for the received notification;
- expected amount and currency;
- current status and updated_at timestamp.
Create the payment and present it to the customer
The server validates the order, creates a payment through the approved API and stores the response. The frontend receives only what is required to display the payment link or QR code. Secrets and privileged headers never reach the client.
A repeated user request should not silently create many active payments. Define whether to return the current valid attempt or create a new explicitly linked attempt.
Process the webhook
A webhook confirms a status change independently of browser behavior. Validate authenticity under the documentation, compare amount and identifiers, store the fact of receipt and respond quickly. Perform heavy work after the event is recorded.
Idempotency means that receiving one notification several times creates one business outcome. Goods, balance or settlement instructions must not be issued twice.
- validate the event;
- store its identifier;
- compare expected parameters;
- change status atomically;
- queue downstream processing.
Observability and reconciliation
Logs should reconstruct the order journey without exposing secrets or unnecessary personal data. Add a correlation identifier, error metrics and a process for rechecking stuck payments.
Compare internal operations with the dashboard and register every day. The API serves the online journey; reconciliation confirms accounting completeness.
Questions and answers
Can the payment API be called from the browser?
Privileged methods should be called server-side. The frontend receives only customer-facing data.
What should happen when a webhook is repeated?
Check the event identifier and current state, then apply the change idempotently.
Is status polling needed when webhooks exist?
Webhooks provide the primary event channel, while selective rechecks and daily reconciliation improve reliability.
Sources and policies
We use official payment-system information and WHITECAPITAL policies. Contractual documents prevail for an individual merchant setup.
This material is for operational orientation and is not a promise of approval, universal method availability, a fixed fee or settlement timing.