托管支付页面 (HPP)

托管支付页面 (Hosted Payment Page) 是 GoGoPay 提供的安全、美观的支付界面，让您无需处理敏感的支付信息，即可为用户提供完整的支付体验。

什么是托管支付页面？

托管支付页面 (HPP) 是由 GoGoPay 托管的安全支付界面，具有以下特点：

PCI DSS 合规：符合最高级别的支付卡行业安全标准
响应式设计：完美适配桌面和移动设备
多语言支持：支持多种语言和货币
品牌定制：可自定义颜色、Logo 等品牌元素
快速集成：几行代码即可完成集成

                    优势： 使用 HPP 可以大大简化您的 PCI 合规要求，因为敏感的支付信息不会经过您的服务器。
                

集成流程

集成 HPP 只需要三个简单步骤：

步骤 1：创建支付会话

在您的后端调用 GoGoPay API 创建支付会话：

POST /v1/checkout/sessions

curl -X POST https://api.gogopay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_types": ["card"],
    "line_items": [{
      "price_data": {
        "currency": "cny",
        "product_data": {
          "name": "商品名称"
        },
        "unit_amount": 2000
      },
      "quantity": 1
    }],
    "mode": "payment",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'
                

步骤 2：重定向到支付页面

将用户重定向到返回的 url 字段：

// JavaScript 示例
fetch('/create-checkout-session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [{ id: 'product-1', quantity: 1 }]
  })
})
.then(response => response.json())
.then(session => {
  // 重定向到 GoGoPay 托管的支付页面
  window.location.href = session.url;
})
.catch(error => {
  console.error('Error:', error);
});
                

步骤 3：处理支付结果

用户完成支付后，会被重定向到您指定的成功或取消页面。同时，您会收到 Webhook 通知。

API 参数详解

创建支付会话时，您可以配置以下参数：

必需参数

参数	类型	描述
`payment_method_types`	array	支持的支付方式，如 ["card", "alipay", "wechat"]
`line_items`	array	商品列表
`mode`	string	支付模式："payment", "subscription", "setup"
`success_url`	string	支付成功后的重定向 URL
`cancel_url`	string	支付取消后的重定向 URL

可选参数

参数	类型	描述
`customer`	string	客户 ID，用于保存支付方式
`customer_email`	string	客户邮箱，会预填到支付表单
`locale`	string	界面语言："zh", "en", "ja" 等
`metadata`	object	自定义元数据，最多 50 个键值对
`expires_at`	timestamp	会话过期时间，默认 24 小时

品牌定制

您可以自定义支付页面的外观以匹配您的品牌：

{
  "payment_method_types": ["card"],
  "line_items": [...],
  "mode": "payment",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "custom_text": {
    "submit": {
      "message": "我们将在 2-3 个工作日内处理您的订单"
    }
  },
  "ui_mode": "hosted",
  "branding": {
    "logo": "https://example.com/logo.png",
    "primary_color": "#1a73e8",
    "background_color": "#ffffff"
  }
}
                

支付方式配置

GoGoPay 支持多种支付方式，您可以根据业务需求选择：

信用卡/借记卡

"payment_method_types": ["card"]

数字钱包

"payment_method_types": ["alipay", "wechat", "apple_pay", "google_pay"]

银行转账

"payment_method_types": ["bank_transfer", "sepa_debit"]

组合支付方式

"payment_method_types": ["card", "alipay", "wechat", "apple_pay"]

订阅支付

HPP 也支持订阅支付模式：

{
  "payment_method_types": ["card"],
  "mode": "subscription",
  "line_items": [{
    "price": "price_1234567890", // 预先创建的价格 ID
    "quantity": 1
  }],
  "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://example.com/cancel"
}
                

处理支付结果

用户完成支付后，有多种方式获取支付结果：

1. URL 参数

在 success_url 中使用模板变量：

"success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}"

2. 查询会话状态

// 在成功页面查询会话详情
fetch(`/checkout/sessions/${sessionId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_...'
  }
})
.then(response => response.json())
.then(session => {
  if (session.payment_status === 'paid') {
    // 支付成功，处理业务逻辑
    console.log('Payment successful!');
  }
});
                

3. Webhook 通知

推荐使用 Webhook 来处理支付结果，确保可靠性：

// Webhook 处理示例
app.post('/webhook', (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'checkout.session.completed':
      const session = event.data.object;
      // 处理支付成功逻辑
      fulfillOrder(session);
      break;
    case 'checkout.session.expired':
      // 处理会话过期
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }
  
  res.status(200).send('OK');
});
                

安全最佳实践

HTTPS 必需：所有 URL（包括重定向 URL）必须使用 HTTPS
验证会话：在成功页面验证会话状态，不要仅依赖 URL 参数
使用 Webhook：使用 Webhook 确保支付状态的可靠通知
幂等性：确保重复的 Webhook 事件不会重复处理
超时处理：设置合理的会话过期时间

移动端优化

HPP 自动适配移动设备，但您可以进一步优化用户体验：

深度链接

支持移动应用的深度链接：

"success_url": "myapp://payment/success?session_id={CHECKOUT_SESSION_ID}",
"cancel_url": "myapp://payment/cancel"
                

移动钱包

启用移动设备上的数字钱包：

"payment_method_types": ["card", "apple_pay", "google_pay", "samsung_pay"]

测试和调试

在沙箱环境中测试 HPP 集成：

// 沙箱环境配置
const gogoPayConfig = {
  apiKey: 'sk_test_...', // 使用测试密钥
  apiUrl: 'https://sandbox-api.gogopay.com'
};

// 创建测试会话
fetch('https://sandbox-api.gogopay.com/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${gogoPayConfig.apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_method_types: ['card'],
    line_items: [{
      price_data: {
        currency: 'cny',
        product_data: { name: '测试商品' },
        unit_amount: 1000
      },
      quantity: 1
    }],
    mode: 'payment',
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel'
  })
})
.then(response => response.json())
.then(session => {
  window.location.href = session.url;
});
                

常见问题

问题	原因	解决方案
支付页面无法加载	会话已过期或 URL 无效	重新创建支付会话
重定向失败	URL 不是 HTTPS 或格式错误	检查 success_url 和 cancel_url
支付方式不显示	地区限制或配置错误	检查支付方式配置和地区设置
品牌定制不生效	图片 URL 无效或格式不支持	使用 HTTPS 图片 URL，支持 PNG/JPG

性能优化

预加载：在用户点击支付前预创建会话
缓存：合理缓存商品和价格信息
压缩：压缩传输的数据
CDN：使用 CDN 加速静态资源

下一步

现在您已经了解了 HPP 的使用方法，可以：

使用测试卡号 - 在沙箱环境中测试支付流程
配置 Webhook - 接收支付状态通知
注册 Webhook 端点 - 在控制台配置通知地址