Integrating electronic invoicing and payments in Jordan requires two connected but distinct records. An invoice establishes what was supplied and what is due under the applicable requirements. A payment event records what a selected provider confirmed and how that event was settled. A sound design preserves both lifecycles and creates an auditable relationship between them. It does not reduce financial truth to a manually editable “paid” flag.
Verify current official requirements
Technical specifications, guidance, provider capabilities, and implementation stages can change. At the beginning of delivery, consult the current material from Jordan’s Income and Sales Tax Department and the relevant national e-invoicing resources. Identify the entity, invoice type, fields, and process that actually apply. An integration built for a different organisation or an old specification is not evidence of current compliance.
Record the review date, specification version, decisions, and the qualified people who approved them. The software team should not invent tax treatment. Where interpretation is required, involve the organisation’s accountant or appropriate adviser. The application implements the approved policy and preserves evidence.
Model the invoice lifecycle
Define allowed states such as draft, approved, submitted, accepted or rejected externally, corrected, cancelled, and credited where applicable. State names and transitions must follow the current business and regulatory design. Deleting a record should not be treated as a universal correction mechanism. Users need to know which action is permitted, who may perform it, and what resulting document or event is created.
Keep the internal identifier separate from external references. Store the request, response, timestamps, and status needed for support without collecting unnecessary sensitive material. If a submission times out, do not generate another invoice blindly. Retry with an idempotent identifier or query status as the official contract allows.
Model payment independently
A payment can begin as a request, wait for action, be confirmed, fail, expire, be cancelled, or later be refunded. Provider terminology varies, so define an internal state model and map each external event deliberately. Do not mark an invoice paid because the browser returns to a success page. The customer can close the page, open a stale URL, or return before final confirmation.
Reliable confirmation should come from authenticated server-to-server communication described by the provider, such as a verified callback or a protected status query. Preserve the provider reference, amount, currency, time, and verified state, then associate that event with the relevant invoice or balance.
Make event handling idempotent
Providers commonly retry notifications when acknowledgement is delayed or lost. If every callback creates a ledger event, the same payment may be recorded twice. Use a unique event or transaction key and perform validation and persistence within an appropriate transaction. Acknowledge only after the required work is committed, and make failures safe to retry.
Test out-of-order events. A delayed callback may arrive after a status query, or a refund can arrive after a reporting period has closed. Define precedence and transition rules so an older message cannot silently move a record back to an invalid state.
Reconcile amounts, not only status
An invoice can receive a partial payment or multiple payments. A confirmed amount can differ from the requested amount, or an unexpected currency can arrive. Do not convert every confirmation into “paid in full.” Derive the balance from verified financial events and route discrepancies to review.
Agree on policies for underpayment, overpayment, allocation, and unapplied funds with finance. The integration should detect and present evidence; developers should not invent an accounting decision. Preserve who resolved the discrepancy and why.
Design cancellation, correction, and refund paths
An invoice may be cancelled while a payment is still pending, followed by a late confirmation. A completed payment may need a full or partial refund. Map these intersections before implementation. Do not erase the original payment event; create the appropriate reversing event with its own reference, reason, and provider state.
Tax correction and movement of money may be separate actions. Make both visible and assign ownership. A generic “undo” button is dangerous when it hides distinct legal and financial consequences.
Build daily reconciliation
The integration is not complete when a green success state appears. Obtain a trustworthy provider settlement or transaction feed and match it against internal events by reference, amount, currency, and status. Classify exceptions: present at the provider but missing internally, present internally but absent externally, duplicated, or mismatched.
Assign a role and resolution procedure. Preserve the evidence and action used to clear the difference. Finance should be able to move from invoice to payment events to reconciliation without collecting screenshots from several systems.
Protect secrets and callback endpoints
Provider credentials belong in controlled secret storage, not source code or browser bundles. Support rotation and grant the minimum required permissions. Validate signatures, timestamps, references, amounts, and currencies exactly as the provider specifies. Do not trust a customer-controlled field when the server can verify it independently.
Restrict and monitor callback endpoints using the mechanisms the provider supports. Apply sensible rate controls and structured logging. Record identifiers and states needed for investigation while avoiding payment details the application does not require. Ensure error logging cannot expose secrets.
Treat provider outages as normal conditions
The invoicing platform, payment provider, or local network may be unavailable. Queue recoverable work, show “pending verification” rather than a false success or failure, and retry with controlled backoff. After a limit, route the case to an owned human review queue. Prevent repeated clicks from creating multiple requests.
Decide what work can continue during an outage. The organisation may be able to save a draft, issue an internal reference, or may need to pause a regulated action. The answer depends on the current official requirements and business process. Test the selected behaviour rather than assuming it.
Use contract and scenario testing
Test valid and invalid requests, signature failure, duplicate and delayed callbacks, amount mismatch, cancellation, refund, timeout, and provider unavailability. Use the provider’s supported test environment and synthetic data. One successful developer-led transaction is not adequate acceptance.
Monitor provider contract changes and deprecations. Pin a documented version when available, subscribe to official change notices, and run recurring checks. The software cost estimation guide explains why this maintenance belongs in ownership cost. The subscription versus one-time software guide helps assign that responsibility under different commercial models.
Make auditability useful to operations
An audit trail should answer who initiated an invoice action, which system accepted it, what payment event arrived, and how a discrepancy was resolved. Use business-readable status descriptions and link them to technical identifiers. Avoid exposing raw provider payloads to ordinary users, but make diagnostic evidence available to authorised support staff.
Define retention and access according to purpose and applicable requirements. Logs should support investigation without becoming an uncontrolled duplicate store of financial or personal data.
Roll out with reversible stages
Begin with a limited send or read capability, compare results manually, and expand only after acceptance. Use a controlled feature switch and retain the previous safe process until the new route is verified. Train finance and support on failures, pending states, corrections, and reconciliation—not only the successful checkout.
BarmajTek’s invoicing and payment integration service can scope the adapter around the chosen provider, current requirements, and existing system. A proposal should name the assumed specification, test environment, failure scenarios, monitoring, reconciliation, and handover.
Build a chain of financial evidence
A dependable integration answers four questions: what invoice action occurred, what the external system confirmed, how the payment was allocated, and how finance reconciled it. A green icon alone cannot answer them. To evaluate an existing or planned design, request an invoice-to-settlement integration review with your real state transitions and exception categories before selecting an API or publishing claims about fees and timing.
