Morphosis HMAC v2 authenticates every public Payment API request. Webhook delivery still uses callback HMAC v1 — see Webhooks.

Morphosis HMAC v2

Each API request proves possession of a merchant signing secret without sending that secret over the network. Generate the signature from the exact request bytes before transmission.

Required headers

Header	Example value	Purpose
`X-Morphosis-Signature-Version`	`v2`	Selects the canonicalization rules
`X-Morphosis-Key-Id`	`mk_sandbox_docs_example`	Identifies the sandbox merchant key
`X-Morphosis-Timestamp`	`1785456000`	Unix time in whole seconds
`X-Morphosis-Nonce`	`nonce_docs_20260731_0001`	Unique value for one signed request
`X-Morphosis-Signature`	`jeIngz8uluitIQutRDF9r6d0K7p1ChdRAVAPDmXwueM`	Unpadded base64url HMAC-SHA256

POST /v2/payments also requires Idempotency-Key. That header is signed as the sixth canonical line. GET /v2/payments/{payment_id} must not send Idempotency-Key; if present, the gateway returns 400. Duplicate values for any signed header are rejected.

Canonical request

Join these seven values with a single line-feed character and no trailing LF:

v2
POST
/v2/payments
1785456000
nonce_docs_20260731_0001
idem_docs_20260731_0001
3994e63c2b7d0c81685c910d29a8116fdae90f587276a88699b8a599a2383b2a

Line rules:

Version string v2
Uppercase HTTP method
Raw path and query exactly as transmitted (/v2/payments, not a full URL)
Unix timestamp in whole seconds
Unique nonce
Raw Idempotency-Key for create, or an empty line for retrieve
Lowercase hexadecimal SHA-256 of the exact raw request body bytes

Encode the canonical string as UTF-8. Sign with HMAC-SHA-256. Encode the signature as unpadded base64url.

Compute the signature

import { createHash, createHmac } from "node:crypto";

function signMorphosisRequestV2({
  method,
  pathAndQuery,
  timestamp,
  nonce,
  idempotencyKey,
  rawBody,
  signingSecret,
}) {
  const bodyDigest = createHash("sha256").update(rawBody).digest("hex");
  const canonicalRequest = [
    "v2",
    method.toUpperCase(),
    pathAndQuery,
    timestamp,
    nonce,
    idempotencyKey ?? "",
    bodyDigest,
  ].join("\n");

  return createHmac("sha256", signingSecret)
    .update(canonicalRequest, "utf8")
    .digest("base64url");
}

const signature = signMorphosisRequestV2({
  method: "POST",
  pathAndQuery: "/v2/payments",
  timestamp: "1785456000",
  nonce: "nonce_docs_20260731_0001",
  idempotencyKey: "idem_docs_20260731_0001",
  rawBody: Buffer.from(
    '{"external_reference":"merchant-order-20260731-001","requested_amount":{"currency":"USD","decimal":"10.00","minor_units":"1000"},"metadata":{"channel":"docs-quickstart"}}',
    "utf8",
  ),
  signingSecret: "demo_only_not_a_credential_replace_with_issued_secret",
});

console.log(signature);
// jeIngz8uluitIQutRDF9r6d0K7p1ChdRAVAPDmXwueM

JSON formatting changes the body bytes. Serialize once, sign those bytes, and send the same bytes. Do not parse and reserialize the body after signing. Body digests use lowercase hex — not base64url.

Retrieve signing

For GET /v2/payments/{payment_id}:

Omit Idempotency-Key
Use an empty sixth canonical line
Hash an empty body (SHA-256 of zero bytes) as the seventh line

Replay resistance

Generate a cryptographically random nonce for every request.
Send current Unix time in whole seconds.
Never reuse a nonce, even when another field changes.
Keep merchant clocks synchronized.
Compare signatures in constant time in any verification tooling.

Credential handling

Store the key identifier and signing secret in a managed secret store or local environment variables excluded from version control. Never place a live secret in browser code, mobile applications, logs, screenshots, support tickets, or documentation.

Getting started

Guides

API reference

Authentication

Morphosis HMAC v2

Required headers

Canonical request

Compute the signature

Retrieve signing

Replay resistance

Credential handling

​Morphosis HMAC v2

​Required headers

​Canonical request

​Compute the signature

​Retrieve signing

​Replay resistance

​Credential handling

Morphosis HMAC v2

Required headers

Canonical request

Compute the signature

Retrieve signing

Replay resistance

Credential handling