概述

请注意,已弃用的Chargify Direct赞成 chargify.js..

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

虽然Chargify Direct仍将运行并受支持,但不会添加新的增强功能或功能。

直接充电通常需要更具技术上经验丰富的商家,有时需要在实施期间提供技术专家支持。我们的高级Chargify计划提供了我们的技术专业支持。

欢迎您使用Chargify的任何计划级别使用Chargify。但是,如果您需要帮助,我们会向上询问您在一个包含先进技术支持的计划中。

请注意,Chargify Direct目前不支持创建基于手动发票的订阅者。

直接充电允许您通过自己的网站上的表格创建Chargify Resources(如订阅),该网站将直接发布到Chargify。 Chargify后收到表单提交后,将用户重定向到您自己的网站。重定向传达提交结果,以便您的网站可以决定如何响应用户。此流程有时在行业内称为“透明重定向”。

请注意,使用Chargify Direct是完全不同于CharGify的API的实施。

  • Chargify的API使用使用您网站的子域构造的单独端点。
  • 直接充电 uses the endpoint //api.ikvrej.icu/api/v2/.. as the basis for all calls made.
  • 方法和端点和示例不可互换。请注意,在进行之前,您正在使用什么空间。

参考实施

一个小型SINATRA应用程序已被建造为作为Chargify Direct的参考实施。它可以在这里提供:

//github.com/chargify/chargify_direct_example

好处

  • 您的用户永远不会在整个流程中留下您的网站
  • 您的PCI合规范围急剧减少,因为您永远不会处理或传输敏感卡数据

详细的流量

  1. 您可以在您自己的网站上制作一个表格,将帖子发布到Chargify的Chargify Direct Resource端点之一。此表单必须包含正确的安全参数,也应具有正在创建资源的参数。可选地,您可以添加将在镜像参数中反映回给您的参数。

  2. Chargify收到表格帖子并处理如下:

    • 通过其加密签名验证安全参数中发送的信息
    • 如果验证,则通过传递的参数尝试创建所请求的资源
    • 是否创建了资源,有关表单帖子的详细信息并通过CharGify记录。在Chargify Direct API中提供了此“呼叫”的记录
  3. Chargify重定向到您定义的URI,在查询字符串中添加包含有关原始请求结果的信息的签名响应参数

    • 您的应用通过计算和比较结果的加密签名验证响应参数中发送的信息
    • 您的应用程序可以完全基于响应参数中给出的状态的成功/失败屏幕
    • 为了更好的用户体验,您的应用程序可以进行常规API访问来获取原始呼叫的记录,其中包含请求(减去敏感持卡人数据),响应和结果。如果结果是成功,您将拥有有关要显示的资源的信息。如果结果是失败,您将能够重新显示您的表单,预先填充大部分原始表单,其中包含最初提交的值和查明错误

安全参数

每个Chargify Direct Post必须包含一组加密签名的安全参数。安全参数是必要的,以便:

  • 验证请求,以便Chargify可以验证它来自受信任的源(因为互联网上的任何人可以发布到Chargify Direct Endpoints.)
  • 允许您与请求一起发送防篡改数据
  • 指定重定向URI(或覆盖默认值)
api_id. 必需的 由Chargify分配的API ID(请参阅API用户凭据)
时间戳 选修的 请求的时间是自1月1日1970 00:00 UTC(即Unix时间)以来经过的整数秒数。如果提供时间戳,它将在响应参数中反映回给您,并且可以用于使请求无效,如果它比某个阈值较大(请参阅下面的时间戳请求)
omce. 必需的 用于唯一可卸载请求的字符串(最多40个字符)。当时间戳和API ID范围时,随机数必须是唯一的。使用随机数提供,它将在响应参数中反映回给您,并且 可能 如果匹配相同时间戳的先前使用的值(参见随机值),则用于使请求无效
数据 选修的 URL查询字符串格式中的字符串可用于传输篡改数据以通过表单充电(参见安全数据)。请注意,您将希望在嵌入表单之前在此字符串中转义任何HTML字符。
签名 必需的 基于其他4个安全输入和API用户的共享API_SECRET的验证签名(参见签名计算)

应将这些安全输入发送到Chargify通过Chargify Direct Endpoint嵌套在安全参数内。例如,以下表格演示如何使用隐藏的表单输入来提交所有5个安全输入:

