OAuth applications

Developer portal

Create and manage partner applications at https://apps.makecrypto.io. Applications belong to a MakeCrypto company and define the redirect URIs, allowed OAuth scopes, webhooks, icon, support contact, privacy policy, and terms shown during consent.

Each confidential application has a client secret. The secret is shown once when it is created or rotated, then stored only as a hash. Public applications must use PKCE and do not receive a secret.

Authorization Code with PKCE

MakeCrypto supports delegated company OAuth for partner applications. Start the flow by sending the user to the authorization endpoint with an exact registered redirect URI and a PKCE S256 challenge.

GET https://www.makecrypto.io/oauth/authorize
  ?response_type=code
  &client_id=mco_app_...
  &redirect_uri=https%3A%2F%2Fpartner.example%2Fcallback
  &scope=company%3Aread%20makepay%3Apayment-links%3Aread
  &resource=https%3A%2F%2Fmakecrypto.io%2Fapi%2Fpartner%2Fv1
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256

The user chooses the company, reviews the requested permissions, and approves or rejects access. If approval succeeds, MakeCrypto redirects back with a short lived authorization code.

Exchange the code at the token endpoint. Confidential clients authenticate with client_secret_basic or client_secret_post; public clients authenticate with their client_id and PKCE verifier.

POST https://www.makecrypto.io/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code
&code=mco_code_...
&redirect_uri=https%3A%2F%2Fpartner.example%2Fcallback
&code_verifier=ORIGINAL_PKCE_VERIFIER

Access tokens are short-lived JWT bearer tokens. Refresh tokens rotate on every use, and refresh-token reuse revokes the token family.

The production issuer, authorization server, token endpoint, native-registration origin, and API request origin are https://www.makecrypto.io. Call that canonical request origin directly. The stable OAuth protected-resource identifier remains https://makecrypto.io/api/partner/v1; a resource identifier does not have to share the authorization server's origin. The apex request host redirects to www, but a DPoP proof is bound to its exact method and URL and must not be reused after an origin-changing redirect.

Official native integrations, such as the MakePay WordPress and Medusa plugins, do not use the developer portal or a shared client secret. They register a per-store public installation at POST /oauth/native/installations, use exact callback URI matching, and receive DPoP-bound tokens that must be sent with Authorization: DPoP and a matching DPoP proof header.

Native registration itself requires DPoP, signed by the submitted key. If an existing installation changes its JWK thumbprint, the request also requires DPoP-Previous, signed by the key currently registered for that installation. Official template branding is server-controlled; a caller cannot replace an official app's name or icon through registration metadata. Platform metadata can include the installed plugin and platform versions for support and Connected Apps display.

Native connectors must durably save a proposed replacement private key before submitting a rotation registration. Registration does not revoke the existing grant, so abandoning the subsequent consent screen leaves the old DPoP-bound token family usable. Completing consent promotes the new grant binding and revokes the complete old access and refresh-token family. If the proposed key is lost after registration but before consent, retain the old connection: the still-accepted previous key can prove possession and register another replacement. MakeCrypto support is needed only when no accepted installation key remains available; never delete usable local credentials as a recovery step.

Official Medusa installations have no inactivity expiry. Their access tokens are short-lived, but the rotating refresh-token family remains renewable after more than 30 days without a request and the host plugin persists each rotation atomically. An access-token expiry is the next renewal time, not a disconnected state. Explicit disconnect, revocation, security reset, refresh-token reuse, or loss of the complete refresh family still terminates OAuth API access. Other OAuth application templates retain their configured refresh-token lifetime.

For the immutable official Medusa integration, ending OAuth API access also prevents new payment links from being associated with that installation, but does not cancel payments already issued. A separately encrypted, historical-only webhook credential may continue to verify exact late or redelivered payment-status callbacks for those existing payments. It cannot be used for API requests or new checkouts. See the MakePay webhook guide for the strict correlation rules and retention requirements.

The Medusa plugin requests only company:read, payment-link read/write, and webhook read/write. It does not request wallet-send, API-key management, customer, subscription, or global settings permissions.

Official SDKs

Use the official SDKs when you want a server-side integration without building the HTTP client, payment-link payloads, and webhook signature verification from scratch.

