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.
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 pageimport { 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.
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": { ... }
}| 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.