签约

请注意,不建议使用Chargify Direct, Chargify.js.

Chargify.js是一种PCI兼容的方式,可在您的网站上嵌入付款表格,同时仍充分利用我们强大的功能 API.

尽管Chargify Direct仍然可以运行并受支持,但不会添加任何新的增强功能或功能。

认证方式

直接充电资源使用与常规Chargify API不同的凭据。如果您收到401未经授权的回复,请参阅Chargify Direct Introduction中的“身份验证”部分。

注册输入属性

创建注册时,必须在注册对象内指定产品,客户和Payment_profile。可能需要信用卡详细信息,具体取决于所订购产品的选项(请参阅产品选项)。

应税订阅

如果您的意图是通过收取订户税 阿瓦拉税 或者 海关税收, there are a few considerations to be made regarding collecting subscription data. For subscribers to be eligible to be taxed, the following information for the customer object or payment_profile object must by supplied:

  • 订阅 应税产品
  • 完整的有效帐单或送货地址 识别税收地区
  • 地址所在的部分 状态信息 两种地址的任何一种都必须遵守2-3个字符限制/格式的ISO标准。
  • 地址所在的部分 国家信息 必须遵守2字符限制/格式的ISO标准。

  • 示例:不能接受完整的国家名称,例如“美国”,请使用美国。
  • 示例:全州名称(例如“爱达荷州”)使用ID

注册详细信息

The product may be specified by either product[id] 或者 by product[handle], or, if signing up from an 提供, an 提供_id.

产品详情

  • product

    • id 您的客户正在注册的产品的ID
    • handle 您的客户正在注册的产品的API句柄
  • subscription

    • snap_day (可选)用于日历计费。设置为1到28之间的数字,或结束。

优惠详情

范围 描述 需要
提供_id The id 或者 handle of the 提供 您的客户正在注册。 可选,但在使用优惠时是必需的

优惠句柄

If specifying a handle, then you must add the "handle:" prefix. For example, if your offer’s handle is "my-offer", then you would pass 提供_id: "handle:my-offer" in your request parameters.

限制条件

注意你 不能 specify either a product[id]/product[handle], and an 提供_id. Similarly, you cannot specify any components or coupons if you are passing an 提供_id. An offer has its own product/component/coupon configuration.

顾客信息

The customer may be specified by customer[id] or by customer[reference] or by the following attributes as part of the customer object.

范围 描述 需要
first_name 客户的名字 是的
last_name 客户的姓氏 是的
email 客户的电子邮件地址 是的
cc_emails 客户需要的所有抄送电子邮件  
或者ganization 客户的组织  
reference 在您自己的应用程序中为此客户使用的唯一标识符。  
address 客户的送货街道地址(即“ 123 Main St.”)。  
address_2 客户收货地址的第二行,即“ Apt。 100”  
city 客户的送货地址城市(即“波士顿”)。  
state 客户的收货地址状态(即“ MA”)  
zip 客户的送货地址邮政编码(即“ 12345”)。  
country 客户运送地址国家/地区采用ISO 3166-1 alpha-2格式(即 “我们”)。  
phone 客户的电话号码。  

付款资料

The payment profile may be specified by either payment_profile[id] or by the following attributes as part of the payment_profile object.

产品配置或网关设置可能会要求未标记为必需的参数。请注意这一潜在要求。

