facebook充值实时更新接口文档翻译 希望对做facebook充值的小伙伴有帮助

Realtime Updates for Payments are an essential method by which you are informed of changes to orders made through Facebook Payments within your app. Facebook has built Realtime Updates for Payments with a focus on reliability, allowing your app to depend on them for accurate and timely updates representing the latest state of payments within your app.

充值及时更新是一个基本的通知你facebook的应用支付的订单改变的方法，facebook内置了专注的稳定的可依赖的充值及时更新接口，允许你更精确和及时的更新代表着应用订单的最新状态；

POST

及时更新是基于facebook和你的服务器的订阅系统，你的应用订阅接收facebook的更新通过一个特定的http端点，当你的应用的一个订单发生发生改变时，facebook就发起一个http的post请求到这个http端点，通知你的服务器做出更改。

As part of Facebook’s commitment to providing people with the best possible payment experiences, as of May 2014, the subscription and processing of Realtime Updates for the payments object will be a mandatory requirement of accepting payments on Canvas.

作为facebook承诺提供给人民可能是最好的支付体验的一部分，从2014年5月份开始，作为cavas应用的充值，订阅和处理充值及时更新这个对象是一个强制的要求。

There are three primary scenarios in which Realtime Updates are sent to your developer server:

充值及时更新有三种基本的场景推送到你的开发服务器上的时候
完成付款
退款，拒付，拒付逆转和拒付降低
纠纷

When a person attempts to make a purchase in your app, there are two methods through which you are notified of the outcome, a JavaScript callback and a Realtime Update. You must handle both of these methods to fully support the range of payment options provided by Facebook.

当一个顾客尝试在你的应用里面进行购买，有两种方法可以通知你购买的结果，一种是js的回调，另外一种是及时更新接口，你必须处理这两种方法的通知来支持facebook提供的一些列支付选择。

After the person has finished entering their payment details in the purchase flow, Facebook will return details of the order via the JavaScript callback specified when initiating the Pay Dialog - see Order Fulfillment for more information. This callback is invoked as the purchase flow ends, without necessarily waiting for the transaction to fully complete. Such transactions may complete asynchronously at a later time. As an example, there are payment methods supported by Facebook where the consumer is required to print out an order completion form and physically deposit it at their bank. These methods can take hours or even days to complete.

顾客在购物流程中输入完支付明细之后，当初始化支付对话框的时候，facebook就会通过javascript的回调返回订单的明细-查看完成订单的更多信息，这个回调被调用当购买流程结束的时候，而没有必要等着事物完全结束。这个事物可能会异步的完成在稍后的时刻，举个例子，有一个支付的方法支持facebook当一个顾客需要打印出订单的完成表单和银行的实际储蓄支出，这些方法可能会需要几个小时或者几天才能完成。

initiated

之所以给出这些场景，这使得专门的满足完成的订单通过js回调成为可能，因为当js回调的时候，某些订单就会处于未完成的初始化状态

Additionally, there are other circumstances in which the JavaScript callback method of order fulfillment cannot be exclusively relied upon. For example, when a person's connectivity to your app is unreliable, the callback may never be triggered. This may occur if the consumer loses connection to the internet mid-flow, or closes their browser.

除此之外，也有些别的情况，订单完成的js回调方法不能专门的信任，例如：当一个顾客到你的应用的连接是不可信任的，这个回调从来不会触发，这个也许会发生当一个顾客在购物流程当中丢失网络连接或者关闭他们的浏览器的时候。

Facebook accounts for these scenarios by sending a Realtime Update to your server every time a payment is completed (either synchronously or asynchronously). This allows you to fulfill orders that complete asynchronously and robustly handle the range of circumstances that may interrupt the client side payment flow.

facebook帐号对这些场景发送实时更新当你的服务器 ，当每次支付完成的时候（同步或者异步），这允许你 异步完成或者费力的处理一些列可能打断客户端的支付流程的场景完成订单。

