Concepts

Two Invoice IDs

Why Gwop invoices have both a merchant ID and a public invoice ID
View as Markdown

Every Gwop invoice has two identifiers because two different parties need to use it for two different jobs.

The two IDs

FieldFormatUsed by
idUUIDYour backend
publicInvoiceIdinv_*The payer or agent

Your backend uses id for merchant-side concerns like internal references, reconciliation, and canceling an invoice. The payer-facing side uses publicInvoiceId to fetch the public invoice view, discover payment methods, and track settlement.

Why this split exists

The merchant record and the payer-facing checkout are not the same thing.

  • the merchant record belongs in your internal model
  • the public invoice ID is safe to hand to an agent
  • separating them lets your backend keep private state and permissions separate from the public payment flow

The practical rule is simple: store both, but only hand publicInvoiceId to the payer.

What to do in your app

When you create an invoice:

  1. store id on your internal checkout or order record
  2. store publicInvoiceId alongside it
  3. return publicInvoiceId and agentProtocol to the agent
  4. use both IDs later when correlating public invoice status and webhook events back to your local state
Create an Invoice

See where both IDs first appear in the create response

Subscription Checkout

See how to carry both IDs through your backend model