API Reference

Reference

Routes, object models, enums, settings, and error shapes.

Route reference

Method	Route	Auth	Use
GET	`/api/partner/v1/companies`	session	List user companiesReturn teams available to the signed-in MakeCrypto user for portal tooling.
POST	`/api/partner/v1/onboarding/company`	partner onboarding secret	Create company onboarding linkCreate 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`	MakePay API key	List payment linksReturn every MakePay payment link for the API key's company.
POST	`/api/partner/v1/makepay/payment-links`	MakePay API key	Create payment linkCreate a hosted MakePay checkout link and optional email request.
POST	`/gateway/pay/{makepayKeyId}`	public form key	Submit HTML payment formAccept browser form fields, create a hosted payment link, and redirect the customer to checkout.
GET	`/api/partner/v1/makepay/payment-links/{uid}`	MakePay API key	Get payment-link detailReturn one MakePay payment link with its latest session and timeline events.
PATCH	`/api/partner/v1/makepay/payment-links/{uid}`	MakePay API key	Update payment-link statusSet a payment link to active, paused, or archived.
POST	`/api/partner/v1/makepay/payment-links/{uid}/send-request-email`	MakePay API key	Send payment requestSend or resend the hosted payment link to a customer email address.
GET	`/api/partner/v1/makepay/subscriptions`	MakePay API key	List subscriptionsReturn recurring MakePay subscription schedules.
POST	`/api/partner/v1/makepay/subscriptions`	MakePay API key	Create subscriptionCreate a recurring MakePay subscription and first invoice.
GET	`/api/partner/v1/makepay/customers`	MakePay API key	List customersReturn MakePay customer profiles for the API key's company.
POST	`/api/partner/v1/makepay/customers`	MakePay API key	Upsert customerCreate or update a MakePay customer by email.
POST	`/api/partner/v1/makepay/customers/{customerId}/portal`	MakePay API key	Create customer portal linkGenerate a 24-hour signed MakePay customer portal URL on demand.
GET	`/api/partner/v1/timezones`	public	List timezonesReturn supported IANA timezone identifiers.
GET	`/api/partner/v1/makepay/settings`	MakePay API key	Read MakePay settingsRead settlement, redirect, fee, and underpayment settings.
PUT	`/api/partner/v1/makepay/settings`	MakePay API key	Update MakePay settingsUpdate settlement asset, product status, redirects, and fee policy.
GET	`/api/partner/v1/makepay/destination-assets`	MakePay API key	List destination assetsReturn supported settlement assets and the current default asset.
GET	`/api/partner/v1/makepay/webhook-requests`	MakePay API key	List webhook deliveriesInspect payment and subscription webhook delivery attempts and retry state.

Partner onboarding OAuth

POST /api/partner/v1/onboarding/company can include an optional oauth object. MakeCrypto validates the OAuth app, redirect URI, scopes, and PKCE challenge before creating the onboarding link. When the merchant completes onboarding, MakeCrypto creates the company, grants the OAuth app access to that company, and redirects to the registered redirectUri with an authorization code.

{
  "idempotencyKey": "merchant_123",
  "company": {
    "name": "Acme Markets",
    "website": "https://acme.example"
  },
  "oauth": {
    "clientId": "mco_app_example",
    "redirectUri": "https://apps.makecrypto.io/oauth/callback",
    "scope": "company:read makepay:payment-links:write makepay:settings:read",
    "state": "merchant_123",
    "codeChallenge": "PKCE_S256_CODE_CHALLENGE",
    "codeChallengeMethod": "S256"
  }
}

The partner app should keep the matching PKCE code_verifier and exchange the returned code through POST /oauth/token.

PaymentLink object

Field	Type	Notes
`id`	`string`	Internal UUID.
`uid`	`string`	Public payment-link identifier used in hosted and embedded checkout routes.
`status`	`"active" \| "paused" \| "archived"`	Merchant-managed link state.
`payload`	`PaymentLinkPayload`	Merchant order, amount, customer, redirect, metadata, branding, and runtime fields.
`created_at`	`string`	ISO timestamp.
`updated_at`	`string`	ISO timestamp.
`expires_at`	`string \| null`	Resolved expiration timestamp, or `null` for no expiration.
`publicUrl`	`string`	Hosted MakePay checkout URL, included on create, list, detail, and status update responses.

PaymentLinkPayload

Field	Type	Notes
`title`	`string`	Display label for the payment.
`description`	`string`	Customer-facing description.
`amount`	`string`	Decimal amount to collect.
`fiatCurrency`	`string`	Optional display currency such as `USD` or `EUR`.
`currency`	`string`	Settlement symbol such as `USDT`, `USDC`, or `BTC`.
`asset`	`string`	Exact destination asset identifier. Use this when a symbol exists on multiple chains.
`orderId`	`string`	Merchant order or invoice reference.
`customerEmail`	`string`	Used for email requests and webhook payloads.
`clientId`	`string`	Optional merchant-side customer identifier.
`returnUrl`	`string`	Merchant URL for generic return navigation.
`successUrl`	`string`	Merchant URL for completed payments.
`failureUrl`	`string`	Merchant URL for failed or cancelled payments.
`expirationTime`	`"15m" \| "1h" \| "12h" \| "24h" \| "72h" \| "never"`	Requested payment-link lifetime.
`metadata`	`Record<string, unknown>`	Merchant-defined metadata returned in dashboards and webhooks.
`runtimeMode`	`"merchant_target_net_v2"`	Injected by the API for new payment links.
`billingVersion`	`"v2"`	Injected by the API for new payment links.
`merchantName`	`string`	Injected from company branding when available.
`merchantPictureUrl`	`string`	Injected from company profile when available.
`merchantLogoUrl`	`string`	Injected from merchant branding when available.
`merchantPaymentLinkTheme`	`"light" \| "dark" \| "system"`	Injected from merchant checkout theme settings.

Customer object

Field	Type	Notes
`id`	`string`	Internal UUID.
`uid`	`string`	Public MakePay customer identifier used in portal links.
`email`	`string`	Customer email.
`name`	`string \| null`	Customer display name. Editable from the customer portal.
`clientId`	`string \| null`	Merchant-side customer identifier. Read-only in the portal.
`metadata`	`Record<string, unknown>`	Merchant-defined metadata.
`createdAt`	`string`	ISO timestamp.
`updatedAt`	`string`	ISO timestamp.
`urls`	`{ customerPortal: string }`	Present on portal generation responses. Do not persist this URL.

Customer portal response

POST /api/partner/v1/makepay/customers/{customerId}/portal returns a signed portal URL for the stored customer.

json

{
  "ok": true,
  "companyId": "acct_123",
  "customer": {
    "id": "b834dd77-69b8-41a9-a4b6-95bc9dd14c2d",
    "uid": "cus_01hzy4k6p4w9y2x7e2z7n8a2xm",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "clientId": "client_1042",
    "metadata": {
      "source": "api"
    },
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "urls": {
      "customerPortal": "https://makepay.io/billing?company=acct_123&customer=cus_01hzy4k6p4w9y2x7e2z7n8a2xm&expires=1776765600&signature=8d1f..."
    }
  },
  "expiresAt": "2026-04-21T10:00:00.000Z"
}

The URL is valid for 24 hours and uses the company's verified payment_link_domain when available. Otherwise it falls back to the MakePay public origin.

Query parameter	Notes
`company`	MakeCrypto company account ID that owns the customer.
`customer`	MakePay customer UID.
`expires`	Unix timestamp in seconds.
`signature`	HMAC signature over `v1:{companyId}:{customerUid}:{expires}`.

Generate portal links on demand when the customer opens billing. Expired, tampered, or cross-customer URLs are rejected before portal data is loaded.

Subscription object

Field	Type	Notes
`id`	`string`	Internal UUID.
`uid`	`string`	Merchant-facing subscription identifier.
`status`	`"active" \| "paused" \| "overdue" \| "cancelled"`	Current subscription state.
`customerEmail`	`string`	Customer email used for reminders and portal matching.
`label`	`string`	Customer-facing subscription label.
`description`	`string \| null`	Optional subscription description.
`amountUsd`	`string`	Recurring USD amount.
`settlementAsset`	`string`	Destination settlement asset identifier.
`cadence`	`"weekly" \| "biweekly" \| "monthly" \| "custom_months" \| "yearly"`	Display cadence.
`billingIntervalUnit`	`"week" \| "month" \| "year"`	Billing interval unit.
`billingIntervalCount`	`number`	Number of units between billing cycles.
`startAt`	`string`	ISO timestamp for the first billing cycle.
`timezone`	`string`	IANA timezone used for reminder timing.
`metadata`	`Record<string, unknown>`	Merchant-defined metadata and advanced redirect/tolerance settings.
`cycles`	`SubscriptionCycle[]`	Generated billing cycles returned by list routes and dashboard calls.

Subscriptions move to overdue when an unpaid cycle is at least 24 hours past its dueAt timestamp. MakePay sends a signed makepay.subscription.status_changed webhook whenever the subscription status changes.

MakePaySettings

Field	Type	Notes
`status`	`"active" \| "paused"`	Product availability for the team.
`defaultDestinationAsset`	`string \| null`	Default asset identifier used when payment links provide only `currency`.
`feePaidBy`	`"client" \| "merchant"`	Determines whether customer or merchant absorbs MakePay fees.
`returnRedirectUrl`	`string \| null`	Fallback redirect after checkout.
`successRedirectUrl`	`string \| null`	Redirect after completed payment.
`failureRedirectUrl`	`string \| null`	Redirect after cancelled or failed payment.
`underpaymentPercentEnabled`	`boolean`	Enables percentage tolerance.
`underpaymentPercentThreshold`	`number`	Allowed underpayment percentage.
`underpaymentFixedEnabled`	`boolean`	Enables fixed tolerance.
`underpaymentFixedThreshold`	`number`	Allowed fixed underpayment amount.

DestinationAsset

Field	Type	Notes
`assetIdentifier`	`string`	Canonical chain, symbol, and contract identifier.
`chainCode`	`string`	Settlement chain code.
`chainName`	`string`	Human-readable chain name.
`symbol`	`string`	Asset symbol.
`name`	`string`	Asset name.
`decimals`	`number`	Token decimals.
`isDefault`	`boolean`	Whether this asset is the current company default.

Status values

active: the link can be opened and paid.
paused: the link remains visible to the merchant but should not accept new payment starts.
archived: the link is hidden from active views and should be treated as closed.

Subscription status values:

active: the subscription is collecting scheduled invoices normally.
paused: reminders and merchant/customer changes have paused the subscription.
overdue: at least one unpaid cycle is 24 hours or more past its due date.
cancelled: the subscription is ended and unpaid generated cycles are cancelled.

Error shape

Errors return JSON with error and, when available, errorCode.

{
  "errorCode": "invalid_destination_asset",
  "error": "payload.asset ETH.USDT-... is not available for supported settlement routes."
}