Draft API Preview for the MorphosisBlock Payment API. This walkthrough targets a reserved non-routable domain. It demonstrates the proposed contract and cannot create a real payment.

Create a sandbox payment

This example signs a proposed POST /v2/payments request with Morphosis HMAC v1. It uses fixed documentation values so the request can be reviewed and reproduced without exposing a credential. The complete path is deliberately short: configure documentation values, sign one exact JSON body, and inspect the proposed payment resource.

1. Set documentation-only values

export MORPHOSIS_API_BASE_URL="https://api.example.invalid"
export MORPHOSIS_KEY_ID="mk_test_docs_20260730"
export MORPHOSIS_SIGNING_SECRET="demo_only_not_a_credential_20260730"

The .invalid top-level domain is reserved and cannot resolve to a real API. The displayed signing value is intentionally public and must never be used outside this documentation example.

2. Sign and send the request

Save the following as create-payment.mjs and run it with Node.js 18 or newer. The request will fail at network resolution by design, but the printed canonical request and headers demonstrate the complete signing flow.

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

const baseUrl = process.env.MORPHOSIS_API_BASE_URL;
const keyId = process.env.MORPHOSIS_KEY_ID;
const signingSecret = process.env.MORPHOSIS_SIGNING_SECRET;

if (!baseUrl || !keyId || !signingSecret) {
  throw new Error("Set all three documentation environment variables.");
}

const method = "POST";
const pathAndQuery = "/v2/payments";
const timestamp = "1785369660";
const nonce = "nonce_docs_20260730_0001";
const idempotencyKey = "idem_docs_20260730_0001";
const requestBody = {
  external_reference: "merchant-order-20260730-001",
  requested_amount: {
    currency: "USD",
    decimal: "1.00",
    minor_units: "100",
  },
  metadata: {
    checkout_session: "checkout-001",
  },
};
const body = JSON.stringify(requestBody);
const bodyDigest = createHash("sha256")
  .update(Buffer.from(body, "utf8"))
  .digest("base64url");
const canonicalRequest = [
  "v1",
  method,
  pathAndQuery,
  timestamp,
  nonce,
  bodyDigest,
].join("\n");
const signature = createHmac("sha256", signingSecret)
  .update(canonicalRequest)
  .digest("base64url");

console.log(canonicalRequest);

const response = await fetch(`${baseUrl}${pathAndQuery}`, {
  method,
  headers: {
    "content-type": "application/json",
    "idempotency-key": idempotencyKey,
    "x-morphosis-signature-version": "v1",
    "x-morphosis-key-id": keyId,
    "x-morphosis-timestamp": timestamp,
    "x-morphosis-nonce": nonce,
    "x-morphosis-signature": signature,
  },
  body,
});

console.log(response.status);
console.log(await response.text());

3. Understand the proposed response

A successful draft response has the following shape. The address is deliberately invalid and must not receive funds.

{
  "payment_id": "pay_01K1DRAFT8F7Z6K5Q4N3M2P1A0",
  "external_reference": "merchant-order-20260730-001",
  "status": "pending",
  "requested_amount": {
    "currency": "USD",
    "decimal": "1.00",
    "minor_units": "100"
  },
  "payment_instructions": {
    "network": "tron_shasta",
    "asset": "TRX",
    "destination": "TDocs0nlyAddressNotForPayments0000",
    "amount": {
      "currency": "TRX",
      "decimal": "3.250000",
      "minor_units": "3250000"
    },
    "expires_at": "2026-07-30T15:40:00Z"
  },
  "environment": "sandbox",
  "metadata": {
    "checkout_session": "checkout-001"
  },
  "created_at": "2026-07-30T15:10:00Z",
  "updated_at": "2026-07-30T15:10:00Z"
}

Persist payment_id, external_reference, and the complete payment_instructions object before presenting instructions to a customer. Never send funds to a documentation address. See Errors and idempotency for ambiguous outcomes.

Getting started

Guides

API reference

Quickstart

Create a sandbox payment

1. Set documentation-only values

2. Sign and send the request

3. Understand the proposed response

​Create a sandbox payment

​1. Set documentation-only values

​2. Sign and send the request

​3. Understand the proposed response

Create a sandbox payment

1. Set documentation-only values

2. Sign and send the request

3. Understand the proposed response