范围 描述 需要
first_name 卡或银行帐户上的名字 是的
last_name 卡或银行帐户上的姓氏 是的
card_number 完整的信用卡号(字符串表示,即“ 5424000000000015”) 是的
cvv (如果付款方式是信用卡,则为可选)3或4位数字卡的验证值。 是的
expiration_month 1位数或2位数的信用卡有效期,以整数或字符串的形式表示,即“ 5” 是的
expiration_year 4位数字的信用卡有效期,以整数或字符串形式,即“ 2012” 是的
billing_address 信用卡或银行帐户帐单的街道地址(即“ 123 Main St.”)。该值仅传递到支付网关。  
address_2 客户帐单地址的第二行,即“ Apt。 100”  
city 信用卡或银行帐户的帐单邮寄地址城市(即“波士顿”)。  
state 信用卡或银行帐户的帐单邮寄地址状态(即“ MA”)。  
zip 信用卡或银行帐户的帐单邮寄地址邮政编码(即“ 12345”)。  
country 信用卡或银行帐户的帐单邮寄地址国家/地区必须采用ISO 3166-1 alpha-2格式(即“美国”)。该值仅传递到支付网关。某些网关要求使用特定格式的国家/地区代码。请检查网关的文档。目前,在创建银行帐户时,仅接受美国。  
bank_name 客户帐户所在银行的名称 使用ACH创建订阅时需要
bank_routing_number 银行的转帐号码 使用ACH创建订阅时需要
bank_account_number 客户的银行帐号 使用ACH创建订阅时需要
bank_account_type 检查还是节省 使用ACH创建订阅时需要
bank_account_holder_type 个人或企业 使用ACH创建订阅时需要
agreement_terms ACH协议的条款(如果创建使用bank_account作为付款资料的订阅) ACH协议的条款(如果创建使用bank_account作为付款资料的订阅)
payment_type 调成 paypal_account 贝宝所需
payment_method_nonce   贝宝所需
paypal_email   PayPal必需,但仅用于显示
device_data 由Braintree JS生成。例子: //github.com/chargify/chargify_direct_example/tree/device_data 可选的。必须在Braintree中启用。

组件详细信息

通过包括组件密钥,可以将组件附加/分配给注册。子项应该是组件ID,其值是分配的数量。

其他领域

范围 描述 需要
metafields 代表自定义字段及其值的一组键/值对。如果尚未创建元字段,则将在您的站点中为给定密钥“即时”创建元字段。  
ref (可选,请参阅引荐以获取更多详细信息。)有效的引荐代码。  
coupon_code (可选,有关更多详细信息,请参见优惠券。)有效的优惠券代码。  

HTML注册请求

要使用Chargify Direct创建订阅,请向您的网站添加包含以下元素的HTML表单。该表格将直接邮寄到Chargify,我们将在注册后将客户重定向回您。

URL: //api.ikvrej.icu/api/v2/signups Method: POST

<form method="post" action="//api.ikvrej.icu/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- For brevity, this form contains no labels, only inputs -->
  <input type="hidden" name="signup[product][handle]" value="basic" />
  <input type="text" name="signup[customer][first_name]" />
  <input type="text" name="signup[customer][last_name]" />
  <input type="text" name="signup[customer][email]" />
  <input type="text" name="signup[customer][organization]" />
  <input type="text" name="signup[customer][address]" />
  <input type="text" name="signup[customer][address_2]" />
  <input type="text" name="signup[customer][city]" />
  <input type="text" name="signup[customer][state]" />
  <input type="text" name="signup[customer][zip]" />
  <input type="text" name="signup[customer][country]" />
  <input type="text" name="signup[customer][phone]" />
  <input type="text" name="signup[payment_profile][first_name]" />
  <input type="text" name="signup[payment_profile][last_name]" />

  <!-- begin credit card fields -->
  <input type="text" name="signup[payment_profile][card_number]" />
  <input type="text" name="signup[payment_profile][expiration_month]" />
  <input type="text" name="signup[payment_profile][expiration_year]" />
  <!-- end credit card fields -->

  <!-- begin bank account fields -->
  <input type="text" name="signup[payment_profile][bank_name]" />
  <input type="text" name="signup[payment_profile][bank_routing_number]" />
  <input type="text" name="signup[payment_profile][bank_account_number]" />
  <input type="text" name="signup[payment_profile][bank_account_type]" />
  <input type="text" name="signup[payment_profile][bank_account_holder_type]" />
  <!-- end bank account fields -->

  <input type="text" name="signup[payment_profile][billing_address]" />
  <input type="text" name="signup[payment_profile][billing_address_2]" />
  <input type="text" name="signup[payment_profile][billing_city]" />
  <input type="text" name="signup[payment_profile][billing_state]" />
  <input type="text" name="signup[payment_profile][billing_country]" />
  <input type="text" name="signup[payment_profile][billing_zip]" />
  <input type="text" name="signup[payment_profile][payment_type]" />
  <input type="text" name="signup[agreement_terms]" />
  <input type="submit" value="Sign Up" />
