Payment and telecom integration patterns in the region

Many payment and telecom requests are asynchronous. A synchronous acceptance means the provider received or queued the instruction, not that value moved or a message reached a handset. Represent submitted, provider-accepted, pending, successful, failed, expired, reversed and unknown as explicit states where the provider protocol supports them. Do not compress pending and unknown into success because the first response was HTTP 200.

Transitions need rules. A late success may arrive after the local polling job marked the operation unknown. A reversal can follow success. Duplicate callbacks may repeat the same state. Keep every observation with provider time, receipt time, source and payload identity. Project the current state from those observations. If a transition conflicts with the expected model, place it in an exception queue instead of silently overwriting history.

A caller may retry because it never received your response. Your adapter may retry because the provider response timed out. The provider may process the original request even though the connection closed. Generate a stable business reference before any outbound call and persist the intended operation. Repeated local submissions with the same idempotency identity should return the existing operation rather than send again.

Use the provider’s idempotency or external reference field where available, but do not assume it has unlimited scope or retention. Store request fingerprints and provider references locally. If an uncertain timeout cannot be queried safely, stop automated retries and ask reconciliation to determine the result. For value-moving operations, a duplicate is worse than a delayed result. Bounded uncertainty is an honest state.

A callback endpoint is public application input even when the provider supplies it. Verify the protocol’s signature, mutual TLS identity, source control or shared-secret construction as documented. Check timestamp and replay conditions. Parse against a strict schema. Bind the callback to the original operation using both local and provider references, then check whether the proposed transition is allowed.

Return quickly after durable receipt. Business processing, notifications and reporting can happen asynchronously. A slow callback handler invites provider retries, which increases duplicates during an incident. Store a callback fingerprint and make processing idempotent. Do not log credentials or full personal payloads. Keep enough metadata for correlation while sending sensitive evidence to a restricted store with retention rules.

Callbacks can be delayed, duplicated or lost. Polling can be rate-limited and may return a state that trails the provider’s internal ledger. Use both according to operation value and age. A callback gives prompt observation. Scheduled queries close gaps for operations that remain pending beyond their expected interval. Stop polling once the operation reaches a terminal state unless the provider permits later reversal, in which case a settlement process still checks final records.

Backoff polling and add jitter so a provider recovery does not trigger a synchronized surge. Prioritise older or higher-consequence unknown operations. Record each query and response as an observation. If callback and query disagree, apply the provider’s documented precedence rules or escalate. Do not select whichever response arrived last without understanding whether its data can be stale.

Phone numbers, account references, merchant codes and names arrive in different formats. Store a canonical form for matching while preserving the supplied value and its source. Phone numbers should be parsed with country context and stored in an international form where valid, but short codes and service identifiers are not ordinary subscriber numbers. Do not force every telecom identifier through the same parser.

Identity checks have risk and privacy consequences. A successful account-name lookup does not prove that the caller controls the account. A name returned by one provider may differ in spacing, order or abbreviation from another. Use matching rules appropriate to the operation, show uncertainty to an authorised operator and minimise retained identity data. Avoid placing subscriber identifiers in metric labels, URLs or general logs.

Never use binary floating point for currency. Represent value in integer minor units with an explicit currency, or use a decimal type whose scale rules are controlled. Some currencies and provider interfaces do not use the same minor-unit assumptions, so the adapter contract must state scale and rounding. Validate amount limits and fees against the agreement configured for that provider and operation.

A displayed total, requested amount, provider-debited amount, fee and settled amount can differ. Store them as separate facts. Do not rewrite the requested value after settlement. Exchange rates need source, quote time and rounding policy. If conversion occurs outside your system, preserve the provider’s reported values and reconcile them against the commercial statement rather than rebuilding the result from an unrelated market rate.

Operational APIs answer individual requests. Settlement files and statements answer what the provider considers financially final. Build reconciliation around independent evidence. Compare local successful operations, provider transaction records, reversals, fees and settlement totals. Match by stable references first, then use amount, currency, account and time only as controlled secondary evidence.

Classify unmatched records: local-only, provider-only, amount mismatch, status mismatch, duplicate reference, late settlement or unknown. Each class needs ownership and a resolution procedure. Adjustments should create new ledger entries and reasons, not edit the historical transaction. Control totals by file, settlement window and currency catch a missing block even when individual matching appears normal.

A messaging API acceptance usually means queued, not delivered or read. Preserve message identity and map provider receipts into accepted, submitted, delivered, failed, expired or unknown as supported. Sender identity, template approval, encoding and message length affect routing and billing. Unicode text may use fewer characters per segment than a basic alphabet message, so cost and segmentation should be calculated by the adapter rather than guessed in the interface.

Consent, suppression and purpose should be checked before submission. A retry after uncertain acceptance can send duplicate customer messages, so use stable message references and provider query where possible. Notification workflows should decide whether a delayed message still has value. An expired one-time code should not arrive after a newer code. Mark messages with an expiry and suppress them at the last controllable boundary.

Providers may use API keys, signed requests, certificates, private links or combinations. Keep credentials in a secrets service, scope them by environment and operation, and rotate through a rehearsed overlap process. Sandbox credentials and callback endpoints must never share production trust. Egress rules should restrict where adapters can send sensitive requests, though provider address changes need a controlled update path.

Mask account and subscriber data in lower environments. Contract tests can use synthetic fixtures. When production evidence is required for an incident, grant time-bound access and record it. Verify signatures before parsing large callback bodies where the protocol allows. Rate-limit public endpoints and protect them from replay. A provider-branded callback is still traffic from outside the application trust boundary.

Regional integrations face planned maintenance, intermittent connectivity and provider-specific capacity limits. Publish degraded state to the product so users know whether an operation is queued, unavailable or uncertain. Do not let every frontend poll the provider. Centralise status checks, cache safe results briefly and cap retries. Queue work only when the business permits delayed execution; a price-sensitive or consent-sensitive command may need fresh confirmation after recovery.

Dashboards should show request rate, acceptance, terminal success, pending age, callback delay, query rate, reconciliation breaks and provider latency. Break results down by operation and provider with bounded dimensions. Alert on unknown operations ageing past policy and on settlement mismatches, not only HTTP failure. A provider can return successful transport responses while business requests fail because of credentials, balance, limits or format changes.

Provider sandboxes often simplify timing and error behaviour. Build a local simulator for duplicate callbacks, late success, reversal, malformed signatures, timeout after acceptance and rate limiting. Replay recorded synthetic fixtures through contract tests. Verify that the state machine rejects impossible transitions and that retries do not duplicate an effect. Test reconciliation with missing and conflicting records.

The production-readiness record should name references, state mappings, timeout and retry policy, callback verification, credential owner, reconciliation source and support contact for each provider. Keep the canonical model small enough to remain meaningful, and allow adapter-specific evidence where providers differ. Regional integration works when uncertainty is visible, value is reconciled independently and one provider’s failure stays inside its boundary.