SDK	Use it for	Guide
MakePay PHP SDK	PHP, Laravel, Symfony, custom checkout, and backend payment-link creation.	PHP SDK
MakePay Go SDK	Go services, background workers, custom APIs, and signed webhook handlers.	Go SDK
MakePay Python SDK	Python, Django, Flask, FastAPI, workers, and server-side webhook handlers.	Python SDK
MakePay NPM SDK	Node.js, Next.js, TypeScript backends, and server-side webhook handlers.	NPM SDK
MakePay Rust SDK	Rust services, workers, CLIs, and server-side webhook verification.	Rust SDK
MakePay Java SDK	Java, Spring, Micronaut, Quarkus, JVM backends, and signed webhook handlers.	Java SDK
MakePay Swift SDK	Swift server backends, Vapor services, Apple-platform teams, and webhook verification.	Swift SDK

Endpoints

Purpose	Endpoint
Authorization	GET /oauth/authorize
Token exchange	POST /oauth/token
Revocation	POST /oauth/revoke
Introspection	POST /oauth/introspect
Pushed authorization request	POST /oauth/par
Native installation registration	POST /oauth/native/installations
JWKS	GET /oauth/jwks.json
Authorization server metadata	GET /.well-known/oauth-authorization-server
Protected resource metadata	GET /.well-known/oauth-protected-resource

Scopes

Scope	Access
company:read	Read selected company identity and basic settings.
wallet:balances:read	Read wallet balances for the selected company.
wallet:activity:read	Read wallet and settlement activity.
makepay:payment-links:read	Read MakePay payment links and payment status.
makepay:payment-links:write	Create and update MakePay payment links.
makepay:customers:read	Read MakePay customer records.
makepay:customers:write	Create and update MakePay customer records.
makepay:subscriptions:read	Read MakePay subscription records.
makepay:subscriptions:write	Create and update MakePay subscriptions.
makepay:settings:read	Read MakePay merchant settings and enabled assets.
makepay:settings:write	Update MakePay merchant settings and callback configuration.
makepay:webhooks:read	Read delivery logs and the current grant webhook subscription.
makepay:webhooks:write	Create, update, rotate, disable, or delete the grant webhook subscription.

API route permissions

Route	Method	Required scope
/api/partner/v1/makepay/payment-links	GET	makepay:payment-links:read
/api/partner/v1/makepay/payment-links	POST	makepay:payment-links:write
/api/partner/v1/makepay/customers	GET	makepay:customers:read
/api/partner/v1/makepay/customers	POST	makepay:customers:write
/api/partner/v1/makepay/subscriptions	GET	makepay:subscriptions:read
/api/partner/v1/makepay/subscriptions	POST	makepay:subscriptions:write
/api/partner/v1/makepay/settings	GET	makepay:settings:read
/api/partner/v1/makepay/settings	PUT	makepay:settings:write
/api/partner/v1/makepay/webhook-requests	GET	makepay:webhooks:read
/api/partner/v1/makepay/webhook-subscriptions/current	GET	makepay:webhooks:read
/api/partner/v1/makepay/webhook-subscriptions/current	PUT, DELETE	makepay:webhooks:write
/api/partner/v1/companies/{id}/wallet/balances	GET	wallet:balances:read
/api/partner/v1/companies/{id}/wallet/activity	GET	wallet:activity:read

Webhook signing

Developer-application webhooks include a makecrypto-signature header with timestamp and v1 signature values. Verify timestamp freshness, rebuild the signed payload as timestamp.rawBody, and compare the signature with the webhook secret shown once when the endpoint is created or rotated.

MakePay grant-scoped payment subscriptions instead use x-makepay-signature. Manage the current grant's isolated callback through /api/partner/v1/makepay/webhook-subscriptions/current; its signing secret is also returned only at creation or explicit rotation. See the MakePay webhook guide for the event and delivery contract.

Connected app management

Approved OAuth grants are visible in the company dashboard under Integrations -> Connected apps. Company admins can review app status, last access, and granted scopes, then revoke access to stop new API operations. For the official Medusa integration, revocation does not erase the historical-only webhook credential or suppress an exact late or redelivered settlement callback for a payment issued before revocation.