Skip to content

Sell with one API call

Create a checkout from your server. Send the buyer to it, or embed it in your page. Deliver the product when the payment webhook arrives. Tax, invoices and receipts happen on our side.

What the API does

Checkouts
Create a checkout for a product from your server, prefilled with the buyer's email or country.
Payment links
A fixed link per product, https://checkout.merquay.com/buy/{product_id}, with no code at all.
Embedded checkout
Show the checkout inside your own page. It runs in a frame your page can't read or change.
Refunds
Refund a payment in full or in part, within 30 days of it; later refunds go through our support team. A credit note is issued automatically.
Subscriptions
Cancel now or at the period end, undo a scheduled cancellation, move the billing date.
Customer portal
Buyers see their payments, subscriptions, license keys and downloads in one place.

Create a checkout

One product per checkout. The response holds the checkout's url, valid for 24 hours.

Your server
const response = await fetch("https://api.merquay.com/v1/checkouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": order.id,
  },
  body: JSON.stringify({
    product_id: "prd_...",
    customer_email: "buyer@example.com",
    success_url: "https://your-site.com/thanks",
  }),
});
const checkout = await response.json();
// checkout.url: send the buyer there, or embed it in your page
Your page (optional: embedded checkout)
import { checkout } from "https://checkout.merquay.com/embed/v1.mjs";

const frame = checkout.mount("#pay", checkoutUrl, {
  theme: "auto",
  onEvent(event) {
    if (event.type === "success") showThankYou();
  },
});

The success event in the page is for your interface only. Anyone can fake events in their own browser, so deliver the product from the payment.succeeded webhook.

Webhooks

Signed events, sent to up to 10 endpoints per project, for every event or the ones you choose.

Every event is signed following the Standard Webhooks specification: an HMAC-SHA256 of the event id, timestamp and body, with your endpoint's secret. Check it, and use webhook-id to ignore duplicates: it stays the same on every retry.

A delivery that fails is tried again, up to 8 attempts over about a day. You can also send a test event from the dashboard.

An event
POST https://your-site.com/webhooks
webhook-id: evt_...
webhook-timestamp: 1763380800
webhook-signature: v1,<signature>

{
  "id": "evt_...",
  "object": "event",
  "type": "payment.succeeded",
  "created_at": "...",
  "organization_id": "org_...",
  "project_id": "...",
  "request": { "id": "...", "idempotency_key": "..." },
  "data": { ... }
}
Webhook events
Event
payment.succeededA payment succeeded. Deliver the product from this event.
payment.failedA payment attempt failed.
payment.updatedThe buyer edited their billing details.
refund.succeededA refund reached the buyer.
refund.failedA refund could not be completed.
dispute.openedA buyer disputed a payment with their bank.
dispute.wonThe dispute was won.
dispute.lostThe dispute was lost.
checkout.expiredA checkout was not paid in time.
subscription.createdA new subscription started.
subscription.updatedA period renewed, or a cancellation was scheduled or undone.
subscription.past_dueA renewal failed. Retries are running.
subscription.activeA past-due subscription was paid again.
subscription.canceledThe subscription ended.

Test mode

A separate sandbox with its own accounts, data and API keys. Nothing in it touches live sales.

  • Open it from the dashboard. It needs no verification and no bank account.
  • Test payments run the whole flow: checkout, receipt, invoice and webhooks.
  • Invoices carry a test watermark and are not valid tax documents.
  • Test helpers open and close disputes and decide how the next renewal goes.

Conventions

Authentication
API keys sent as a Bearer token. Separate test and live keys.
Idempotency
Send an Idempotency-Key header on any POST: a retry with the same key returns the first result.
IDs
Prefixed by type: prd_, cus_, sub_, evt_ and so on.
Errors
One JSON shape with a stable code, a message and the parameter at fault.
Pagination
Cursor based: limit, starting_after and ending_before.
Versioning
The version is in the URL: /v1.

The full API reference is available on request: sales@merquay.com.

Start building in the sandbox

Apply to sell, and test the whole flow while we verify your business.