npm install @venta/hyper-js
npm install @venta/react-hyper-js

import { loadHyper } from "@venta/hyper-js";

// 使用 Publishable Key 初始化（前端安全）
const hyperPromise = loadHyper("YOUR_PUBLISHABLE_KEY");

const response = await fetch("https://sandbox.venta.network/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    amount: 10000,
    currency: "USD",
    customer_id: "cus_123",
    confirm: false,          // 由前端 SDK 负责确认
    capture_method: "automatic",
    return_url: "https://example.com/complete",
  }),
});
// 响应中的 client_secret 用于前端渲染收银台与确认支付

import { HyperElements, UnifiedCheckout } from "@venta/react-hyper-js";

function CheckoutForm({ clientSecret }) {
  return (
    <HyperElements hyper={hyperPromise} options={{ clientSecret }}>
      <UnifiedCheckout />
    </HyperElements>
  );
}

const { error, status } = await hyper.confirmPayment({
  elements,
  confirmParams: {
    return_url: "https://example.com/complete",
  },
});

if (error) {
  // 展示错误信息，例如卡片被拒绝
} else if (status) {
  // 处理支付状态（succeeded / requires_capture ...）
}

curl https://sandbox.venta.network/payments/pay_123 \
  -H "api-key: YOUR_API_KEY"

import { loadHyper } from "@venta/hyper-js";
import { HyperElements, ExpressCheckout } from "@venta/react-hyper-js";

const hyperPromise = loadHyper("YOUR_PUBLISHABLE_KEY");

function ExpressPay({ clientSecret }) {
  return (
    <HyperElements hyper={hyperPromise} options={{ clientSecret }}>
      {/* 一行 Apple Pay / G Pay 按钮，点一下弹钱包授权 */}
      <ExpressCheckout />
    </HyperElements>
  );
}

<ExpressCheckout
  onSDKHandleClick={() => {
    // 客户点击钱包按钮后触发（须在 1 秒内完成，否则 Apple Pay 可能失败）
  }}
  onPaymentComplete={() => {
    // 支付完成、跳转 return_url 前触发，可在此更新订单状态
  }}
/>
// 注意：ExpressCheckout 会自动完成 confirm，无需像 UnifiedCheckout 那样手动调 confirmPayment

<script src="https://cdn.venta.network/hyper.js"></script>

hyper = Hyper.init("YOUR_PUBLISHABLE_KEY", {
  // 可选：自定义后端代理地址，统一转发 session / payments / confirm 请求
  customBackendUrl: "https://your-backend.example.com",
});

// 服务端创建 PaymentIntent，返回 clientSecret
// 切勿将 API Key 暴露给客户端
const payment = await createPayment({
  amount: 10000,
  currency: "USD",
  customer_id: "cus_123",
});
// 返回给前端: { client_secret }

paymentSession = hyper.initPaymentSession({
  clientSecret: client_secret,
});

// 获取客户已保存的支付方式，渲染自定义 UI
paymentMethodSession = await paymentSession.getCustomerSavedPaymentMethods();

if (paymentMethodSession.error) {
  // 处理无默认支付方式的情况
} else {
  // 读取默认 / 最近使用的支付方式数据，用于渲染您的卡片列表
  const defaultPm = paymentMethodSession.getCustomerDefaultSavedPaymentMethodData();
  const lastUsedPm = paymentMethodSession.getCustomerLastUsedPaymentMethodData();
}

// 使用默认支付方式发起支付
const { error, status } =
  await paymentMethodSession.confirmWithCustomerDefaultPaymentMethod({
    confirmParams: { return_url: "https://example.com/complete" },
    redirect: "if_required",  // always / if_required，默认 always
    id: "card-cvc-element",   // 采集 CVC 的 CardCVCElement id（可选）
  });

// 或使用最近一次使用的支付方式
await paymentMethodSession.confirmWithLastUsedPaymentMethod({
  confirmParams: { return_url: "https://example.com/complete" },
  redirect: "if_required",
});

import { CardCVCElement, useHyper } from "@venta/react-hyper-js";

function CvcField() {
  const hyper = useHyper();
  return (
    <div>
      {/* 安全 iframe 采集 CVC，数据不经过你的服务器 */}
      <CardCVCElement id="card-cvc-element" />
      <button onClick={handleSubmit}>立即支付</button>
    </div>
  );
}

curl https://sandbox.venta.network/payment-method-session \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "profile_id": "YOUR_PROFILE_ID",
    "customer_id": "cus_123",
    "storage_type": "long_term"
  }'
// 响应返回 sdk_authorization（临时会话凭证），
// 供前端 SDK 初始化与安全采集卡号，请勿泄露

// ① 调用您自己的后端端点拿到 sdk_authorization
const res = await fetch("/api/payment-method-session");
const { sdk_authorization } = await res.json();

// ② 用 sdk_authorization 初始化 SDK（注意：不是 Publishable Key）
const hyper = loadHyper(sdk_authorization);

// ③ 挂载卡片采集 / 管理表单（iframe），客户在此输入或选择卡片
hyper.paymentMethodsManagement().mount("#pmm-container");

// 客户在表单中填好卡后，调用确认代币化
const { error, payment_method_id } = await hyper.confirmTokenization({
  return_url: "https://example.com/vault-complete",
});
if (error) { /* 展示错误，例如卡片被拒 */ return; }

// ★ payment_method_id 在此返回，先到前端
// 请将它 POST 回您的后端，长期保存（Vault-Then-Pay）
await fetch("/api/save-payment-method", {
  method: "POST",
  body: JSON.stringify({ payment_method_id, customer_id: "cus_123" }),
});

