API Reference

Payment links & anonymous API

Create API-key merchant links or no-key anonymous one-time MakePay payment links, then manage merchant links.

Routes

Use these routes to create and manage hosted MakePay payment links from MakeCrypto. The same create route also accepts anonymous one-time payment links when the request omits MakePay API key headers.

Need a no-account payment API? Start with anonymous one-time links: send a public payload with amount, settlement priorities, branding, and an optional webhook URL. No MakeCrypto workspace or API key is required.

Jump to anonymous payment API
MethodRoute
GET/api/partner/v1/companies

Auth

session

Use

List user companies

Return teams available to the signed-in MakeCrypto user for portal tooling.

POST/api/partner/v1/onboarding/company

Auth

partner onboarding secret

Use

Create company onboarding link

Create a partner-prefilled company onboarding draft and return a merchant claim URL. Include an oauth block to auto-connect a validated OAuth app after the merchant completes onboarding.

GET/api/partner/v1/makepay/payment-links

Auth

MakePay API key or OAuth

Use

List payment links

Return up to 200 newest merchant links: company-wide for API keys or limited to links created by the current OAuth grant. Anonymous links are excluded; pagination and filters are not currently available.

POST/api/partner/v1/makepay/payment-links

Auth

MakePay API key, OAuth, or public

Use

Create payment link

Create an API-key or OAuth merchant payment link, or omit authentication to create an anonymous one-time link.

POSThttps://www.makepay.io/api/public/anonymous-payment-links

Auth

public

Use

Create anonymous payment link

Public MakePay endpoint for one-time anonymous checkout links with explicit settlement priorities, branding, and optional webhooks.

POST/gateway/pay/{makepayKeyId}

Auth

public form key

Use

Submit HTML payment form

Accept browser form fields, create a hosted payment link, and redirect the customer to checkout.

GET/api/partner/v1/makepay/payment-links/{uid}

Auth

MakePay API key or OAuth

Use

Get payment-link detail

Return one MakePay payment link with its latest session and timeline events.

PATCH/api/partner/v1/makepay/payment-links/{uid}

Auth

MakePay API key or OAuth

Use

Update payment-link status

Set a payment link to active, paused, or archived.

POST/api/partner/v1/makepay/payment-links/{uid}/send-request-email

Auth

MakePay API key or OAuth

Use

Send payment request

Send or resend the hosted payment link to a customer email address.

GET/api/partner/v1/makepay/subscriptions

Auth

MakePay API key or OAuth

Use

List subscriptions

Return recurring MakePay subscription schedules.

POST/api/partner/v1/makepay/subscriptions

Auth

MakePay API key or OAuth

Use

Create subscription

Create a recurring MakePay subscription and first invoice.

GET/api/partner/v1/makepay/customers

Auth

MakePay API key or OAuth

Use

List customers

Return MakePay customer profiles for the authenticated company.

POST/api/partner/v1/makepay/customers

Auth

MakePay API key or OAuth

Use

Upsert customer

Create or update a MakePay customer by email.

POST/api/partner/v1/makepay/customers/{customerId}/portal

Auth

MakePay API key or OAuth

Use

Create customer portal link

Generate a 24-hour signed MakePay customer portal URL on demand.

GET/api/partner/v1/timezones

Auth

public

Use

List timezones

Return supported IANA timezone identifiers.

GET/api/partner/v1/makepay/settings

Auth

MakePay API key or OAuth

Use

Read MakePay settings

Read settlement, redirect, fee, checkout policy, and underpayment settings.

PUT/api/partner/v1/makepay/settings

Auth

MakePay API key or OAuth

Use

Update MakePay settings

Update settlement asset, product status, redirects, fee policy, and checkout policy.

GET/api/partner/v1/makepay/destination-assets

Auth

MakePay API key or OAuth

Use

List destination assets

Return supported settlement assets and the current default asset.

GET/api/partner/v1/makepay/webhook-requests

Auth

MakePay API key or OAuth

Use

List webhook deliveries

Inspect payment and subscription webhook delivery attempts and retry state.

GET/api/partner/v1/makepay/webhook-subscriptions/current

Auth

grant-bound OAuth

Use

Read current webhook subscription

Read the webhook subscription owned by the current OAuth grant without revealing its signing secret.

