跳到主要内容

创建订阅

Transactions

使用客户信息、计划详情和支付方式创建新订阅。支持灵活的试用期设置和幂等性保证。

POSThttps://api.efundpay.com/v4/subscriptions
This endpoint requires the subscriptions.write scope.

Authorizations

Authorizationstringheaderrequired

Bearer认证头，格式为 `Bearer <token>`，其中 `<token>` 是您的认证令牌。

Headers

x-merchant-account-idstringrequired

用于此请求的商户账户ID。

Examples:"default"
idempotency-keystring

确保请求幂等性的唯一密钥。如果提供，相同的请求不会被处理多次。

Examples:"unique-key-123"
X-Forwarded-Forstringrequired

连接到服务器的客户端的原始IP地址。

Examples:"203.0.113.195"

Body

application/json
external_identifierstringrequired

此订阅的商户引用标识。用于在您的系统中识别订阅。

Length:1 - 64
Examples:"subscription-12345"
amountintegerrequired

第一期订阅的金额，以分为单位（最小货币单位）。

Examples:"1000""2999"
currencystringrequired

第一期订阅的货币（ISO 4217格式）。

Examples:"USD""EUR"
customerobjectrequired

客户信息对象。

planobjectrequired

订阅计划详情。

payment_methodobjectrequired

支付方式详情。如果商户没有PCI资质，请使用收银台模式重定向到收银台支付页面收集卡信息。

billing_detailsobject

此订阅的账单详情。当 `payment_method.payment_channel_code` 为"J-Pay"时必需

cart_itemsarray

表示订阅行项目的购物车项目数组。当 `payment_method.payment_channel_code` 为"J-Pay"时必需。

browser_infoobject

客户使用的浏览器信息。**直接API模式下必需**。这可用于反欺诈服务。

trial_endstring

试用期结束时间（ISO 8601格式）。

Examples:"2025-09-01T00:00:00Z"
descriptionstring

订阅的描述。

Length:1 - 255
Examples:"Premium Plan with trial period"
metadataobject

用于附加信息的自定义键值对。

Examples:"{"campaign": "summer_promotion", "source": "website"}"

Response

application/json

Successful Response

idstringrequired

唯一订阅标识符。

Examples:"sub_0001"
objectstringrequired

对象类型，始终为"subscription"。

Examples:"subscription"
external_identifierstringrequired

此订阅的商户引用标识。

Examples:"subscription-12345"
amountintegerrequired

第一期订阅的金额，以分为单位（最小货币单位）。

Examples:"1000"
currencystringrequired

第一期订阅的货币（ISO 4217格式）。

Examples:"USD"
createdstringrequired

订阅创建时间（ISO 8601）。

Examples:"2025-08-12T09:00:00Z"
customerobjectrequired

客户信息。

planobjectrequired

订阅计划详情。

payment_methodobjectrequired

支付方式详情。

statusstringrequired

订阅状态：failed、active、past_due、cancelled。

Examples:"failed""active"
current_period_startstringrequired

当前计费期开始时间。

Examples:"2025-08-12T09:00:00Z"
current_period_endstringrequired

当前计费期结束时间。

Examples:"2025-09-12T09:00:00Z"
next_billing_datestringrequired

下次计费日期（YYYY-MM-DD格式）。

Examples:"2025-09-01"
trial_startstring | null

试用期开始时间（如果适用）。

Examples:"2025-08-12T09:00:00Z"
trial_endstring | null

试用期结束时间（如果适用）。

Examples:"2025-09-01T00:00:00Z"
metadataobject

自定义元数据。

Examples:"{}"
payment_url_linkstring | null

完成此订阅支付的URL。当使用结账模式或需要额外支付步骤时提供。

Examples:"https://pay.efundpay.com/abc123""null"
curl --request POST \
  --url https://api.efundpay.com/v4/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'x-merchant-account-id: <x-merchant-account-id>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: unique-key-123' \
  --header 'X-Forwarded-For: 203.0.113.195' \
  --data '{
    "external_identifier": "subscription-12345",
    "amount": 1000,
    "currency": "USD",
    "customer": {
      "display_name": "John Doe",
      "external_identifier": "customer-12345",
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "account_number": "123456789"
    },
    "plan": {
      "name": "Basic Monthly",
      "currency": "USD",
      "amount": 1000,
      "interval": "month",
      "trial_period_days": 14,
      "billing_cycle_anchor": "immediate",
      "payment_attempts": 3,
      "interval_time": 3600
    },
    "payment_method": {
      "payment_channel_code": "card",
      "type": "card",
      "redirect_url": "https://example.com",
      "webhooks_url": "https://merchant.com/webhooks/payment"
    },
    "cart_items": [{
      "name": "Premium Plan",
      "description": "Premium subscription plan with advanced features",
      "quantity": 1,
      "unit_amount": 1000,
      "discount_amount": 0,
      "tax_amount": 0,
      "external_identifier": "premium-plan",
      "sku": "PREMIUM001",
      "product_url": "https://example.com/catalog/premium-plan",
      "image_url": "https://example.com/images/premium-plan.jpg",
      "categories": ["subscription", "premium", "feature"],
      "product_type": "service"
    }],
    "browser_info": {
      "javascript_enabled": true,
      "java_enabled": false,
      "language": "en-US",
      "color_depth": 24,
      "screen_height": 1080,
      "screen_width": 1920,
      "time_zone_offset": -480,
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
      "user_device": "desktop",
      "accept_header": "*/*"
    },
    "metadata": {
      "campaign": "summer_promotion",
      "source": "website"
    },
    "billing_details": {
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "San Jose",
        "country": "US",
        "postal_code": "94560",
        "state": "California",
        "state_code": "US-CA",
        "house_number_or_name": "10",
        "line1": "Stafford Appartments",
        "line2": "29th Street",
        "organization": "EFundFlow"
      }
    }
  }'
{
  "id": "sub_0001",
  "object": "subscription",
  "external_identifier": "subscription-12345",
  "amount": 1000,
  "currency": "USD",
  "created": "2025-08-12T09:00:00Z",
  "customer": {
    "display_name": "John Doe",
    "external_identifier": "customer-12345",
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john@example.com",
    "phone_number": "+1234567890",
    "account_number": "123456789"
  },
  "plan": {
    "name": "Basic Monthly",
    "currency": "USD",
    "amount": 1000,
    "interval": "month",
    "trial_period_days": 14,
    "billing_cycle_anchor": "immediate",
    "payment_attempts": 3,
    "interval_time": 3600
  },
  "payment_method": {
    "type": "card",
    "card": {
      "last4": "1111",
      "expiration_date": "12/27"
    }
  },
  "status": "failed",
  "current_period_start": "2025-08-12T09:00:00Z",
  "current_period_end": "2025-09-12T09:00:00Z",
  "next_billing_date": "2025-09-01",
  "trial_start": "2025-08-12T09:00:00Z",
  "trial_end": "2025-09-01T00:00:00Z",
  "metadata": {
    "campaign": "summer_promotion",
    "source": "website"
  },
  "payment_url_link": "https://pay.efundpay.com/abc123"
}
Powered by Docusaurus