Codex · III

Using the API

Use it without the buy button

The buy button is a convenience layer. Underneath, Coin Moebius is a rented webhook plus a few JSON endpoints. If you'd rather build your own UI, run your own checkout flow, or plug Coin Moebius into something the button can't handle (Square or Authorize.Net subscriptions, a custom payment form, a server-side script, a mobile app), every endpoint the button uses is also callable from anything. No code changes on our side.

Authenticating backend calls

Calls you make from your own server can carry your store's API key as a bearer token. Create a key in the dashboard, under your store's API keys (it starts with cmk_), and send it in the Authorization header:

Authorization: Bearer cmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key is tied to one store, and authenticated calls get a higher rate limit than anonymous ones. The buy button itself is public and needs no key. Keep your key on your server. Never put it in browser or other client-side code.

These endpoints all live under one base URL. In production that base is https://api.coinmoebius.com. The full URL for each is shown below (replace the {…} parts with your own values).

EndpointWhat it does
GET https://api.coinmoebius.com/api/projects/{projectId}/public-infoThe provider list the buy button renders: every payment method enabled on the store, each with only its public-safe fields (display label, publishable key, mailing address for pay-by-mail). Add ?productId=… to get per-product prices, ordering, and labels. No key needed. Responses come from an edge cache and can be up to a minute old; your own dashboard saves show up immediately.
POST https://api.coinmoebius.com/api/checkout/{provider}/{projectId}Start a checkout. POST { productId, metadata }; receive back whatever the provider needs (a redirect URL for Stripe, an approval URL for PayPal, a token for Authorize.Net Accept Hosted). Render it however you want.
POST https://api.coinmoebius.com/webhook/{provider}/{projectId}The provider posts here. We verify the signature, normalize the event, store it, count quota. Point the provider's webhook at this URL whether the original checkout came from our button or your own integration.
GET https://api.coinmoebius.com/status/{projectId}/{txId}Poll for the current state of a payment or subscription. Returns the same normalized shape the buy button gets.
POST https://api.coinmoebius.com/api/subscriptions/{projectId}/{subscriptionId}/portal-grantAsk for a short-lived grant for one subscription. Call it from your server with your API key. The grant lasts 10 minutes.
POST https://api.coinmoebius.com/api/subscriptions/{projectId}/{subscriptionId}/portal-urlGet the link to the provider's page for managing a subscription. It needs a grant from the portal-grant call first. Stripe and PayPal open the buyer's own page. Square and Authorize.Net open your account with them, so you make the change for the buyer.

Identify the buyer in your own system by passing metadata.customerRef on the checkout call. It threads through the provider and comes back on the transaction, so you can join Coin Moebius's records to your own user database without us storing anything about the buyer.

Why someone uses this path: a static-site builder who wants to write their own button to match their site's design and just needs the webhook handled. A developer who wants to skip the button entirely and call the API from their own server. A merchant who wants to run Square or Authorize.Net subscriptions and is fine wiring up card collection themselves. The button is a starting point. The API is the actual product.

Listening for buyer events

The element fires seven browser events. Listen with addEventListener on the element (or on document, the events bubble). In Angular that's (cm-busy)="onBusy($event)" right in the template, and React, Vue, and plain JavaScript bind the same way they bind any DOM event. All events are cancelable; what preventDefault() does is listed per event.

EventWhen it firesDetail payload
cm-busyA click started processing: the button has locked itself and shown its spinner. Cancel it to hide the built-in spinner and drive your own loading UI. The double-click lock always holds.Empty.
cm-load-providersThe button is about to ask the API for the list of providers configured on this store.Empty.
cm-checkout-startedThe buyer picked a provider and Coin Moebius is about to create a checkout session (Stripe / NOWPayments) or show the pay-by-mail preview. Cancel it to stop the checkout.{ provider }, the method's id, such as stripe, paypal, nowpayments or manual
cm-errorSomething failed: network error, signature failure, no provider configured. Cancel it to suppress the built-in error display and route the message into your own UI.{ error: Error }
cm-successA coin payment made inside the popup was confirmed.{ provider, paymentId }
cm-idleProcessing settled: the buyer was handed off to checkout, the popup opened, or an error surfaced. The paired end to cm-busy.Empty.
cm-closeThe buyer closed the payment popup.Empty.
document.addEventListener('cm-error', (event) => {
  console.error('Coin Moebius:', event.detail.error);
  // Show your own error UI, send to your analytics, etc.
});

cm-success fires only for a coin payment made inside the popup. With a hosted checkout (Stripe Checkout, NOWPayments invoice page), the buyer has left your page by the time the payment completes. They return to your site via the success URL you set for that provider (see The success and cancel URLs), and your server learns about the payment via the dashboard or by polling the /status endpoint.

Polling from your backend

For a server-side source of truth, poll GET /status/:projectId/:txId from your backend. The response shape:

{
  "kind": "payment",
  "contract": 1,
  "status": "success",
  "paymentId": "cs_live_a1B2c3D4e5F6g7H8",
  "provider": "stripe",
  "amount": 29.99,
  "currency": "USD",
  "metadata": {},
  "timestamp": 1778720661000
}

The status is one of success, pending, failed, refunded, disputed or partial. A pay-by-mail order that is still waiting shows as pending, and one that was canceled, expired or reversed shows as failed. The endpoint is unauthenticated but rate-limited to 60 requests / minute per IP. The transaction id you pass is what's shown in the dashboard's Order # column.

A typical pattern: when your success_url page loads, kick off a backend job that polls /status/:projectId/:txId every 15 seconds until it sees success (or failed / a timeout), then fulfill the order.

Ready to wire it up?

Get your first checkout working with the provider you already use. Follow the guide, paste the button, and run a test. No card needed to get started.