If you do not support order fulfillment via a Realtime Update, you risk creating a significantly negative user experience where your consumers will never receive the virtual-item they successfully purchased. This will ultimately lead to an increase in refunded purchases, impacting your revenue and reputation.

如果你不支持通过实时更新来完成订单，你冒着风险去创建一个你的顾客将不会收到虚拟物品当他们成功支付的明显消极的用户体验 。这最终会导致退款的增加，影响你的收入和声誉。

Refunds, Chargebacks, Chargeback Reversals and Declines

There are times when you may wish to issue a refund to a consumer for a payment made within your app. It is also important to be aware that there are some circumstances in which Facebook can and will issue refunds directly. In both cases, when the refund is issued, Facebook will send a Realtime Update to your server. Subscribing and responding to Realtime Updates is the only way to keep your records up to date and in sync with Facebook.

退款，拒付，拒付逆转和拒绝
有这个当你希望发起退款给一个在你的应用中完成支付顾客的时间，意识到有一些场景 facebook可以就会发起直接的退款同样很重要，在这些场景当中，当退款发起的时候，facebook就会发送一条试试更新信息到你的服务器，订阅和回应实时更新是唯一的方法来保持你的记录最新和同步facebook

A chargeback occurs when a consumer in you contacts their payment provider directly (e.g., credit card company or PayPal) to dispute a charge. A chargeback can happen for a variety of reasons, including unauthorized use of a financial instrument, double billing, or non-receipt of a virtual good.

A chargeback reversal will occur in the rare circumstance where the consumer invokes a chargeback via their bank, then later the bank determines the chargeback was not warranted. In this scenario the developer is paid for the transaction as normal.

当一个拒付发生的时候，顾客直接联系支付提供方（例如信用卡公司或者贝宝公司）来争议支付，一个拒付发生可能因为多种原因，包括非授权的使用财政设备，多重账单，或者没收到虚拟物品。
一个拒付的逆转会发生在这些罕见的场景，顾客通过银行发起了一个拒付，稍后银行决定拒付是否需要，这种情境下，开发者被当作正常的事物支付了。

decline

As with refunds, you will also be notified via a Realtime Update when a chargeback, chargeback reversal or decline have been issued.

还有，在这些案例中，facebook就会尝试绑定小的支付到一个单独的事物中，对这些事物，这种绑定被处理，当顾客收到所谓的美元门槛或者之后一段时间，这这种时候，如果支付方没有足够的资金来完成这个事物，就在这个束中所有的支付会标记为拒绝。
对退款来说，你就会别通知通过一个实时更新当拒付，拒付逆转或者拒绝拒付被发起的时候。

For more information about the dispute and refund process, please see Payments How-To: Handling Disputes and Refunds.

If you do not subscribe to refund notifications via Realtime Updates, you will be unaware (before payout) of any refunds issued directly from Facebook and will therefore be unable to respond to the associated consumer issue or concern.

更多关于争议和退款的流程信息，请看支付如何处理争议和退款。
如果你没有订阅一个通过实时更新接口的退款的通知，你不会意识到（支出之前）被直接从facebook发起了的任何退款，因此不能响应客户相关的问题和担忧。

Disputes

There are occasionally times when a consumer will wish to dispute a payment made in your app. They can do this via various methods on Facebook which are fully detailed in Payments How-To: Handling Disputes and Refunds.

Facebook will notify you by issuing a Realtime update when a dispute is initiated. This is the only method in which you are notified of the existence of a dispute. Handling and responding to disputes are an important part of providing a trustworthy service to your customers, so it is essential that you subscribe to dispute Realtime Updates.

If you do not subscribe to dispute notifications via Realtime Updates, you will create a negative user experience for your customers by ignoring their payment disputes. Facebook considers the handling of consumer disputes a mandatory requirement of Facebook Payments.

