Skip to main content
Package: gwop-checkout v2.0.0

​
Environment variables

Set these in your .env or deployment config before using the SDK:
VariableDescriptionExample
GWOP_CHECKOUT_API_KEYMerchant API key. Generate in Merchant Dashboard → Settings.sk_m_6vyv...I131
GWOP_WEBHOOK_SECRETWebhook signing secret. Generate in Merchant Dashboard → Settings.whsec_d1...

​
Constructor

import { GwopCheckout } from 'gwop-checkout';

const gwop = new GwopCheckout({
  merchantApiKey: process.env.GWOP_CHECKOUT_API_KEY,
});
OptionTypeDefaultDescription
merchantApiKeystring—Merchant API key (sk_m_*). Required for create/list/cancel.
apiKeystring—Alias for merchantApiKey.
baseUrlstringhttps://agents.gwop.ioAPI base URL.
maxRetriesnumber2Max retries on 429/503/network errors.
timeoutnumber30000Request timeout in ms.
debugbooleanfalseLog requests to console.debug. Also enabled by env var GWOP_DEBUG=1.

​
Invoices

​
Create

const invoice = await gwop.invoices.create(
  {
    amount_usdc: 5_000_000,
    description: 'Pro plan — 1 month',
    metadata: { customer_id: 'cust_123' },
  },
  { idempotencyKey: 'order_abc_v1' },
);
Body:
FieldTypeRequiredDescription
amount_usdcnumberYesAmount in USDC minor units. 1_000_000 = $1.00.
descriptionstringNoHuman-readable description (max 500 chars).
metadataobjectNoArbitrary key-value pairs (max 1024 bytes).
metadata_publicbooleanNoExpose metadata in public invoice view.
expires_in_secondsnumberNoInvoice TTL (60–86400). Default: 900 (15 min).
Options: idempotencyKey?: string — safe retry key. Same key returns the original invoice. Returns: CreateInvoiceResponse — id, public_invoice_id, status: 'OPEN', expires_at, created_at.

​
Retrieve

Public endpoint — no API key needed. 
const invoice = await gwop.invoices.retrieve('inv_abc123');
Returns: InvoicePublic — full v3 response with payment_methods, pricing, completion_check, and links.

​
List

const { invoices, pagination } = await gwop.invoices.list({
  status: 'PAID',
  limit: 25,
});
ParamTypeDefaultDescription
statusstring—Filter: OPEN, PAYING, PAID, EXPIRED, CANCELED.
limitnumber20Results per page (1–100).
offsetnumber0Pagination offset.

​
Cancel

const result = await gwop.invoices.cancel('inv_abc123');
// result.status → 'CANCELED'
Only OPEN invoices can be canceled. Returns 409 if the invoice is already paid or in a non-cancellable state.

​
Wait for status

Poll until the invoice reaches a target status. Uses exponential backoff with jitter. 
const paid = await gwop.invoices.waitForStatus('inv_abc123', 'PAID', {
  timeoutMs: 60_000,  // max wait (default)
  intervalMs: 1_000,  // initial interval (default)
});
Accepts an array to wait for any terminal status: 
const terminal = await gwop.invoices.waitForStatus(
  'inv_abc123',
  ['PAID', 'EXPIRED', 'CANCELED'],
);
Throws GwopCheckoutError with code WAIT_TIMEOUT if the timeout is reached.

​
Webhooks

​
Construct event

Verify a webhook signature and parse the event. 
const event = gwop.webhooks.constructEvent(
  req.body.toString('utf8'),           // raw body — string or Buffer
  req.header('x-gwop-signature'),      // signature header
  process.env.GWOP_WEBHOOK_SECRET!,    // whsec_...
);
Throws InvalidRequestError with code WEBHOOK_SIGNATURE_ERROR on failure.

​
Dispatch

Route a verified event to typed handlers. 
await gwop.webhooks.dispatch(event, {
  invoicePaid: async (evt) => { /* fulfill order */ },
  invoiceExpired: async (evt) => { /* cancel pending order */ },
  invoiceCanceled: async (evt) => { /* cancel pending order */ },
  unhandled: async (evt) => { /* log unknown event */ },
});

​
Error handling

All errors extend GwopCheckoutError with code, statusCode, requestId, and details.
ClassStatusWhen
AuthenticationError401Missing or invalid API key.
InvalidRequestError400, 422Validation error or bad input.
NotFoundError404Invoice not found.
RateLimitError429Too many requests. Check details.retry_after_seconds.
GwopCheckoutError*Base class for all other errors.
import { GwopCheckoutError } from 'gwop-checkout';

try {
  await gwop.invoices.create({ amount_usdc: 5_000_000 });
} catch (err) {
  if (err instanceof GwopCheckoutError) {
    console.error(err.code, err.requestId, err.statusCode);
  }
}

​
Retries

The SDK retries automatically on transient failures (max 2 by default).
StatusRetried?Behavior
429YesRespects Retry-After header.
503YesExponential backoff with jitter.
Network errorYesRetries on TypeError from fetch.
400, 401, 404, 409NoThrows immediately.
After retries are exhausted, throws GwopCheckoutError with code MAX_RETRIES_EXCEEDED.