<form method="post" action="//api.ikvrej.icu/api/v2/signups">
  <input type="hidden" name="secure[api_id]"    value="1234" />
  <input type="hidden" name="secure[timestamp]" value="1301148971" />
  <input type="hidden" name="secure[nonce]"     value="5b2763d0-39e1-012e-858d-64b9e8d3946e" />
  <input type="hidden" name="secure[data]"      value="one=uno&amp;two=dos" />
  <input type="hidden" name="secure[signature]" value="412951d095ebbb3800dfb2126fe5073d2ab6c260" />
</form>

时间戳请求

向您的请求添加时间戳可以帮助防范重播攻击和重复的提交,但也有可能降低有效用户的体验。如果您没有向您的请求发送时间戳,则Chargify将不会根据时间戳年龄或时间戳 - Nonce对重复执行任何拒绝。

必须将时间戳指定为自1月1日00:00:00 UTC(即Unix时间)以来经过的整数秒数。 不包括米氏乳头。 (在Ruby中,这可以通过将时间对象传递给整数,即Time.now.to_i_I_I)可用

如果您将时间戳提交了您的请求,它将包含在响应参数中,并在获取呼叫时可用。如果您未提交时间戳,将自动生成一个。

此时,Chargify不会根据时间戳的年龄拒绝任何提交。只会拒绝重复的时间戳。此机制的具体细节将于将来发布。

omce值

向您的请求添加Nonce有助于防范重播攻击和重复提交。

  • Nonce的值必须为40个字符或更少。

  • 如果您没有使用注册请求发送unmce,则Chargify将生成一个,但不会根据时间戳-Monce对重复执行任何拒绝。

  • The nonce is required for the card_update endpoint.

  • 在响应参数中,随机将反映给您。

安全数据

安全输入中的数据参数使您有机会以及您的表单提交提供篡改属性。通常,您将为正在创建的资源提供参数,以便您不希望用户能够更改。例如,您可以将产品句柄包含用于注册,以便表单仅适用于为指定产品创建订阅。如果在普通资源参数中发送相同的参数,则该参数将被安全数据中的一个参数覆盖。

除非您已经注册了您正在访问的端点的默认重定向URI,否则安全数据中的一个参数必须是redirect_uri。

例如,考虑包含以下两个隐藏表单输入的表单:

<input type="hidden" name="secure[data]" value="signup[product][handle]=pro" />
<input type="hidden" name="signup[product][handle]" value="basic" />

As long as the submission passes signature validation, the value of pro would be used, not basic, for the signup[product][handle] parameter.

The value attribute of the secure[data] parameter should be a string of data in query-string format:

  • 查询字符串由一系列字段值对组成
  • 字段值对每个由等号分隔。如果该值是空字符串,则可以省略等号
  • 一系列成对由ampersand分开('&’)

您的单个键和值应该是自己的URL编码,但整体字符串不应该是。由于您的字符串将插入输入标记的值属性内,因此它应该是HTML实体转义。考虑以下隐藏输入:

<input type="hidden" name="secure[data]" value="address[city]=Raleigh&amp;address[state]=North%20Carolina&amp;hobbies[0]=soccer&amp;hobbies[1]=snowboarding&amp;hobbies[2]=playing%20inside%20the%20%3Chtml%3E%20tag%20at%20http%3A%2F%2Fchargify.com" />

上面的输入将解析为以下数据结构(在YAML中表示):

---
  address:
    city: Raleigh
    state: North Carolina
  hobbies:
  - soccer
  - snowboarding
  - playing inside the <html> tag at //ikvrej.icu

签名计算

The signature is the hexadecimal representation of a computed Hash-based Message Authentication Code, using SHA-1 as the cryptographic function (HMAC-SHA1). The secret for the function is the API shared secret (api_secret) issued to the API user by Chargify. The message for the function is the concatenation of the api_id., 时间戳, omce., and data parameters 在这个命令 。未给出的任何可选参数都被转换为空字符串。

HMAC-SHA1(api_secret, api_id+timestamp+nonce+data)

在Ruby中,是一个例子 //github.com/chargify/chargify_direct_signature_example

此应用程序还可以作为计算的在线验证者。它可以访问 //chargify-direct-signature.herokuapp.com/

重定向Uri.

In order to tell Chargify where to redirect after attempting to create the resource, you should specify a value for redirect_uri within your secure data. This value is not read from normal parameters so, if included, it must be within your secure data paramters.

For example, the following form would attempt to create a signup resource at Chargify and then redirect to //www.example.com (with the response parameters in the query string):

<form action="//api.ikvrej.icu/api/v2/signups" method="post">
  <input type="hidden" name="secure[api_id]" value="my_api_id"/>
  <input type="hidden" name="secure[data]" value="redirect_uri=http%3A%2F%2Fwww.example.com"/>
  <input type="hidden" name="secure[signature]" value="bd8629eba9bd1c134b3a8c6352d784b9f86fb6a9"/>
  <!-- Resource parameters here-->
  <input type="submit" value="Submit"/>
</form>

镜子参数

镜像参数目前尚未在Chargify中实现

您的表单可能会将任何数据(格式化为安全数据)到镜像参数。作为响应参数的一部分,此数据将反映回给您,unltered。

此参数的目的是为您的应用程序作为便利性“钩”。您可以决定将额外的数据添加到您的提交中,只能在客户端计算,即检测javascript功能并为自己设置标志。

请将此参数中传递的数据量保存到最低限度。由于建议查询字符串具有少于255个字符,并且重定向将使用查询字符串传递结果参数,添加冗长的镜像参数可能导致Web服务器的兼容性问题。

直接充电 Endpoints.

注册

创建注册创建订阅,并可创建或引用现有的客户和付款配置文件。

资源URI: //api.ikvrej.icu/api/v2/signups

卡更新

使用新信息更新订阅的付款方式。

资源URI: //api.ikvrej.icu/api/v2/subscriptions/<subscription.id>/card_update

请参阅API: 卡更新 for more details.

资源参数

您的表单应包含您正在创建的资源的参数,除非它们都放在安全数据内(不太可能)。

资源参数嵌套在资源之后名为的密钥下方,并且类似于资源的正常API输入。例如,以下表格包括所有必要的输入,用于创建带有新客户和付款配置文件的注册:

<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[payment_profile][first_name]" />
  <input type="text" name="signup[payment_profile][last_name]" />
  <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]" />
  <input type="submit" value="Sign Up" />
