التوثيق — الإصدار v1

KEY="sy_test_xxx"; SECRET="xxx"
METHOD="GET"; TARGET="/api/v1/products?page=1"   # path + ?query exactly as sent
BODY=''
TS=$(date +%s)
SIG=$(printf 'v2\n%s\n%s\n%s\n%s' "$TS" "$METHOD" "$TARGET" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -s -X "$METHOD" "https://syriana.store$TARGET" \
  -H "X-Syriana-Key: $KEY" \
  -H "X-Syriana-Timestamp: $TS" \
  -H "X-Syriana-Signature-Version: 2" \
  -H "X-Syriana-Signature: $SIG"

import hashlib, hmac, json, time, requests
from urllib.parse import quote, urlencode

KEY, SECRET = "sy_test_xxx", "xxx"
BASE = "https://syriana.store"

def call(method, path, payload=None, query=None):
    # v2 signs METHOD, the path + query exactly as sent, and the body. Build
    # each string once and send those same strings — json.dumps twice can
    # differ. Percent-encode path segments yourself: quote(sku, safe="").
    body = json.dumps(payload, ensure_ascii=False) if payload else ""
    target = path + ("?" + urlencode(query) if query else "")
    ts = str(int(time.time()))
    to_sign = "\n".join(["v2", ts, method.upper(), target, body])
    sig = hmac.new(SECRET.encode(), to_sign.encode(), hashlib.sha256).hexdigest()
    return requests.request(method, BASE + target, data=body.encode(), headers={
        "X-Syriana-Key": KEY,
        "X-Syriana-Timestamp": ts,
        "X-Syriana-Signature-Version": "2",
        "X-Syriana-Signature": sig,
        "Content-Type": "application/json",
    })

print(call("GET", "/api/v1/ping").json())
print(call("GET", "/api/v1/products", query={"page": 1}).json())

<?php
$key = "sy_test_xxx"; $secret = "xxx";
$base = "https://syriana.store";

function sy_call($method, $path, $payload = null, $query = []) {
    global $key, $secret, $base;
    // JSON_UNESCAPED_UNICODE matters: Arabic escaped differently here than
    // when you signed it would produce a valid signature over other bytes.
    $body   = $payload ? json_encode($payload, JSON_UNESCAPED_UNICODE) : "";
    $target = $path . ($query ? "?" . http_build_query($query) : "");
    $ts     = (string) time();
    $toSign = implode("\n", ["v2", $ts, strtoupper($method), $target, $body]);
    $sig    = hash_hmac("sha256", $toSign, $secret);

    $ch = curl_init($base . $target);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            "X-Syriana-Key: $key",
            "X-Syriana-Timestamp: $ts",
            "X-Syriana-Signature-Version: 2",
            "X-Syriana-Signature: $sig",
            "Content-Type: application/json",
        ],
    ]);
    $out = curl_exec($ch); curl_close($ch);
    return json_decode($out, true);
}

print_r(sy_call("GET", "/api/v1/ping"));
print_r(sy_call("GET", "/api/v1/products", null, ["page" => 1]));

const crypto = require("crypto");

const KEY = "sy_test_xxx", SECRET = "xxx";
const BASE = "https://syriana.store";

async function call(method, path, payload, query) {
  const body = payload ? JSON.stringify(payload) : "";
  const qs = query ? new URLSearchParams(query).toString() : "";
  const target = path + (qs ? "?" + qs : "");   // exactly what is sent
  const ts = Math.floor(Date.now() / 1000).toString();
  const sig = crypto.createHmac("sha256", SECRET)
    .update(["v2", ts, method.toUpperCase(), target, body].join("\n"))
    .digest("hex");

  const res = await fetch(BASE + target, {
    method,
    body: body || undefined,
    headers: {
      "X-Syriana-Key": KEY,
      "X-Syriana-Timestamp": ts,
      "X-Syriana-Signature-Version": "2",
      "X-Syriana-Signature": sig,
      "Content-Type": "application/json",
    },
  });
  return res.json();
}

call("GET", "/api/v1/ping").then(console.log);
call("GET", "/api/v1/products", null, { page: 1 }).then(console.log);

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
    "strings"
    "time"
)

const key, secret, base = "sy_test_xxx", "xxx", "https://syriana.store"

