Merchant connection

This links one merchant to the platform you already set up. Your platform key stays on your server. The merchant only handles their own connection code.

Who does what

Endpoint

POSThttps://app.payshare.nz/api/connector/platform/redeem

Every action uses this endpoint, sent from your server with a JSON body and a signature. The action field selects the operation: verify during setup, then redeem, property_status and connection_status.

Signing requests

X-PayShare-PlatformheaderRequired

Your platform ID, shown next to your platform key in the PayShare app.

X-PayShare-Request-IdheaderRequired

A new unique value for every request, such as a UUID. PayShare rejects a request ID it has already seen.

X-PayShare-TimestampheaderRequired

Current Unix time in seconds. Must be within 5 minutes of PayShare’s clock.

X-PayShare-SignatureheaderRequired

Lowercase hex HMAC-SHA256 of the canonical string, keyed with your platform key.

The canonical string is these six values joined with a newline character:

platform ID
request ID
timestamp
action
externalPropertyId
SHA-256 hex of the raw JSON body

The action and externalPropertyId must match the body. Hash and send exactly the same body bytes.

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

const PAYSHARE_URL = "https://app.payshare.nz/api/connector/platform/redeem";
const PLATFORM_ID = process.env.PAYSHARE_PLATFORM_ID!;    // from the PayShare app
const PLATFORM_KEY = process.env.PAYSHARE_PLATFORM_KEY!;  // ps_conn_… from the PayShare app

export async function callPayShare(body: {
  action: "verify" | "redeem" | "property_status" | "connection_status";
  externalPropertyId: string; // "" for verify
  externalPropertyName?: string;
  connectionCode?: string;
  enabled?: boolean;
}) {
  const rawBody = JSON.stringify(body);
  const requestId = randomUUID();
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const canonical = [
    PLATFORM_ID,
    requestId,
    timestamp,
    body.action,
    body.externalPropertyId,
    createHash("sha256").update(rawBody, "utf8").digest("hex"),
  ].join("\n");
  const signature = createHmac("sha256", PLATFORM_KEY).update(canonical, "utf8").digest("hex");

  const res = await fetch(PAYSHARE_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-PayShare-Platform": PLATFORM_ID,
      "X-PayShare-Request-Id": requestId,
      "X-PayShare-Timestamp": timestamp,
      "X-PayShare-Signature": signature,
    },
    body: rawBody, // send exactly the bytes you hashed
  });
  const json = await res.json().catch(() => ({}));
  return { ok: res.ok, json };
}

Setup test

Send { "action": "verify", "externalPropertyId": "" } once after deploying. It returns { "verified": true } and ticks step 3 in PayShare. It works before your platform is live. The other actions need your platform to be live.

Redeem a connection code

Call this when the merchant selects Connect.

{
  "action": "redeem",
  "externalPropertyId": "prop_8842",
  "externalPropertyName": "Harbour View Motel",
  "connectionCode": "PS-CONNECT-7KQM-3XRT"
}

action"redeem"Required

Redeem a code.

externalPropertyIdstringRequired

Your stable ID for the property or store, 1 to 128 characters.

externalPropertyNamestring

Its display name, up to 256 characters.

connectionCodestringRequired

The code the merchant entered.

{ "status": "CONNECTED" }

• A code works once and expires after 30 minutes. Generating a new code in PayShare cancels the old one.
• Retrying with the same code and the same property returns CONNECTED again. Use a new request ID for each retry.
• A code that was used for one property cannot connect a different one.
• A property connects to one PayShare install. Redeeming a code from a different install for the same property moves it, for example when the merchant changes Stripe accounts, and disconnects the old one.
• Connecting leaves PayShare off. Send the current switch value next.

Turn PayShare on or off

Call this after Connect, and whenever the merchant changes the switch.

{
  "action": "property_status",
  "externalPropertyId": "prop_8842",
  "externalPropertyName": "Harbour View Motel",
  "enabled": true
}

action"property_status"Required

Report the switch value.

externalPropertyIdstringRequired

The connected property.

externalPropertyNamestring

Its current display name.

enabledbooleanRequired

true when PayShare is on for this property.

{ "relationship": "ACTIVE" }

This fails if the property is not connected. If the merchant has removed PayShare, the connection is closed and they need to reinstall and connect with a new code.

Check a connection

Use this to decide whether to show the button, or to refresh your setting screen.

{
  "action": "connection_status",
  "externalPropertyId": "prop_8842"
}

{ "connected": true, "installActive": true, "enabled": true }

connectedboolean

The property has a live connection to an active PayShare install.

installActiveboolean

The merchant still has PayShare installed. Only meaningful when connected is true.

enabledboolean

PayShare is on for this property. Show the button only when this is true.

Errors

Every failure returns HTTP 400 with the same body, whatever the cause: a bad signature, an old timestamp, a reused request ID, an expired or used code, or a disconnected property.

{ "error": { "message": "We couldn't connect PayShare. Please try again or contact PayShare support." } }

Show the merchant a general message and ask them to generate a new code. Retry a network failure once with a new request ID and timestamp.

Security checklist

• Keep your platform key on your server only. Never log it or the signature.
• Never log connection codes after use.
• Only call PayShare for properties the signed-in user administers on your platform.

Next: Add PayShare to checkout →