Crypto Payments Gateway

What you will build.

Follow DEMO-ORDER-01 through checkout, confirmed payment and fulfillment. A customer returns to the success page, but the authoritative payment may still be pending. Your local exercise must not release the order merely because a browser redirected successfully.

Your working record

Create a private worksheet with columns for the source reference, observed state, responsible system, observation time, expected result and unresolved issue. Use the same fictional case throughout the steps; do not paste live personal or financial records into this exercise.

1. 01Map the three records
2. 02Validate before acting on a notification
3. 03Keep pending orders undelivered
4. 04Exercise duplicate fulfillment

Run the example before changing it.

Inspect the baseline record below. Download and read the complete JavaScript file before running it. It uses only Node’s built-in test and assertion modules; there is no package installation, account connection or secret to configure.

{
  "notificationVerified": true,
  "authoritativeState": "paid",
  "fulfilled": false
}

Save it as crypto-payments-gateway.mjs. Open a terminal in that folder and run:

node --version
node --test crypto-payments-gateway.mjs

Expected result: four passing tests and zero failures. These tests verify the teaching classifier only. They do not verify a production integration, security boundary or financial outcome.

// Hybrid-Chain offline teaching model: crypto-payments-gateway
// Fictional fields/states; NOT an API client, authorization system or production implementation.
// No network calls, credentials, payments or file writes. Review before running.
// Requires Node.js 22+. Run: node --test crypto-payments-gateway.mjs
import test from 'node:test';
import assert from 'node:assert/strict';

export function inspect(record) {
  if (!record.notificationVerified) return 'REJECT_NOTIFICATION';
  if (record.fulfilled) return 'ALREADY_FULFILLED';
  if (record.authoritativeState !== 'paid') return 'WAIT_FOR_PAYMENT';
  return 'READY_FOR_FULFILLMENT_REVIEW';
}

const baseline = {
  "notificationVerified": true,
  "authoritativeState": "paid",
  "fulfilled": false
};
const cases = [
  {
    "name": "payment ready for delivery review",
    "patch": {},
    "expected": "READY_FOR_FULFILLMENT_REVIEW"
  },
  {
    "name": "invalid callback",
    "patch": {
      "notificationVerified": false
    },
    "expected": "REJECT_NOTIFICATION"
  },
  {
    "name": "pending payment",
    "patch": {
      "authoritativeState": "pending"
    },
    "expected": "WAIT_FOR_PAYMENT"
  },
  {
    "name": "repeated paid notification",
    "patch": {
      "fulfilled": true
    },
    "expected": "ALREADY_FULFILLED"
  }
];

for (const example of cases) {
  test(example.name, () => {
    assert.equal(inspect({...baseline, ...example.patch}), example.expected);
  });
}

Know what the tests demonstrate

payment ready for delivery review

READY_FOR_FULFILLMENT_REVIEW

invalid callback

REJECT_NOTIFICATION

pending payment

WAIT_FOR_PAYMENT

repeated paid notification

ALREADY_FULFILLED

Now change one fixture at a time. If you change a case’s input without changing its expected result, the test should fail. Read the actual-versus-expected difference and use the walkthrough to decide whether your rule or your expectation needs correcting. Keep an unchanged copy for comparison.

Work through the case, step by step.

1. 01

   Map the three records

   Do this

   1. Create DEMO-ORDER-01 in a worksheet and add empty columns for payment reference and fulfillment reference.
   2. Record the expected currency and amount before creating a checkout through any later authorized integration.
   3. Write down the source of truth for payment state and the system responsible for delivery.

   Expected result

   Order creation, provider payment and delivery remain separate records that can be reconciled after a failure.

   If your result is different

   If a return URL is your only evidence of payment, stop and identify a supported authoritative status route.

2. 02

   Validate before acting on a notification

   Do this

   1. Run the offline baseline with notificationVerified=true and authoritativeState=paid.
   2. Set notificationVerified=false and confirm REJECT_NOTIFICATION.
   3. Treat this flag as a placeholder for real provider authentication, replay handling and schema checks—not a signature verifier.

   Expected result

   The design has a clear boundary between receiving a message and trusting it enough to inspect payment status.

   If your result is different

   Never let a browser parameter or an unchecked JSON field set notificationVerified in the actual implementation.

3. 03

   Keep pending orders undelivered

   Do this

   1. Change authoritativeState to pending and expect WAIT_FOR_PAYMENT.
   2. Repeat after an imagined browser success redirect; the result must still be pending.
   3. Record the support path for an abandoned checkout and for a paid order whose delivery service is unavailable.

   Expected result

   A customer-facing page can explain pending or paid-but-undelivered without charging again or fabricating completion.

   If your result is different

   When status reads fail, show unresolved payment status and retry safely; do not convert a transport error into paid or declined.

4. 04

   Exercise duplicate fulfillment

   Do this

   1. Set fulfilled=true and confirm ALREADY_FULFILLED, even for a verified paid notification.
   2. Identify the durable unique order/delivery key that the real fulfillment service will enforce.
   3. Save the outcomes and test concurrent callbacks separately when the actual merchant integration is available.

   Expected result

   The local model explains the duplicate boundary; the integration backlog includes the atomic implementation and concurrency test.

   If your result is different

   A boolean in this script does not provide production exactly-once delivery. Use a durable transactional design in the owning service.

Review what you produced.

Save the worksheet, unmodified test output, one deliberately failing case and the explanation of its fix. A useful result includes an unresolved item with an owner; it is not just a screenshot of four green tests.

Map the model to actual systems.

Your commerce application owns the order, callback validation, retry-safe fulfillment, customer support, and refund policy. A redirect is not proof of payment.

For each worksheet field, name the owning system, exact current operation, permission and error behavior. Put “not available” next to any missing operation and assign a dependency owner. Do not substitute the teaching classifier for that missing integration.

Open the current API reference and inspect each operation’s request, response, scope and implementation status. Code examples on this page are local models only; they do not call those operations.

Before a real deployment, the responsible organization must obtain appropriate legal, compliance and security review. The tutorial does not determine licensing, eligibility, entitlement enforceability or financial suitability.

Take the next technical step.

Use your worksheet and failing-case notes in the next walkthrough. Keep the same reference trail so you can see which assumptions become actual observations—and which remain dependencies.

Need help with access or an unavailable integration? Contact the team with a redacted error and the guide step. Never send credentials or private records.