Quickstart

Get your API keys

Your account manager provisions a test key pair (pk_test_… and sk_test_…) during onboarding — the secret key is shown once at creation, so store it in a password manager or your secrets store right away. Lost it? Ask us to rotate; the old key stops working immediately.

Every request authenticates with HTTP Basic Auth using <public_key>:<secret_key>. See Authentication for the full reference, including how to send the header in each language and how live keys differ from test keys.

Make a test charge

Send POST /payments with an amount, currency, your customer's email, a returnUrl for after they finish payment, and a callbackUrl so we know where to deliver the webhook. If you omit callbackUrl, no webhook is sent — it's configured per request, not globally on your account.

curl https://sandbox.mintcash.me/payments \
  -u "pk_test_xxx:sk_test_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "order_001",
    "amount": 4999,
    "currency": "USD",
    "returnUrl": "https://your-shop.example/order/complete",
    "callbackUrl": "https://your-shop.example/webhooks/mintcash",
    "customer": {
      "externalId": "cust_42",
      "email": "buyer@example.com",
      "name": "Jane Doe"
    }
  }'

const auth = Buffer.from(`${publicKey}:${secretKey}`).toString("base64");

const r = await fetch("https://sandbox.mintcash.me/payments", {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: "order_001",
    amount: 4999,
    currency: "USD",
    returnUrl: "https://your-shop.example/order/complete",
    callbackUrl: "https://your-shop.example/webhooks/mintcash",
    customer: {
      externalId: "cust_42",
      email: "buyer@example.com",
      name: "Jane Doe",
    },
  }),
});

const { payment, redirectUrl } = await r.json();

import httpx

r = httpx.post(
    "https://sandbox.mintcash.me/payments",
    auth=(public_key, secret_key),
    json={
        "externalId": "order_001",
        "amount": 4999,
        "currency": "USD",
        "returnUrl": "https://your-shop.example/order/complete",
        "callbackUrl": "https://your-shop.example/webhooks/mintcash",
        "customer": {
            "externalId": "cust_42",
            "email": "buyer@example.com",
            "name": "Jane Doe",
        },
    },
)
payment = r.json()

You'll get back a payment object plus a redirectUrl. The customer's status is created and we're waiting for them to land on the payment page.

Redirect the customer

In your application, send the customer to the redirectUrl returned above. They'll see the hosted payment page, fill in their card, and submit. After the provider confirms, they bounce to your returnUrl.

Use a sandbox card from the test cards reference — pick the happy-path success card with any future expiry and any CVV to complete this walkthrough. The same page lists cards for every failure mode you might want to exercise next.

Listen for the webhook

When the charge settles, MintCash sends an HMAC-signed webhook to the callbackUrl you passed in step 2.

{
  "eventId": "01HXXXXXXXX",
  "event": "payment.succeeded",
  "type": "payment",
  "apiVersion": "2026-05-01",
  "environment": "test",
  "createdAt": "2026-05-22T10:14:32.412Z",
  "data": {
    "id": "pmt_...",
    "externalId": "order_001",
    "status": "succeeded",
    "amount": 49.99,
    "currency": "USD"
  }
}

You should:

1. Verify the x-signature header before doing anything else — see signature verification.
2. Look up the order by data.externalId (the value you sent in step 1).
3. Fulfil the order — grant credits, ship the goods, mark the invoice paid.

That's it. You've taken your first payment.