争议
有这种场景的时候，当顾客想要争议一个在你的应用中的支付，他们可以通过各种facebook的方法，在这里有详细的说明 支付如何处理争议和退款
facebook就会通知通过一个试试更新当争议被初始化的时候，这是唯一的方法你被通知有争议的存在，处理和回应争议是对你的顾客提供一个可值得信耐的服务的一个重要的部分 ，所以你必须订阅争议试试更新接口。
如果你没有订阅争议通知通过实时更新接口，你会创造一个对你的用户通过忽略他们的支付争议的消极的用户体验，facebook考虑把处理用户的争议作为对facebook的支付的一个基本的要求

Subscribing to Realtime Updates

GETPOSTpayment

In either case, your endpoint will receive the same data in the same manner. See Your Callback Server for more information on what your server should expect to receive.

Subscribing to Realtime Updates via the App Dashboard

Payments

订阅实时更新接口通过应用的控制面板
最容易的方法来安装你的应用来接收实时更新是使用应用控制面板的支付面板，找到你的应用的面板，然后点击支付标签，实时更新接口就会在你公司设置区域上面。

This screen will then list your app's subscription status, whether it has been added through this panel or the API. From here, it's possible to change the subscription callback URL and test it.

In the 'Callback' field, you must provide a valid publicly-accessible server endpoint. This is the address that Facebook will use to both verify the subscription, and send the updates, and needs to respond as described in Your Callback Server.

Finally, provide a 'Verify token'. This can be an arbitrary string, which will be sent to your endpoint when the subscription is verified so that you can be sure the verification process is taking place because of this particular new subscription

这个屏幕就会列出你的应用订阅的状态，无论你是否已经 通过这个面板或者api添加 ，在这里，你可以改变你的订阅回调url，并测试它。
这回调字段域，你必须提供一个合法的公共权限的服务器端点，这个地址facebook的校验和订阅将会使用，发送更新，需要返回信息 如同你的回调服务器中描述的。
最后，提供一个校验的令牌，这可以是一个 随意的字符串，你可以发送到你的端点当订阅被校验，因为这个特殊的新订阅你可以确认校验的过程发生

Testing your settings

hub.modehub.challengehub.verify_tokenhub.challenge

测试你的设置
你应该测试回调的设置在保存订阅之前，这会发起一个get的请求到你的服务器的校验，包含hub.mode ,hub.challenge和hub.verify_token参数，你必须确保正确的处理他们，例如，你必须确认你的端点回显hub.challenge到facebook.

Once you’ve entered your subscription details, be sure to click the ‘Save Changes’ button at the bottom of the page.

Editing a subscription is a simple matter of altering the contents of the fields, re-testing, and then saving the form again.

Only subscriptions on the page that have been edited will cause a new verification to be sent to your server when the form is submitted.

Note that if you leave this page and return, the verification code (which has served its purpose) will have been removed from the form. So if you need to then update an existing subscription, you'll need to enter it again if your endpoint is sensitive to its presence.

一旦你输入了你订阅的详情，要保证点击 页面底部的 保存修改按钮
改改订阅是一件简单的事情 更改字段的内容，重复测试 ，最后又保存表单。
止呕在这个页面的订阅被修改才会发起一个新的校验到你的服务器，当表单提交的时候
注意如果你不理会这个页面并返回，你的检验码（已经解释过它的目的了）就会从这个表单中被移除。所以如果你需要更新已存在的订阅，你需要再次输入它如果你的端点敏感  对它的出现。

Subscribing via the Graph API

access token/oauth

