Draft API Preview for the MorphosisBlock Payment API. Header names and signing rules are proposed contract material. No credential issued for another system should be used with these examples.

Morphosis HMAC v1

Each draft 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. Five request headers identify the key, version, time, nonce, and signature. One canonical string binds them to the method, request target, and body.

Required headers

Header	Example value	Purpose
`X-Morphosis-Signature-Version`	`v1`	Selects the canonicalization rules
`X-Morphosis-Key-Id`	`mk_test_docs_20260730`	Identifies the sandbox merchant key
`X-Morphosis-Timestamp`	`1785369660`	Unix time in whole seconds
`X-Morphosis-Nonce`	`nonce_docs_20260730_0001`	Unique value for one signed request
`X-Morphosis-Signature`	`uqHdlUqKTs6QQGbr6sYoFJC3q9atzUZWrkLHrh8G8g4`	Base64url HMAC-SHA256 result

POST /v2/payments also requires an Idempotency-Key, but that header is not part of the v1 canonical string. Use a stable key for one logical payment.

Canonical request

Join these six values with a single line-feed character:

v1
POST
/v2/payments
1785369660
nonce_docs_20260730_0001
h5RBMey_De7e3ESpOiPejzKM7_n5AiMKnmdV-dqWSpY

The final line is the unpadded base64url encoding of the SHA-256 digest of the exact request body bytes. For an empty body, hash an empty byte sequence. The path line contains the exact path and query transmitted on the wire. A request without a query uses /v2/payments, not a host name or full URL.

Compute the signature

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

function signMorphosisRequest({
  method,
  pathAndQuery,
  timestamp,
  nonce,
  rawBody,
  signingSecret,
}) {
  const bodyDigest = createHash("sha256").update(rawBody).digest("base64url");
  const canonicalRequest = [
    "v1",
    method.toUpperCase(),
    pathAndQuery,
    timestamp,
    nonce,
    bodyDigest,
  ].join("\n");

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

const signature = signMorphosisRequest({
  method: "POST",
  pathAndQuery: "/v2/payments",
  timestamp: "1785369660",
  nonce: "nonce_docs_20260730_0001",
  rawBody: Buffer.from(
    '{"external_reference":"merchant-order-20260730-001","requested_amount":{"currency":"USD","decimal":"1.00","minor_units":"100"},"metadata":{"checkout_session":"checkout-001"}}',
    "utf8",
  ),
  signingSecret: "demo_only_not_a_credential_20260730",
});

console.log(signature);

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.

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.

The final accepted timestamp window and nonce retention period are launch parameters and are not promised by this draft preview.

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 v1

Required headers

Canonical request

Compute the signature

Replay resistance

Credential handling

​Morphosis HMAC v1

​Required headers

​Canonical request

​Compute the signature

​Replay resistance

​Credential handling

Morphosis HMAC v1

Required headers

Canonical request

Compute the signature

Replay resistance

Credential handling