</form>

见Chargify. 直接注册 有关输入参数的完整列表。

响应参数

当Chargify重定向到重定向URI时,它将包括以下查询字符串参数:

api_id. 制作原始请求的API ID
时间戳 反射或自动生成的时间戳
omce. 反射或自动生成的omce
status_code. 表示请求状态的HTTP状态代码。使用用于API资源创建的相同代码。
结果_code. 特定于特定的结果代码,与状态代码有关,但可能会提供有关请求结果的更具体信息
call_id. 用于原始呼叫的存储表示的ID(表单POST)。可以通过API获取呼叫以进行全响应信息(用于成功和失败场景)。
签名 先前参数的HMAC-SHA1六角形,验证他们的完整性

响应签名

响应的签名是计算的十六进制表示 “基于哈希的消息认证码”, using SHA-1 as the cryptographic function (HMAC-SHA1). The secret for the function is the API shared secret (api_secret) issued to the API user by Chargify. The message for the function is the concatenation of the api_id., 时间戳, omce., status_code., 结果_code., and call_id. parameters.

HMAC-SHA1(api_secret, api_id+timestamp+nonce+status_code+result_code+call_id)

结果代码

代码 描述
4001 身份验证失败
4011 由于缺少随机值,身份验证失败
4040 无法找到所请求的对象(例如订阅)
4220 输入上的一个或多个验证错误
4221 重复提交
4300 卡下降
5000 发生了错误
5001 请求的资源不存在

获取电话

直接充电 Endpoint的帖子与制作API调用相同。记录此调用并在API中作为呼叫资源可用。此资源可用原始请求参数,响应值和结果。

When using Chargify Direct, the response parameters will include a call_id. pointing to the call that was created as a result of your form post. You may fetch this call from //api.ikvrej.icu/api/v2/calls/<call_id> using your Chargify Direct credentials.

在开发过程中,您可能希望使用CURL来获取呼叫以查看任何错误消息。例如:

curl -u <CHARGIFY_DIRECT_API_ID>:<CHARGIFY_DIRECT_PASSWORD> -H Accept:application/json -H Content-Type:application/json -X GET //api.ikvrej.icu/api/v2/calls/<CALL_ID>.json

API.:呼叫 有关输出字段的完整列表。

验证

直接充电的身份验证取决于请求类型。 验证Chargify Direct请求 (application/x-www-form-urlencoded)

您的表单POST通过表单提交中包含的安全参数进行身份验证。

验证服务器到服务器API请求(应用程序/ JSON)

直接充电支持HTTP基本身份验证。

HTTP基本身份验证

HTTP基本身份验证 (on wikipedia) is available using your api_id. and api_password. It works the same as described in the article on API authentication, only the credentials are different.

您的Chargify Direct API ID和密码对您的每个站点都不同,并且可以在以下位置找到:

  • 配置→
  • 整合→
  • API.键/ Chargify In Appliation