</form>

带有报价的HTML示例

使用优惠的ID

Assuming the Offer has an id of 12345:

<form method="post" action="//api.ikvrej.icu/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- This form omits customer, and payment profile information for brevity -->
  <!-- Note that we are not adding any product, component, or coupon-related fields -->

  <input type="hidden" name="signup[offer_id]" value="12345" />

  <input type="submit" value="Sign Up" />
</form>

使用要约的句柄

Assuming the Offer has a handle of "my-offer":

<form method="post" action="//api.ikvrej.icu/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- This form omits customer, and payment profile information for brevity -->
  <!-- Note that we are not adding any product, component, or coupon-related fields -->

  <input type="hidden" name="signup[offer_id]" value="handle:my-offer" />

  <input type="submit" value="Sign Up" />
</form>

带有组件的HTML示例

为了通过Chargify Direct表单设置组件,您可以创建类似于以下内容的表单元素:

组件分配

假设有一个基于数量的组件,名为“ Widgets”,ID为1234;一个开/关组件,ID为5678,名为“ Support”

您希望允许您的用户选择1-5个小部件,然后打开或关闭支持。

<form method="post" action="//api.ikvrej.icu/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- This form omits product, customer, and payment profile information for brevity -->

  <label for="signup_widgets">How Many Widgets?</label>
  <select name="signup[components][1234]" id="signup_widgets">
    <option value="">Please Select</option>
    <option value="1">1</option>
    <option value="2">2</option>
    <option value="3">3</option>
    <option value="4">4</option>
    <option value="5">5</option>
  </select>

  <label><input type="radio" name="signup[components][5678]" value="1">SSL Support On</label>
  <label><input type="radio" name="signup[components][5678]" value="0">SSL Support Off</label>

  <input type="submit" value="Sign Up" />
</form>

使用非默认组件价格点

Passing in a hidden field for price_point_id will override the component’s default price point. It’s important to note that the order of the fields matter; always include the hidden field for component_id first for each component that you add.

Note: if the price_point_id that is passed in is invalid, the signup will still proceed but will default to the component’s default price point.

<form method="post" action="//api.ikvrej.icu/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- This form omits product, customer, and payment profile information for brevity -->

  <input type="hidden" name="signup[components][][component_id]" value="75" />
  <input type="hidden" name="signup[components][][price_point_id]" value="94" />
  <input type="text" name="signup[components][][quantity]" value="3" />

  <input type="hidden" name="signup[components][][component_id]" value="18" />
  <input type="text" name="signup[components][][quantity]" value="10" />

  <input type="submit" value="Sign Up" />
</form>

带自定义字段的HTML示例

自定义字段(或元字段)可以包含在Chargify Direct表单中,如下所示:

<input type="text" name="signup[metafields][color]" />
<input type="text" name="signup[metafields][size]" />

带有优惠券代码的HTML示例

优惠券代码可以包含在Chargify Direct表单中,如下所示:

<input type="text" name="signup[coupon_code]" value="" />

具有多个优惠券代码的HTML示例

可以在Chargify Direct表单中包含多个优惠券代码,如下所示:

<input type="text" name="signup[coupon_codes][]" value="" />
<input type="text" name="signup[coupon_codes][]" value="" />
<input type="text" name="signup[coupon_codes][]" value="" />

带有日历计费的HTML示例

A subscription can be signed up on calendar billing as follows, where the value of snap_day can be 1 - 28 or end (for the last day of the month):

<input type="hidden" name="signup[subscription][snap_day]" value="1" />

成功注册后的HTML重定向

<input type="hidden" name="secure[data]" value="redirect_uri=http%3A%2F%2Fwww.example.com%2Fparameter=value%26parameter2=value"/>