// target = path + "?" + url.Values{...}.Encode() — exactly what is sent.
func call(method, target, body string) (string, error) {
    ts := fmt.Sprintf("%d", time.Now().Unix())
    mac := hmac.New(sha256.New, []byte(secret))
    toSign := strings.Join([]string{"v2", ts, strings.ToUpper(method), target, body}, "\n")
    mac.Write([]byte(toSign))
    sig := hex.EncodeToString(mac.Sum(nil))

    req, _ := http.NewRequest(method, base+target, strings.NewReader(body))
    req.Header.Set("X-Syriana-Key", key)
    req.Header.Set("X-Syriana-Timestamp", ts)
    req.Header.Set("X-Syriana-Signature-Version", "2")
    req.Header.Set("X-Syriana-Signature", sig)
    req.Header.Set("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return "", err
    }
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    return string(out), nil
}

func main() {
    fmt.Println(call("GET", "/api/v1/ping", ""))
    fmt.Println(call("GET", "/api/v1/products?page=1", ""))
}

BODY='{"title":"اشتراك سنوي","amount":250,"currency":"SAR","mode":"once","methods":["stripe"],"reference":"ORDER-1042"}'
TS=$(date +%s)
SIG=$(printf 'v2\n%s\n%s\n%s\n%s' "$TS" POST /api/v1/payment_links "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -s -X POST "https://syriana.store/api/v1/payment_links" \
  -H "X-Syriana-Key: $KEY" -H "X-Syriana-Timestamp: $TS" \
  -H "X-Syriana-Signature-Version: 2" -H "X-Syriana-Signature: $SIG" \
  -H "Content-Type: application/json" -d "$BODY"

link = call("POST", "/api/v1/payment_links", {
    "title": "اشتراك سنوي",
    "amount": 250,
    "currency": "SAR",
    "mode": "once",              # or "reusable"
    "methods": ["stripe"],       # [] = every method you enabled
    "reference": "ORDER-1042",   # yours; comes back on the webhook
}).json()["data"]

redirect_to = link["url"]        # send your customer here

$link = sy_call("POST", "/api/v1/payment_links", [
    "title"     => "اشتراك سنوي",
    "amount"    => 250,
    "currency"  => "SAR",
    "mode"      => "once",
    "methods"   => ["stripe"],
    "reference" => "ORDER-1042",
])["data"];

header("Location: " . $link["url"]);

const { data: link } = await call("POST", "/api/v1/payment_links", {
  title: "اشتراك سنوي",
  amount: 250,
  currency: "SAR",
  mode: "once",
  methods: ["stripe"],
  reference: "ORDER-1042",
});

res.redirect(link.url);

body := `{"title":"اشتراك سنوي","amount":250,"currency":"SAR",
          "mode":"once","methods":["stripe"],"reference":"ORDER-1042"}`
out, err := call("POST", "/api/v1/payment_links", body)
// out.data.url هو ما تحوّل إليه عميلك

# ليست عملية سطر أوامر: التحقّق يجري في خادمك.
# القاعدة واحدة في كل لغة —
#   expected = hmac_sha256(webhook_secret, timestamp + "." + raw_body)
# ثم قارنه بترويسة X-Syriana-Signature بمقارنة ثابتة الزمن.

import hmac, hashlib

def verify(raw_body: bytes, timestamp: str, signature: str, secret: str):
    expected = hmac.new(secret.encode(),
                        timestamp.encode() + b"." + raw_body,
                        hashlib.sha256).hexdigest()
    # compare_digest, never ==: a plain comparison returns faster on an early
    # mismatch, and that timing alone leaks the signature byte by byte.
    return hmac.compare_digest(expected, signature)

# Read the RAW body. A framework that parses and re-serialises JSON for you
# will hand you different bytes than the ones we signed.

<?php
function sy_verify($rawBody, $timestamp, $signature, $secret) {
    $expected = hash_hmac("sha256", $timestamp . "." . $rawBody, $secret);
    // hash_equals, not ===, for the same timing reason.
    return hash_equals($expected, $signature);
}

// $rawBody = file_get_contents("php://input");  // NOT $_POST

const crypto = require("crypto");

function verify(rawBody, timestamp, signature, secret) {
  const expected = crypto.createHmac("sha256", secret)
                         .update(`${timestamp}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected),
                                Buffer.from(signature));
}

// express: app.use(express.raw({type: "application/json"}))
// so rawBody is the exact bytes we signed.

func verify(rawBody []byte, timestamp, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp + "."))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}