¶ Firehose
A firehose in RevCent gives you the ability to send all, or filtered, API call responses to a recipient, such as a webhook endpoint. This allows you to process responses and take action based on API call response types and methods. Previously, only Third Party Integrations were capable of sending API responses to an external endpoint, with a limited number of API call types and methods supported. With our firehose feature, you can send all, or specific, responses to an endpoint and only take action on responses you wish to. Note: API call responses for “retrieve” and “query” will not be sent.
¶ Why Use A Firehose?
- Send all, or filtered, API call responses to a third party.
- Greater control and capabilities for custom event processing.
- Additional features and settings when compared to our existing Third Party Integration feature.
- Create as many firehoses as you want.
- Take a look at Functions, which allow maximum control using your own code.
¶ API Call Responses
Important: All, or filtered, API call responses for your account will be sent to the recipient of the firehose you create. API call responses for “retrieve” and “query” will not be sent. To view an example of API call responses, please view our API documentation. Specifically, view the example JSON response for the request type and request method you expect to take action on.
When the recipient receives an API call response via the firehose, the “request_type” and “request_method” properties will be present, indicating the origination of the API call. The “code” property will also be present, indicating the result of the API call. The recipient can therefore determine the request that was made and whether the request was successful or not.
¶ Determine API Call
Below are example scenarios for using the firehose and parsing the API call response at the recipient. Remember, all API call responses will be sent to the recipient, not just the scenarios below. Therefore it is important to view our API documentation for JSON example responses on API calls you wish to take action on.
¶ Example 1 - Sale Create
If the firehose recipient receives an API call response with “request_type”: “sale” and “request_method”: “create”, this indicates that the API call originated from a Sale Create request. The recipient will view the “code” property to determine if the sale was successful, or not. If code is not 1, then the sale was not successful. There is an important caveat regarding sale create responses and that is the pending sale property. Read more about Pending Sales below, and identifying if a sale is pending. If you want to know in advance what a sale create request response will be, view the API Documentation section for Sale > Create.
Example API Response
{
"request_type": "sale", // Request type indicates the originating type of API call
"request_method": "create", // Request method indicates the originating method of API call
"code": 1 // Code determines result of API call.
... // Additional data will be in the response. Refer to API docs for example responses
}
¶ Example 2 - Subscription Renew
If the firehose recipient receives an API call response with “request_type”: “subscription” and “request_method”: “renew”, this indicates that the API call originated from a Subscription Renew request. The recipient will view the “code” property to determine if the renewal was successful, or not. If code is not 1, then the renewal was not successful. If you want to know in advance what a subscription renew request response will be, view the API Documentation section for Subscription > Renew
Example API Response
{
"request_type": "subscription", // Request type indicates the originating type of API call
"request_method": "renew", // Request method indicates the originating method of API call
"code": 1 // Code determines result of API call.
... // Additional data will be in the response. Refer to API docs for example responses
}
¶ Response Codes
Important: Every API call response sent to a recipient will have a “code” property. This property indicates the result of the API call. This is important in order to distinguish whether a call was successful or not. I.e. whether a sale was successful or declined, or a renewal was captured, etc.
0 = API Error
1 = Success
2 = Merchant Declined
3 = Merchant Error
4 = Merchant Hold
5 = Fraud Detected
¶ Amounts
Depending on the API call request type and method, you may want to know the amount of the actual event. It is important to review the amount values present in API call responses. For example, if you wish to know how much a sale was for, you would want to know how much the customer actually paid versus potential amounts to be paid in the future.
- amount: The amount of the item.
- amount_captured: The amount captured.
- amount_discounted: The total amount discounted.
- amount_fees: The current amount of calculated fees charged by the payment processor.
- amount_gross: The current gross amount. Equals (amount_captured + amount_settled).
- amount_net: The current net amount. Equals (amount_captured + amount_settled) - amount_fees.
- amount_original_total: The total calculated amount when an item is created.
- amount_remaining: The current amount remaining to be captured. Amounts yet to be captured due to a trial or salvage transaction.
- amount_to_salvage: The current amount of related salvage transactions not yet salvaged.
Amounts In Sale Create Response
{
"amount": 37.39, // The amount related to the event.
"amount_captured": 37.39, // The payment transaction amount captured. (amount charged to customer)
"amount_discounted": 7.05, // The amount discounted from the item before payment.
"amount_fees": 0.82, // The amount of payment transaction fees. (amount of fees depending on processor)
"amount_gross": 37.39, // The amount captured + amount settled. (amount you processed, before fees)
"amount_net": 36.57, // The amount captured + amount settled - amount fees. (amount you processed, after fees)
"amount_original_total": 174.43, // The total calculated amount. (amount of sale including discounts)
"amount_remaining": 129.99, // The current amount remaining to be captured. (amount you have yet to process)
"amount_to_salvage": 0 // Any amounts to be salvaged. (amount you hope to recover in the future)
...
}
¶ Pending Sales
Important: RevCent API calls can involve pending sales. These will appear as successful sales, however it is merely a sale RevCent has created but not yet attempted to process payment. Pending sales are created due to PayPal sales awaiting confirmation or upsell flows awaiting completion. Only the “amount” property will be present, indicating the current total of the pending sale before any payment attempts. Pending sales have the ability to be updated, potentially changing the amount, therefore the amount property is only representative at the time of the call.
Note: If you only want to know when a customer actually paid for something, ignore pending sales. I.e., where the “is_pending” property is present and equals true.
Identify a pending sale: If the “is_pending” property is present in the API response sent to the recipient, and “is_pending” equals true, then the sale was created but in a pending state. Do not consider a pending sale as having been paid, even though an amount property is present. A pending sale is used to save a sale and process later, i.e. upsell flows.
{
"amount": 172.08, // Amount of the pending sale when created.
"code": 1, // Indicates the pending sale was successfully created.
"is_pending": true, // Indicates the sale is in a pending state and no payments were attempted.
"request_method": "create",
"request_type": "sale",
"result": "Pending sale created.",
"sale_id": "o1ZyBJqNYgTMKOpjN7KQ" // The pending sale ID.
}
¶ View Firehoses
View your firehoses by clicking Tools > Firehose in the sidebar, or go to https://revcent.com/user/firehoses
¶ Create A Firehose
Create a new firehose by clicking the Create New Firehose button when viewing all firehoses or go to https://revcent.com/user/new-firehose
¶ Name
Enter a name for the firehose. Required.
¶ Description
Enter a description for the firehose.
Once the firehose is created you will be forwarded to the Edit Firehose Page for the new firehose. You can then select and enter the required values for the recipient you are linking. Continue to the Edit A Firehose section below.
¶ Edit A Firehose
Edit an existing Firehose by clicking the edit icon when viewing all Firehoses.
¶ Details
¶ Name
Enter a name for the firehose. Required.
¶ Description
Enter a description for the firehose.
¶ Status
Set the status for the firehose.
¶ Mode
Will the recipient receive responses from live or test API calls?
¶ Recipient
Select the recipient that you wish to send API call responses.
¶ Filters
¶ Campaign Filter
Select one or more campaign(s) to filter API call responses only from originating campaign(s). If a campaign(s) is selected, only the API calls that originated from the campaign(s) selected will be sent to the firehose recipient. If none selected, all API call responses will be sent to the recipient regardless of originating campaign. Optional.
¶ Type/Method Filter
Do you wish to filter based on API call type/method? If Enabled, the Type/Method options table will appear, allowing to you send only specific API call types to the recipient.
¶ Type/Method Options
Enable the API Call types/methods to send only API call responses that originate from those types/methods that are enabled. Optional
¶ Custom Webhook
RevCent will submit a HTTP POST request to a webhook endpoint you specify. The POST body will contain the API response JSON depending on the request type and method of the API call performed. View our API documentation for examples of all possible API responses.
¶ Webhook Settings
¶ Endpoint URL
Enter the endpoint URL for the webhook. Do not include https:// or any URL parameters.
¶ URL Parameters
Enter any URL Parameters, a.k.a. Query Strings, to amend to the endpoint URL, separated by comma. If parameters are malformed they will be rejected.
Example Input
id=123,string=something
¶ Request Headers
Any additional headers you want RevCent to send with the webhook POST request. Must be a valid JSON object or headers will be rejected. The JSON object must contain the name value pairs for the headers you wish to include.
Example JSON
{
"Custom-Header": "Custom Value",
"Another-Header": "Another Value"
}