{
  "amount": 10000,
  "currency": "USD",
  "customer_id": "cus_123",
  "payment_method": "card",
  "payment_token": "payment_method_id_from_vault",
  "confirm": true
}

curl https://sandbox.venta.network/refunds \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "payment_id": "pay_8f7e6d5c4b3a2a1b",
    "amount": 6540,
    "refund_type": "instant",
    "reason": "Customer requested refund"
  }'

{
  "refund_id": "ref_8f7e6d5c4b3a2a1b",
  "payment_id": "pay_8f7e6d5c4b3a2a1b",
  "amount": 6540,
  "currency": "USD",
  "status": "succeeded",
  "connector": "stripe",
  "created_at": "2026-08-12T10:16:00.000Z",
  "updated_at": "2026-08-12T10:16:01.000Z"
}

curl https://sandbox.venta.network/refunds/ref_8f7e6d5c4b3a2a1b \
  -H "api-key: YOUR_API_KEY"

{
  "refund_id": "ref_8f7e6d5c4b3a2a1b",
  "payment_id": "pay_8f7e6d5c4b3a2a1b",
  "amount": 6540,
  "currency": "USD",
  "status": "succeeded",
  "connector": "stripe"
}

curl "https://sandbox.venta.network/disputes/list?dispute_status=dispute_opened&limit=20" \
  -H "api-key: YOUR_API_KEY"

[
  {
    "dispute_id": "dp_8f7e6d5c4b3a2a1b",
    "payment_id": "pay_8f7e6d5c4b3a2a1b",
    "amount": "12500",
    "currency": "USD",
    "dispute_stage": "dispute",
    "dispute_status": "dispute_opened",
    "connector": "stripe",
    "connector_reason": "fraudulent",
    "challenge_required_by": "2026-08-19T10:20:00.000Z"
  }
]

curl https://sandbox.venta.network/disputes/dp_8f7e6d5c4b3a2a1b \
  -H "api-key: YOUR_API_KEY"

{
  "dispute_id": "dp_8f7e6d5c4b3a2a1b",
  "payment_id": "pay_8f7e6d5c4b3a2a1b",
  "attempt_id": "attempt_123",
  "amount": "12500",
  "currency": "USD",
  "dispute_stage": "dispute",
  "dispute_status": "dispute_opened",
  "connector": "stripe",
  "connector_reason": "fraudulent",
  "connector_reason_code": "10.4",
  "challenge_required_by": "2026-08-19T10:20:00.000Z",
  "profile_id": "prof_8e1f2a3b4c5d",
  "merchant_connector_id": "mca_5c4d3e2f1a0b"
}

# Sandbox
https://sandbox.venta.network/webhooks/{merchant_id}/{merchant_connector_id}

# Production
https://api.venta.network/webhooks/{merchant_id}/{merchant_connector_id}

{
  "merchant_id": "merchant_1745244120",
  "event_id": "evt_9f2c1b3a4d5e6f7a",
  "event_type": "payment_succeeded",
  "timestamp": "2026-08-12T10:15:30.000Z",
  "processor_merchant_id": "M1234567",
  "content": {
    "type": "payment_details",
    "object": {
      "payment_id": "pay_8f7e6d5c4b3a2a1b",
      "merchant_id": "merchant_1745244120",
      "status": "succeeded",
      "amount": 12500,
      "net_amount": 12500,
      "amount_received": 12500,
      "currency": "USD",
      "connector": "stripe",
      "client_secret": "pay_8f7e6d5c4b3a2a1b_secret_8Kx2Lm9Q",
      "created": "2026-08-12T10:14:52.000Z",
      "modified_at": "2026-08-12T10:15:30.000Z",
      "payment_method": "card",
      "payment_method_type": "credit_card",
      "payment_method_data": {
        "card": {
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2029,
          "brand": "visa"
        }
      },
      "profile_id": "prof_8e1f2a3b4c5d",
      "merchant_connector_id": "mca_5c4d3e2f1a0b",
      "connector_transaction_id": "993672945374576J"
    }
  }
}

// 1. 将请求体编码为 JSON 字符串
// 2. 使用 payment_response_hash_key 生成 HMAC-SHA512 签名
// 3. 与请求头 x-webhook-signature-512 比对

const crypto = require("crypto");
const expected = crypto
  .createHmac("sha512", payment_response_hash_key)
  .update(JSON.stringify(body))
  .digest("hex");

if (expected !== req.headers["x-webhook-signature-512"]) {
  throw new Error("Invalid webhook signature");
}

{
  "event_type": "report_generation.completed",
  "status": "success",
  "org_id": "org_MZMfl5gFJ7LksZC3rua2",
  "merchant_id": "merchant_1773034629",
  "data": {
    "report_type": "payment_report",
    "start_date_utc": "2026-06-15",
    "end_date_utc": "2026-07-15",
    "download_url": "https://s3.venta.network/reports/payment_20260715.csv?X-Amz-...",
    "expires_in_hours": 48
  }
}

{
  "event": "report_generation.failed",
  "org_id": "org_MZMfl5gFJ7LksZC3rua2",
  "merchant_id": "merchant_1773034629",
  "data": {
    "code": "internal_server_error",
    "message": "Could not generate the report. Please try again."
  }
}

// Report webhooks use the same HMAC-SHA512 verification
// Key: payment_response_hash_key (same as standard webhooks)
// Sign the raw body, compare with X-Webhook-Signature-512 header

const crypto = require("crypto");
const expected = crypto
  .createHmac("sha512", payment_response_hash_key)
  .update(JSON.stringify(body))
  .digest("hex");

if (expected !== req.headers["x-webhook-signature-512"]) {
  throw new Error("Invalid report webhook signature");
}