PUT/api/partner/v1/makepay/webhook-subscriptions/current

Auth

grant-bound OAuth

Use

Create or update webhook subscription

Create, reactivate, update, or explicitly rotate the current OAuth grant's MakePay payment webhook subscription.

DELETE/api/partner/v1/makepay/webhook-subscriptions/current

Auth

grant-bound OAuth

Use

Disable current webhook subscription

Disable the current OAuth grant's webhook subscription and erase its stored signing secret.

Create a payment link

The create route inserts a MakePay payment link, resolves merchant branding and settlement defaults, injects runtime billing fields, and returns the public checkout URL.

POST /api/partner/v1/makepay/payment-links
json
{
  "status": "active",
  "sendPaymentRequestEmail": false,
  "payload": {
    "title": "Website order #1042",
    "description": "Checkout for order #1042",
    "amount": "129.99",
    "fiatCurrency": "USD",
    "currency": "USDT",
    "feePaidBy": "merchant",
    "skipQuoteAcceptance": true,
    "lineItems": [
      {
        "id": "plan",
        "name": "Starter package",
        "unitAmount": "119.99",
        "quantity": 1
      }
    ],
    "extraCharges": [
      {
        "id": "shipping",
        "name": "Shipping",
        "kind": "shipping",
        "unitAmount": "10.00",
        "quantity": 1
      }
    ],
    "optionalItems": [
      {
        "id": "priority_setup",
        "name": "Priority setup",
        "unitAmount": "19.99",
        "quantity": 1,
        "adjustableQuantity": {
          "enabled": true,
          "minimum": 1,
          "maximum": 3
        }
      }
    ],
    "orderId": "order_1042",
    "customerEmail": "buyer@example.com",
    "invoicePdfUrl": "https://merchant.example/invoices/1042.pdf",
    "returnUrl": "https://merchant.example/orders/1042",
    "successUrl": "https://merchant.example/orders/1042/success",
    "failureUrl": "https://merchant.example/orders/1042/failure",
    "expirationTime": "12h",
    "metadata": {
      "cartId": "cart_7M2V",
      "source": "api"
    }
  }
}

For a no-code or low-code browser checkout button, see Form submit payment. It accepts a plain HTML POST, creates the same kind of hosted payment link, and redirects the shopper to MakePay checkout.

Required setup

The company must have a MakePay default destination asset. If settlement is not configured, the route returns 409 with errorCode: "onboarding_required".

Amount and asset fields

Use payload.amount for the customer-facing amount. Pass either payload.asset for an exact destination asset or payload.currency when the company's default destination asset can resolve the chain. If a currency is enabled on multiple chains and no matching company default exists, pass payload.asset explicitly.

Fee payer override

Merchant settings define the default fee payer for new MakePay checkouts. Add payload.feePaidBy to override that default for a single payment link. Use "client" when the payer should cover MakePay fees at checkout, or "merchant" when the merchant should absorb the fees and keep the customer-facing amount unchanged.

{
  "payload": {
    "amount": "129.99",
    "currency": "USDT",
    "feePaidBy": "merchant"
  }
}

Checkout quote review override

Merchant settings define whether MakePay skips the payer-facing quote Review step by default. Add payload.skipQuoteAcceptance to force a behavior for one payment link. Use true to accept the first valid quote and go directly to Transfer after the payer completes Contact, Method, and any Refund Address step. Use false to require the Review step. Omit the field to inherit the merchant default. payload.skip_quote_acceptance is accepted as an input alias; API responses use skipQuoteAcceptance.

To clear an existing per-link override, send skipQuoteAcceptance: null in the payment-link PATCH payload.

{
  "payload": {
    "amount": "129.99",
    "currency": "USDT",
    "skipQuoteAcceptance": false
  }
}

Itemized checkout fields

For one-time links, you can replace or verify payload.amount with itemized checkout fields:

  • payload.lineItems for required product or service rows.
  • payload.extraCharges for shipping, customs, tax, handling, or other order charges.
  • payload.optionalItems for payer-selectable add-ons.
  • payload.discounts for order-level discounts.

