Skip to main content

​
API Key Authentication

All requests require an API key in the X-API-Key header:
API keys are provisioned during merchant onboarding. Contact support@moduluslabs.io to request keys. Credentials use environment-qualified prefixes such as sk_test_, pk_test_, sk_live_, or pk_live_. Some legacy Modulus APIs use the shorter sk_ or pk_ prefixes. Always send the complete key exactly as issued. The permissions assigned to the key, not its prefix, determine which operations it can perform.
Test a key without writing code in the Create a Payment Link API Reference. Paste your key into the X-API-Key field and send a request against the sandbox.
Keep API keys out of client-side code, public repositories, and browser applications. Requests without a valid key receive 401 UNAUTHORIZED.

​
Entity Scoping

Every API key is scoped to an entity in the organization hierarchy. Data access is automatically restricted based on your key’s level. When you create a payment link, partner- and merchant-scoped keys must specify a merchant_branch_reference_number. Branch-scoped keys can omit it - the link is created against that branch automatically.
Design note. Reading a resource that belongs to another entity returns 404 NOT_FOUND, the same as an id that does not exist, rather than 403. This prevents leaking whether a resource exists across tenants. See Errors.

​
Idempotency

The Idempotency-Key header is a unique client-generated identifier using letters, digits, dot (.), hyphen (-), and underscore (_), 8-64 characters. Clients often reuse their own order_reference as the key.
  • POST /payment-links (create a payment link) - required
  • POST /payment-links/{id}/cancel (cancel a payment link) - optional and validated when supplied
For Create, sending the same idempotency key with the same request body returns the original response without creating a duplicate. Reusing it with a different body returns 409 IDEMPOTENCY_MISMATCH. Cancel accepts and validates an optional key. Repeating a cancel on a link that is no longer ACTIVE returns 409 INVALID_STATE.
Idempotency keys expire after 24 hours. Generate a fresh key for each distinct operation.

​
Choosing the right identifier

Three fields carry merchant-side context. Each serves a different purpose: A common pattern: set order_reference to your order ID for reconciliation, reuse it as the Idempotency-Key for safe retries, and put supplementary tags (channel, campaign, internal user) in metadata.

​
Request headers

​
Response headers

Application responses include x-correlation-id. Platform-generated authentication and authorization responses do not include it.

​
Rate limits

Rate limits may apply and can vary by environment and account configuration. When a limit is exceeded the API returns HTTP 429. Retry with exponential backoff. Contact support@moduluslabs.io for the limits assigned to your integration.