Reference

Route reference

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

PaymentLinkPayload

Contact object

Bookkeeping counterparties are also contacts. A contact can be a customer, vendor, or both, and expense creation searches the same contact list used by payment links and subscriptions.

Bookkeeping wallet activity

Outgoing chain transfers can be saved from the wallet activity detail modal. When bookkeeping details are saved for an outgoing transfer, MakeCrypto creates or updates one expense for that wallet activity, reconciles it through walletActivityEventId, and carries any private invoice or receipt files linked to the transfer into the expense evidence view. Re-saving the same transfer is idempotent and updates the paired expense instead of creating a duplicate.

Expense detail pages show the saved bookkeeping fields, attached files, reconciliation links, and paired chain-transfer details. The same createBookkeepingExpenseFromActivity API accepts either walletActivityEventId or walletActivityEventKey for server-side workflows.

Customer portal response

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

{
  "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.

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

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

DestinationAsset

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."
}