Getting started

Quickstart

Go from zero to a working checkout in five minutes. You need an API key and a product.

Get an API key

In the dashboard, open Settings → API keys, click Create key, and copy the value. Keys are prefixed mrd_test_… (test mode) or mrd_live_… (live mode). The mode is fixed at creation. Keys are shown once, so store yours in a secret manager.

Create a product

From Products, click New product, set a price, publish. Copy the product UUID from the URL. You'll paste it into the next step.

Install the SDK

Type-safe TypeScript client. Skip if you'd rather hit the REST API directly.

bash

bun add @meridapay/sdk
# or: npm i @meridapay/sdk

Create a checkout from your backend

Call POST /checkouts. The response includes a url you redirect the buyer to.

import { createMeridaClient } from "@meridapay/sdk"

const merida = createMeridaClient({ apiKey: process.env.MERIDA_API_KEY! })

const { data, error } = await merida.POST("/checkouts", {
  body: {
    product_id: "<your-product-uuid>",
    customer_email: "[email protected]",
    external_customer_id: "user_123",
    success_url: "https://app.example.com/thanks",
  },
})

if (error) throw new Error(error.error.message)
return Response.redirect(data.url)

Or with curl:

bash

curl -X POST https://api.meridapay.com/checkouts \
  -H "Authorization: Bearer $MERIDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "<your-product-uuid>",
    "customer_email": "[email protected]",
    "external_customer_id": "user_123",
    "success_url": "https://app.example.com/thanks"
  }'

201 response:

json

{
  "id": "e7b5…",
  "url": "https://pay.meridapay.com/abc123XYZ",
  "product_id": "<your-product-uuid>",
  "customer_email": "[email protected]",
  "external_customer_id": "user_123",
  "amount": "29.00",
  "currency": "USD",
  "status": "active",
  "type": "one_time"
}

Or open the checkout as an embed overlay

Mint the checkout URL from your backend (as in step 4), then drop it into an anchor on your page. The embed script opens the checkout in an iframe over your page, no full redirect required.

html

<!-- href value comes from your POST /checkouts response -->
<a href="https://pay.meridapay.com/<token>"
   data-merida-checkout
   data-merida-checkout-theme="light"
   data-merida-brand-color="#214fd8">
  Subscribe
</a>

javascript

import { embed } from "@meridapay/sdk/embed"

const merida = await embed()
merida.attach()

See Embedded overlay for the full attribute list, event callbacks, theming, and the no-build <script> alternative.

Handle the webhook

Add a webhook endpoint in Settings → Webhooks. When the buyer pays, we POST a signed payment.succeeded event to your URL. Verify the signature, then fulfil the order. Full payload + Node/Python verification samples in Webhooks.

Next up

Authentication →