Invoice Order ID

Overview

What it means

An invoice order ID is a merchant-assigned reference linking a payment request to a particular order in the shop’s own system. It gives staff and applications a stable way to match payment activity with the commercial transaction.

How it works

When creating a crypto invoice, the merchant submits or stores an order reference and receives a provider invoice identifier. The system retains a mapping between both IDs, the buyer, expected asset, amount, payment addresses and resulting blockchain transaction references. Repeated provider callbacks should update that same order rather than create new purchases.

Understanding the technical details

The mapping table should impose a unique key on merchant ID plus order ID when each order is intended to have only one active invoice. If multiple attempts are allowed, store version or attempt IDs explicitly. A callback with a familiar order ID but the wrong provider invoice ID is suspicious and should not trigger payment acceptance. Keeping stable identifiers across checkout, webhooks and accounting makes missing-payment investigations far easier.

Common failures and limitations

An order ID is not necessarily globally unique; a merchant should scope it by account or application and prevent accidental reuse. Exposing sequential order IDs can reveal activity patterns and must not authorize account access by themselves.

Related concepts

Crypto Invoice, Crypto Checkout, Crypto Payment Link.

Further reading

OxaPay — Integration documentation.