Stage Sandbox walkthrough. Replace the example key id and secret with credentials Morphosis issued to your merchant. The example secret below is public documentation material and will be rejected by the live gateway.

Create a sandbox payment

This example signs POST /v2/payments with Morphosis HMAC v2 and targets the live Stage Sandbox origin.

1. Configure environment

export MORPHOSIS_API_BASE_URL="https://payment-gateway.learnagent.cloud"
export MORPHOSIS_KEY_ID="mk_sandbox_docs_example"
export MORPHOSIS_SIGNING_SECRET="demo_only_not_a_credential_replace_with_issued_secret"

Use your issued MORPHOSIS_KEY_ID and MORPHOSIS_SIGNING_SECRET. Keep the base URL pointing at the Stage Sandbox.

2. Sign and send the request

Save the following as create-payment.mjs and run it with Node.js 18 or newer.

import { createHash, createHmac, randomBytes } 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 MORPHOSIS_API_BASE_URL, MORPHOSIS_KEY_ID, and MORPHOSIS_SIGNING_SECRET.");
}

const method = "POST";
const pathAndQuery = "/v2/payments";
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomBytes(18).toString("base64url");
const idempotencyKey = `idem_${randomBytes(12).toString("hex")}`;
const requestBody = {
  external_reference: `merchant-order-${Date.now()}`,
  requested_amount: {
    currency: "USD",
    decimal: "10.00",
    minor_units: "1000",
  },
  metadata: {
    channel: "docs-quickstart",
  },
};
const body = JSON.stringify(requestBody);
const bodyDigest = createHash("sha256")
  .update(Buffer.from(body, "utf8"))
  .digest("hex");
const canonicalRequest = [
  "v2",
  method,
  pathAndQuery,
  timestamp,
  nonce,
  idempotencyKey,
  bodyDigest,
].join("\n");
const signature = createHmac("sha256", signingSecret)
  .update(canonicalRequest, "utf8")
  .digest("base64url");

const response = await fetch(`${baseUrl}${pathAndQuery}`, {
  method,
  headers: {
    "content-type": "application/json",
    "idempotency-key": idempotencyKey,
    "x-morphosis-signature-version": "v2",
    "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());

A successful create returns 201 with payment_id and payment_instructions. A same-digest in-flight or indeterminate submission returns 202 with status: "submission_unknown" — do not create a second logical payment.

3. Reproducible documentation vector

The fixed vector below is for reviewing the canonical string. It uses documentation-only credentials and a fixed timestamp.

v2
POST
/v2/payments
1785456000
nonce_docs_20260731_0001
idem_docs_20260731_0001
3994e63c2b7d0c81685c910d29a8116fdae90f587276a88699b8a599a2383b2a

Signed with demo_only_not_a_credential_replace_with_issued_secret, the signature is jeIngz8uluitIQutRDF9r6d0K7p1ChdRAVAPDmXwueM. Body bytes:

{"external_reference":"merchant-order-20260731-001","requested_amount":{"currency":"USD","decimal":"10.00","minor_units":"1000"},"metadata":{"channel":"docs-quickstart"}}

4. Understand a successful response

{
  "payment_id": "pay_01K1EXAMPLE8F7Z6K5Q4N3M2PA",
  "external_reference": "merchant-order-20260731-001",
  "status": "pending",
  "requested_amount": {
    "currency": "USD",
    "decimal": "10.00",
    "minor_units": "1000"
  },
  "payment_instructions": {
    "network": "tron_shasta",
    "asset": "TRX",
    "destination": "TXYZohsKGjPpz8Y9Y9Y9Y9Y9Y9Y9Y9Y9Y9",
    "amount": {
      "decimal": "32.500000",
      "sun": "32500000"
    },
    "expires_at": "2026-07-31T12:40:00Z"
  },
  "environment": "sandbox",
  "metadata": {
    "channel": "docs-quickstart"
  },
  "created_at": "2026-07-31T12:10:00Z",
  "updated_at": "2026-07-31T12:10:00Z"
}

Persist payment_id, external_reference, and the complete payment_instructions object before presenting instructions to a customer. TRX amounts use decimal + sun (not minor_units).

5. Next steps

Implement Authentication helpers once, then reuse them for create and retrieve.
Wire Webhooks before relying on polling alone.
Compare your buyer UX to the reference cashier.

Getting started

Guides

API reference

Quickstart

Create a sandbox payment

1. Configure environment

2. Sign and send the request

3. Reproducible documentation vector

4. Understand a successful response

5. Next steps

​Create a sandbox payment

​1. Configure environment

​2. Sign and send the request

​3. Reproducible documentation vector

​4. Understand a successful response

​5. Next steps

Create a sandbox payment

1. Configure environment

2. Sign and send the request

3. Reproducible documentation vector

4. Understand a successful response

5. Next steps