The Subscription API is available on the endpoint (with your app's ID substituted). There are three tasks you can perform with it:

POSTGET

access_token

通过图形pai订阅
也可以通过程序化的方式安装和列出订阅，通过图形化的api，你需要你应用的通过令牌工具或者通过图形api的oauth端点来获取access token （权限令牌）
订阅api是可用的 在 端点（替换你的应用id），有三个任务你可以处理。
增加或者修改订阅（通过发送一个http的post请求）
列出每一个存在的订阅（通过发送一个htt的get请求）
在所有的案例中，你需要发送你应用的权限令牌所谓一个查询字符参数

Adding and modifying subscriptions

POST

objectpaymentsfieldscallback_urlverify_token

POSTGEThub.challenge

Note that, because an app can only have one subscription for each object type, if a subscription already exists for this object type, then the newly-posted data replaces any existing data.

增加和修改订阅
为了安装订阅，发送一个post请求带上下面的参数，注意 对上面描述的表单中的字段的一致性
object 如同上面的，object的类型你想接收更新，指定为payments
fields  一个对队形类型的分割标记的属性列表 你需要更新相关的 注意actions 和diputes
callback_url  一个合法的功能权限的服务器端点
verify_token 一个随便的字符，当订阅确认的时候发送到端点
当facebook接收到这个post请求，如同上面表单配置，facebook将会差生一个get请求到你的回调url中来确认它是合法的并准备接收实时更新消息，实际情况，你必须保证你的端点返回hub.challenge到facebook.
注意：因为一个应用只能有一个订阅对每个对象类型，如果订阅已经存在了对应的对象类型，之后一个新的推送数据会替换已经存在的数据

Listing your subscriptions

GET

[

  {

    "object": "payments",

    "callback_url": "http://www.friendsmash.com/rtu.php",

    "fields": ["actions", "disputes"],

    "active": true

  }]

You can use the Graph Explorer to experiment with this API directly, remembering to use your app'saccess token.

列举出你的订阅
发起一个http的get请求到订阅的api，返回一个json编码的内容列举出你的订阅，例如：
省略
你可以使用图形浏览器来直接实验这些api，记住使用你的权限令牌

Your Callback Server

Your callback server must handle two types of requests. Ensure it is on a public URL so that Facebook can make these requests successfully.

你的回调服务器
你的回调服务器必须处理两种类型的请求，确保为一个公共的url，facebook可以成功的发送这些请求

Subscription Verification

GET

hub.modesubscribehub.challengehub.verify_tokenverify_token

hub.verify_token

hub.challenge

$_GET['hub_mode']$_GET['hub_challenge']$_GET['hub_verify_token']

Receiving Updates

POST200

200

application/json

Note for PHP developers: In PHP, to get the encoded data you would use the following code:

$data = file_get_contents("php://input");

$json = json_decode($data);

hub.modehub.challengehub.verify_token

接收更新
按照一个成功的订阅，facebook会处理发起一个http的post请求到你的服务器端点，每次当有改变发生的时候（对所选的字段或者连接），你必须响应这个请求，使用http的代码200
注意，facebook把别的htpp响应只要不是200的当成错误，这这些场景中，facebook就会继续尝试发送实时更新，如果你没有返回正确的相应，所以，你也许会接收到相同的更新很多次。
这个请求含有内容类型为application/json，并且身体将会包括json编码的字符串包含一个或者更多的改变。
php开发者注意：在php中，给了获得编码的数据，你需要使用下面的代码

$data = file_get_contents("php://input");

$json = json_decode($data);

注意hub.mode,hub.challenge和hub.verify_token参数没有再次发送，如果订阅一定被确认过了

payments

{

  "object": "payments",

  "entry": [

    {

      "id": "296989303750203",

      "time": 1347996346,

      "changed_fields": [

        "actions"

      ]

    }

  ]}

id

Note - While Realtime Updates for other object types can be batched, payment updates arenever batched.

You are guaranteed to receive a new update every time a transaction is updated, either by user action, developer action, or by Facebook.

这里有一个典型的例子对发送对一个支付对象的订阅一个回调

{

  "object": "payments",

  "entry": [

    {

      "id": "296989303750203",

      "time": 1347996346,

      "changed_fields": [

        "actions"

      ]

    }

  ]}

 注意实时更新值通知你特定的支付很重要，使用id字段来标识改变，接收更新之后，你需要查询图形api来得到信息的事物，为了适当的处理改变。

注意：别的对象类型的实时更新可以鼻梁处理，支付的更新从来不是批量的，你必须保证接收到用户，开发者或者facebook的动作一个新的更新每次事物发生更新的时候，

If a Realtime Update to your server fails, Facebook will retry again immediately, and then a few times more, with decreasing frequency, over the subsequent 24 hours.

X-Hub-Signaturesha1=

如果一个到你服务器的实时更新失败，facebook将会立即重新尝试，稍后几次，24小时候会降低尝试
对每一个请求，facebook发送x中心签名的http的头包含sha1签名 请求的有效荷载 使用应用的密钥作为一个key，前缀使用sha1=,你的回调端点会验证这个签名来来检验 有效载荷的完整性和来源。

Responding to Updates

id

The following sections enumerate all of the potential state changes that trigger a Realtime Update to be sent. These are broadly divided into:

回应更新
服务器接收到实时更新之后，你必须使用id字段查询图形api，包括对事物的新状态的实时更新的详情，你必须对这些依赖的状态采取措施，如下区域列举了所有潜在的状态改变，触发一个实时更新被发送，他们被广泛的分解。
对actions数组的改变，发生在一个支付同步完成，一个退款发起（通过或者不通过facebook）或者一个拒付发生
对disputes数组的改变，发生在一个被一个顾客初始化订单纠纷

Actions

paymentactionsactionstypetypechargerefundchargebackchargeback_reversaldecline

A sample response from the Graph API for a payment object with associated actions is below:

{

   "id": "3603105474213890",

   "user": {

      "name": "Daniel Schultz",

      "id": "221159"

   },

   "application": {

      "name": "Friend Smash",

      "namespace": "friendsmashsample",

      "id": "241431489326925"

   },

   "actions": [

      {

         "type": "charge",

         "status": "completed",

         "currency": "USD",

         "amount": "0.99",

         "time_created": "2013-03-22T21:18:54+0000",

         "time_updated": "2013-03-22T21:18:55+0000"

      },

      {

         "type": "refund",

         "status": "completed",

         "currency": "USD",

         "amount": "0.99",

         "time_created": "2013-03-23T21:18:54+0000",

         "time_updated": "2013-03-23T21:18:55+0000"

      }

   ],

   "refundable_amount": {

      "currency": "USD",

      "amount": "0.00"

   },

   "items": [

      {

         "type": "IN_APP_PURCHASE",

         "product": "http://www.friendsmash.com/og/friend_smash_bomb.html",

         "quantity": 1

      }

   ],

   "country": "US",

   "created_time": "2013-03-22T21:18:54+0000",

   "payout_foreign_exchange_rate": 1,}

As you subscribed to the actions field when registering for Realtime Updates, Facebook will issue a Realtime Update when the array changes as follows:

动作
每一个支付条目包含一个名字叫actions数组,包含状态改变的事物发生过程集合，每一个actions的条目有一个属性名叫type,描述了action发生的的类型，类型有如下的值：
充值，退款，拒付，拒付逆转，拒付拒绝，下面是完整的解释。
一个简单的响应从图形支付api项目跟如下的actions关联

Charge

"status": "initiated"

Note: Facebook will not send Realtime Updates for payments in an initiated state.

"status": "initiated""status": "completed"

支付
最初，所有的订单包含一个拥有“status”:"initiated"的支付条目，一个初始化的支付指出了支付是唯一初始化的并没有完全完成，你将通常看到这个初始化状态对所谓的支付方法，需要很长时间头设置 如同上面描述的。
注意 facebook就不会发送初始化状态的支付实时更新。
当一个支付完成，status:initiated将会编程status:completed,facebook将会发起一个实时更新，基于你看到的改变你需要检查你的支付记录来确认如果有一条如同下面的新的或者已经存在的事物或者响应

initiated

"status": "failed"

For more information about the payment object and its potential states, please see the Payment API reference.

如果订单已经被你所知，或者已经通过js回调（当作第一选择更好）完成 ，你可以安全的忽略掉实时更新，并用它作为额外的确认
如果订单被你所知，但是存在初始化的状态，你需要处理来完成这个订单，发送关联的虚拟条目或者货币给客户，这个支付可以被安全的标记为完成
如果订单未知，这表名客户端的流程没有完成，最可能的是因为连接问题或者顾客关掉了浏览器在充值过程中，你仍然可以完成订单，因为facebook保持了最后的源和真相对用户的账单
你就会收到对充值含有status:failed实时更新 这些订单将不会完成
更多的关于支付项目和基本的状态，请看支付api参考

Refund

"type": "charge"

For more information about the dispute and refund process, please see Payments How-To: Handling Disputes and Refunds.

Chargeback, Chargeback Reversal and Declines

As with refunds, you will also be notified via a Realtime Update when a chargeback, chargeback reversal or decline has been issued. A chargeback, chargeback reversal or decline object will be added to the actions array of the Graph API return data for the payment.

For more information about the dispute and refund process, please see Payments How-To: Handling Disputes and Refunds.

退款
任何时候你通过图形api发起一个退款，你就会收到一个实时更新，含有type:charge,一个退款含有你必须意识到不同的状态，最现煮的，如果一个退款失败，一般是因为处理过程或者连接错误，你需要重试来发起退款。
更多关于纠纷和退款的过程请看支付如何处理纠纷和退款
拒付，拒付逆转和拒付拒绝
对退款来说，你也需要通知通过实时更新当一个拒付，拒付逆转或者拒付拒绝发生的时候，一个拒付，逆转，拒绝项目会增加到图形api返回的支付数据的actions的数组中
更多关于纠纷和退款的过程请看支付如何处理纠纷和退款

Disputes

"disputes"payment

A full sample response from the Graph API for a disputed transaction is below:

{

   "id": "3603105474213890",

   "user": {

      "name": "Daniel Schultz",

      "id": "221159"

   },

   "application": {

      "name": "Friend Smash",

      "namespace": "friendsmashsample",

      "id": "241431489326925"

   },

   "actions": [

      {

         "type": "charge",

         "status": "completed",

         "currency": "USD",

         "amount": "0.99",

         "time_created": "2013-03-22T21:18:54+0000",

         "time_updated": "2013-03-22T21:18:55+0000"

      }

   ],

   "refundable_amount": {

      "currency": "USD",

      "amount": "0.99"

   },

   "items": [

      {

         "type": "IN_APP_PURCHASE",

         "product": "http://www.friendsmash.com/og/friend_smash_bomb.html",

         "quantity": 1

      }

   ],

   "country": "US",

   "created_time": "2013-03-22T21:18:54+0000",

   "payout_foreign_exchange_rate": 1,

   "disputes": [

      {

         "user_comment": "I didn't receive my item! I want a refund, please!",

         "time_created": "2013-03-24T18:21:02+0000",

         "user_email": "email\u0040domain.com",

         "status": "resolved",

         "reason": "refunded_in_cash"

      }

   ]}

For more information on how to respond to disputes and issue refunds, please see Payments How-To: Handling Disputes and Refunds.

For more information about the payment object, please see the Payment API reference.

纠纷
facebook将会通知你通过发起一个实时更新，当纠纷产生的时候，这个情况下，你可以看到一个新的纠纷数组查uxianzuowei一个支付项目的一部分，这个数组含有时间和纠纷初始化的时间，用户的原因对初始化的响应，用户的邮件地址，你可以直接联系到他们为了解决纠纷。
一个完整一个纠纷事物图形api响应的例子 如下

更多关于纠纷和退款的过程请看支付如何处理纠纷和退款