Each item supports id, name, description, kind, sku, productCode, productUid, variantUid, unitAmount, quantity, taxAmount, discountAmount, metadata, and adjustableQuantity. When line items are present and payload.amount is omitted, MakePay derives the base total. When both are present, payload.amount must match the base total. Optional items and adjustable quantities are validated and priced again when the payer requests a quote, so clients cannot send arbitrary final totals.

{
  "payload": {
    "title": "Order #1042",
    "fiatCurrency": "USD",
    "currency": "USDT",
    "lineItems": [
      {
        "id": "seats",
        "name": "Additional seats",
        "unitAmount": "25.00",
        "quantity": 2,
        "adjustableQuantity": {
          "enabled": true,
          "minimum": 1,
          "maximum": 10
        }
      }
    ],
    "extraCharges": [
      {
        "id": "shipping",
        "name": "Shipping",
        "kind": "shipping",
        "unitAmount": "10.00",
        "quantity": 1
      }
    ],
    "optionalItems": [
      {
        "id": "setup",
        "name": "Priority setup",
        "unitAmount": "100.00",
        "quantity": 1
      }
    ]
  }
}

Embedded or custom checkout clients send the payer's allowed selection when requesting a quote. MakePay recalculates the amount from the stored payment-link payload; do not send a client-computed total.

POST https://www.makepay.io/api/public/payment-links/{uid}/quote-payin

{
  "sellAsset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
  "receiptEmail": "buyer@example.com",
  "lineItemSelection": {
    "quantities": {
      "seats": 4
    },
    "optional": [
      {
        "id": "setup",
        "quantity": 1
      }
    ]
  }
}

Expiration

payload.expirationTime accepts 15m, 1h, 12h, 24h, 72h, or never. The API stores the resolved expires_at timestamp on the payment link.

Invoice PDF evidence

Pass payload.invoicePdfUrl when the payment already has an external invoice PDF. Merchant payment-link details show an Invoice button for that URL. When a payment link is generated from a MakeCrypto bookkeeping invoice, the detail view uses the private bookkeeping invoice PDF automatically.

Idempotent mutations

Send Idempotency-Key when creating or updating a merchant payment link. X-Idempotency-Key remains accepted as a compatibility alias. A key must be 8 to 200 characters and can contain letters, numbers, ., _, ~, :, +, /, =, or -.

Keys are isolated by company and authenticated API-key actor or OAuth grant. A second request with the same key, method, path, and canonical JSON body replays the stored status/body and adds:

Idempotent-Replayed: true

Reusing a key with a different request returns 409 with errorCode: "idempotency_key_reused". A concurrent request that has not finished returns 409 with errorCode: "idempotency_request_in_progress". MakePay retains mutation records for seven days and reconciles an ambiguous completed database write from the payment link's mutation marker. Keep each key stable across transport retries, but create a new key for a deliberate new mutation.

Create response

json
{
  "ok": true,
  "companyId": "8d15bb78-d0f8-45ef-88d7-2a1f1f79644b",
  "paymentRequestEmailSent": false,
  "paymentRequestEmailError": null,
  "paymentLink": {
    "id": "3a85f64-5717-4562-b3fc-2c963f66afa6",
    "uid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "donation_slug": null,
    "link_type": "one_time",
    "source": "api",
    "status": "active",
    "amount": "129.99",
    "fiatAmount": "129.99",
    "fiatCurrency": "USD",
    "currency": "USDT",
    "asset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
    "title": "Website order #1042",
    "label": "Website order #1042",
    "description": "Checkout for order #1042",
    "orderId": "order_1042",
    "customerEmail": "buyer@example.com",
    "clientId": null,
    "metadata": {
      "source": "api"
    },
    "payload": {
      "title": "Website order #1042",
      "description": "Checkout for order #1042",
      "amount": "129.99",
      "fiatCurrency": "USD",
      "currency": "USDT",
      "asset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "runtimeMode": "merchant_target_net_v2",
      "billingVersion": "v2",
      "merchantName": "Merchant Co",
      "merchantPaymentLinkTheme": "system",
      "customerEmail": "buyer@example.com",
      "orderId": "order_1042",
      "skipQuoteAcceptance": true,
      "metadata": {
        "source": "api"
      }
    },
    "latestSession": null,
    "timelineEvents": [],
    "publicUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "created_at": "2026-04-19T00:00:00.000Z",
    "updated_at": "2026-04-19T00:00:00.000Z",
    "expires_at": "2026-04-19T12:00:00.000Z",
    "dashboardUrl": "https://www.makecrypto.io/home/makepay/payment-links?orderUid=01hzy4k6p4w9y2x7e2z7n8a2xm"
  }
}