有关如何实现重定向的另一个示例,请参见我们的 Chargify直接示例.

CORS

如果您尝试避免重定向和整页重新加载,例如,如果您正在开发单页应用程序,并且希望通过JavaScript以编程方式提交表单,请注意,不支持跨域资源共享(CORS)默认情况下。请 打开支持票 讨论您的用例并了解可用选项。

JSON注册示例

The signups endpoint also responds to JSON, however since this means sending a request from your own server to Chargify’s server, it is not generally appropriate if you are collecting credit card details. We recommend reviewing Chargify’s 您需要了解的PCI知识 有关更多信息的博客文章。

If you are going to use this method, you must set the Content-Type header of your HTTP POST request to application/json, otherwise the request will be processed as a Chargify Direct request.

无法通过客户的网络浏览器将JSON有效负载直接发布到Chargify,因为这样做需要在客户端公开您的API凭据。

JSON示例请求

URL: //api.ikvrej.icu/api/v2/signups
Method: POST
Content-Type: application/json
{
  "signup": {
    "product": {
      "handle": "pro"
    },
    "customer": {
      "first_name": "Marky",
      "last_name": "Mark",
      "email": "marky@example.com",
      "或者ganization": "Funky Company",
      "reference": "funky-123",
      "phone": "555-555-5555",
      "address": "123 2nd Street",
      "address_2": "Apt 5B",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10004"
    },
    "payment_profile": {
      "first_name": "Marky",
      "last_name": "Mark",
      "card_number": "1234123412341234",
      "expiration_month": "02",
      "expiration_year": "2022",
      "billing_address": "123 2nd Street",
      "billing_address_2": "Apt 5B",
      "billing_city": "New York",
      "billing_state": "NY",
      "billing_country": "US",
      "billing_zip": "10004"
    },
    "components": {
      "1234": 4,
      "5678": 0
    }
  }
}

请注意,上面的示例显示了将ID为“ 1234”的基于数量的组件设置为分配的数量4,并将ID为“ 5678”的On / Off组件设置为“关”。

ACH的JSON示例

{
  "signup": {
    "agreement_terms": "I hereby agree to ACH.",
    "product": {
      "handle": "pro"
    },
    "customer": {
      "first_name": "Marky",
      "last_name": "Mark",
      "email": "marky@example.com",
      "或者ganization": "Funky Company",
      "reference": "funky-123",
      "phone": "555-555-5555",
      "address": "123 2nd Street",
      "address_2": "Apt 5B",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10004"
    },
    "payment_profile": {
      "first_name": "Marky",
      "last_name": "Mark",
      "payment_type": "bank_account",
      "bank_name": "My Bank",
      "bank_routing_number": "123412341",
      "bank_account_number": "123412341234",
      "bank_account_type": "checking",
      "bank_account_holder_type": "personal",
      "billing_address": "123 2nd Street",
      "billing_address_2": "Apt 5B",
      "billing_city": "New York",
      "billing_state": "NY",
      "billing_country": "US",
      "billing_zip": "10004"
    }
  }
}

带有自定义字段的JSON示例

{
  "signup": {
    [...]
    "metafields": {
      "color": "blue",
      "size": "large"
    }
  }
}

JSON示例注册响应

有关详细信息,请参见Chargify Direct Response Parameters。 充实直接响应。 JSON.

The following is an example of a successful JSON POST to /signups:

