Integration Patterns

Subscription Checkout

Create invoices and preserve both merchant and public identifiers
View as Markdown

Treat invoice creation as a checkout boundary. One SDK call produces both the merchant-side record ID and the agent-facing payment instructions.

1import { randomUUID } from "node:crypto";
2
3const invoice = await invoices.createInvoice({
4  idempotencyKey: randomUUID(),
5  amountUsdc: config.subscriptionOffer.priceUsdcAtomic,
6  description: `${config.subscriptionOffer.name} subscription`,
7  metadata: {
8    source: "docs-example",
9    offerKey: config.subscriptionOffer.key,
10    durationDays: config.subscriptionOffer.durationDays,
11  },
12  metadataPublic: false,
13});
14
15console.log(invoice.invoiceId);
16console.log(invoice.publicInvoiceId);
17console.log(invoice.status);
18console.log(invoice.agentProtocol);

What to carry into your own app

  • keep invoiceId for internal references and merchant-side cancellation
  • keep publicInvoiceId for payer-facing status checks and webhook joins
  • hand agentProtocol through to agents as-is rather than re-encoding payment instructions

This pattern keeps ownership of local checkout records in your app while letting Gwop provide the payment contract.

Create an Invoice

See the raw create call and the invoice response fields in the API guide

Get Invoice

See the payer-facing invoice view used for status and payment methods

Two Invoice IDs

Learn why your backend should store both the merchant and public identifiers