Create an anonymous one-time payment link

Anonymous links are for one-off hosted checkout pages that are not attached to a MakeCrypto merchant workspace. Send the same create request without x-makecrypto-key-id or x-makecrypto-key-secret; if credential headers are present and invalid, the API treats the request as an authenticated attempt and returns 401.

POST /api/partner/v1/makepay/payment-links
json
{
  "amount": "129.99",
  "fiatCurrency": "USD",
  "title": "Anonymous order #1042",
  "description": "One-time hosted MakePay checkout",
  "customerEmail": "buyer@example.com",
  "settlement": {
    "currency": "USDT",
    "priorities": [
      {
        "chain": "TRON",
        "address": "TMerchantSettlementAddress"
      },
      {
        "chain": "ETH",
        "address": "0xMerchantSettlementAddress"
      }
    ]
  },
  "returnUrl": "https://merchant.example/orders/1042",
  "successUrl": "https://merchant.example/orders/1042/success",
  "failureUrl": "https://merchant.example/orders/1042/failure",
  "expirationTime": "24h",
  "webhookUrl": "https://merchant.example/webhooks/makepay",
  "branding": {
    "name": "Merchant Co",
    "logoUrl": "https://merchant.example/logo.png",
    "brandColor": "#0f766e",
    "accentColor": "#111827",
    "theme": "system"
  },
  "metadata": {
    "cartId": "cart_7M2V",
    "source": "anonymous-api"
  }
}

You can also call the MakePay public proxy from MakePay-hosted pages:

POST https://www.makepay.io/api/public/anonymous-payment-links

Anonymous setup

Anonymous one-time links require either amount or itemized checkout rows, plus a settlement block with currency and at least one settlement priority. Each priority contains the chain and the merchant-controlled settlement address for completed payments. The checkout collects the payer refund address when the payer selects a pay-in network, so do not send source-chain refund addresses in the create request.

Display currency and settlement

Use fiatCurrency or displayCurrency for the customer-facing display currency. Use settlement.currency for the asset family you want to receive, such as USDT, USDC, or BTC. If a settlement symbol is available on several chains, order settlement.priorities by preferred chain so MakePay can resolve the default destination asset and fallback routes.

Anonymous webhooks

Pass webhookUrl to receive MakePay webhook events for the anonymous payment link. When a webhook URL is present, the create response returns paymentLink.webhook.secret once; store it immediately and use it to verify future webhook signatures.

Anonymous links are intentionally limited: they are not returned by merchant list APIs, cannot be paused or archived later, and are subject to public creation rate limits.

curl
curl -X POST "https://www.makecrypto.io/api/partner/v1/makepay/payment-links" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "129.99",
  "fiatCurrency": "USD",
  "title": "Anonymous order #1042",
  "description": "One-time hosted MakePay checkout",
  "customerEmail": "buyer@example.com",
  "settlement": {
    "currency": "USDT",
    "priorities": [
      {
        "chain": "TRON",
        "address": "TMerchantSettlementAddress"
      },
      {
        "chain": "ETH",
        "address": "0xMerchantSettlementAddress"
      }
    ]
  },
  "returnUrl": "https://merchant.example/orders/1042",
  "successUrl": "https://merchant.example/orders/1042/success",
  "failureUrl": "https://merchant.example/orders/1042/failure",
  "expirationTime": "24h",
  "webhookUrl": "https://merchant.example/webhooks/makepay",
  "branding": {
    "name": "Merchant Co",
    "logoUrl": "https://merchant.example/logo.png",
    "brandColor": "#0f766e",
    "accentColor": "#111827",
    "theme": "system"
  },
  "metadata": {
    "cartId": "cart_7M2V",
    "source": "anonymous-api"
  }
}'

Anonymous create response