{
  "result": {
    "status_code": "200",
    "result_code": "2000",
    "errors": []
  },
  "meta": {
    "status_code": "200",
    "result_code": "2000",
    "errors": []
  },
  "signup": {
    "product": {
      "id": 100002,
      "handle": "pro",
      "name": "Pro",
      "accounting_code": "",
      "description": "Pro Super Widget",
      "price_in_cents": 9900,
      "interval_unit": "month",
      "interval": 1,
      "initial_charge_in_cents": null,
      "trial_price_in_cents": null,
      "trial_interval": null,
      "trial_interval_unit": "month",
      "expiration_interval_unit": "never",
      "expiration_interval": null,
      "return_url": "",
      "return_params": "",
      "require_credit_card": false,
      "request_credit_card": true,
      "created_at": "2013-08-23T14:39:41-04:00",
      "updated_at": "2013-09-05T22:58:29-04:00",
      "archived_at": null,
      "product_family_id": 100000
    },
    "customer": {
      "id": 100016,
      "reference": "funky-123",
      "first_name": "Marky",
      "last_name": "Mark",
      "email": "marky@example.com",
      "或者ganization": "Funky Company",
      "address": "123 2nd Street",
      "address_2": "Apt 5B",
      "city": "New York",
      "state": "NY",
      "zip": "10004",
      "country": "US",
      "phone": "555-555-5555",
      "created_at": "2013-09-20T11:19:11-04:00",
      "updated_at": "2013-09-20T11:19:12-04:00"
    },
    "payment_profile": {
      "id": 56,
      "first_name": "Marky",
      "last_name": "Mark",
      "masked_card_number": "XXXX-XXXX-XXXX-1234",
      "card_type": "bogus",
      "expiration_month": 2,
      "expiration_year": 2022,
      "billing_address": "123 2nd Street",
      "billing_address_2": "Apt 5B",
      "billing_city": "New York",
      "billing_state": "NY",
      "billing_country": "US",
      "billing_zip": "10004",
      "current_vault": "bogus",
      "vault_token": "1",
      "customer_vault_token": null,
      "customer_id": 100016,
      "created_at": "2013-09-20T11:19:11-04:00",
      "updated_at": "2013-09-20T11:19:11-04:00"
    },
    "subscription": {
      "id": 100051,
      "state": "active",
      "balance_in_cents": 9900,
      "current_period_ends_at": "2013-10-20T11:19:11-04:00",
      "next_assessment_at": "2013-10-20T11:19:11-04:00",
      "trial_started_at": null,
      "trial_ended_at": null,
      "activated_at": "2013-09-20T11:19:11-04:00",
      "expires_at": null,
      "created_at": "2013-09-20T11:19:11-04:00",
      "updated_at": "2013-09-20T11:19:11-04:00",
      "cancellation_message": null,
      "cancel_at_end_of_period": false,
      "canceled_at": null,
      "current_period_started_at": "2013-09-20T11:19:11-04:00",
      "previous_state": "active",
      "signup_payment_id": 146,
      "signup_revenue": "99.00",
      "delayed_cancel_at": null,
      "customer_id": 100016,
      "product_id": 100002,
      "payment_profile_id": 56
    },
    "next_billing_manifest": {
      "total_tax_in_cents": 0,
      "start_date": "2013-10-20T11:19:11-04:00",
      "line_items": [
        {
          "discount_amount_in_cents": 0,
          "taxable_amount_in_cents": 9900,
          "transaction_type": "charge",
          "kind": "baseline",
          "amount_in_cents": 9900,
          "memo": "Pro (10/20/2013 - 11/20/2013)"
        }
      ],
      "total_discount_in_cents": 0,
      "end_date": "2013-11-20T11:19:11-05:00",
      "subtotal_in_cents": 9900,
      "total_in_cents": 9900,
      "period_type": "recurring"
    }
  }
}

回应失败

Any errors will be returned within the meta[errors] and result[errors] objects. For example, when trying to create a new subscription without passing in the payment_profile[expiration_month], the following is returned:

{
  "result": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "payment_profile.expiration_month",
        "message": "Credit card expiration month: cannot be blank."
      }
    ]
  },
  "meta": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "payment_profile.expiration_month",
        "message": "Credit card expiration month: cannot be blank."
      }
    ]
  }
}

Not passing in a customer at all will yield the following response:

{
  "result": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "customer",
        "message": "A Customer must be specified for the subscription to be valid."
      }
    ]
  },
  "meta": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "customer",
        "message": "A Customer must be specified for the subscription to be valid."
      }
    ]
  }
}