json
{
  "ok": true,
  "anonymous": true,
  "paymentRequestEmailSent": false,
  "paymentRequestEmailError": null,
  "paymentLink": {
    "id": "8d15bb78-d0f8-45ef-88d7-2a1f1f79644b",
    "uid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "status": "active",
    "link_type": "one_time",
    "publicUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "expiresAt": "2026-04-20T00:00:00.000Z",
    "expires_at": "2026-04-20T00:00:00.000Z",
    "created_at": "2026-04-19T00:00:00.000Z",
    "updated_at": "2026-04-19T00:00:00.000Z",
    "payload": {
      "amount": "129.99",
      "type": "one_time",
      "fiatCurrency": "USD",
      "displayCurrency": "USD",
      "currency": "USDT",
      "asset": "TRON.USDT",
      "runtimeMode": "merchant_target_net_v2",
      "billingVersion": "v2",
      "merchantName": "Merchant Co",
      "merchantPaymentLinkTheme": "system"
    },
    "settlement": {
      "currency": "USDT",
      "defaultDestinationAsset": "TRON.USDT",
      "priorities": [
        {
          "chain": "TRON",
          "assetIdentifier": "TRON.USDT",
          "address": "TMerchantSettlementAddress"
        },
        {
          "chain": "ETH",
          "assetIdentifier": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
          "address": "0xMerchantSettlementAddress"
        }
      ],
      "sourceAddresses": []
    },
    "branding": {
      "name": "Merchant Co",
      "logoUrl": "https://merchant.example/logo.png",
      "brandColor": "#0f766e",
      "accentColor": "#111827",
      "theme": "system"
    },
    "webhook": {
      "url": "https://merchant.example/webhooks/makepay",
      "secret": "mkwhsec_8d1f...",
      "secretLast4": "d1f0"
    }
  },
  "requestId": "5f31fb28-1a6c-4d57-b765-e32fb9b7b3e0"
}

List payment links

Use the list route for back-office reconciliation, dashboards, and smoke tests.

The current route returns at most the newest 200 merchant links, ordered by creation time. API-key authentication sees company-owned links; OAuth sees only links created by the current grant, which prevents one connected store from reading another store's links. The route does not currently accept pagination, search, status, or source filters. Anonymous links are never included. Persist a returned UID and use the detail route when an older known link is outside this list window.

curl
curl "https://www.makecrypto.io/api/partner/v1/makepay/payment-links" \
  -H "x-makecrypto-key-id: MAKEPAY_API_KEY_ID" \
  -H "x-makecrypto-key-secret: MAKEPAY_API_SECRET" \
  -H "Accept: application/json"

Get payment-link detail

Use the detail route when you already have a payment-link UID and need the normalized link, public checkout URL, latest payment session, and timeline events.

curl
curl "https://www.makecrypto.io/api/partner/v1/makepay/payment-links/PAYMENT_LINK_UID" \
  -H "x-makecrypto-key-id: MAKEPAY_API_KEY_ID" \
  -H "x-makecrypto-key-secret: MAKEPAY_API_SECRET" \
  -H "Accept: application/json"

Pause or archive a payment link

Use the status route to stop a link from being paid, hide it from active operations, or add/remove the invoice PDF URL shown in merchant payment details.

curl
curl -X PATCH "https://www.makecrypto.io/api/partner/v1/makepay/payment-links/PAYMENT_LINK_UID" \
  -H "x-makecrypto-key-id: MAKEPAY_API_KEY_ID" \
  -H "x-makecrypto-key-secret: MAKEPAY_API_SECRET" \
  -H "Idempotency-Key: order_1042_update_v1" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

status must be active, paused, or archived. To attach an invoice PDF URL to an existing payment link, send:

{
  "invoicePdfUrl": "https://merchant.example/invoices/1042.pdf"
}

Send a payment request email

MakeCrypto can send the hosted link directly to the customer email on the payment-link payload, or to an override email in the request body.

curl
curl -X POST "https://www.makecrypto.io/api/partner/v1/makepay/payment-links/PAYMENT_LINK_UID/send-request-email" \
  -H "x-makecrypto-key-id: MAKEPAY_API_KEY_ID" \
  -H "x-makecrypto-key-secret: MAKEPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"buyer@example.com"}'

Only active payment links can be emailed. Completed payment links cannot be resent.

Need partner setup help?

Open the payment link details view in MakeCrypto to copy the generated snippets for a real payment UID, or return to the portal to manage merchant settings.

Open portal