Configure a transaction recording policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Configure transaction recording policies for each API product in your API product bundle, as described in the following sections.

Introduction

A transaction recording policy enables monetization to capture transaction parameters and custom attributes. Monetization needs this information to perform its monetization processing such as applying rate plans.

For example, if you set up a revenue share rate plan, a percentage of the revenue generated from each transaction involving your monetized API product is shared with the developer of the app issuing the request. The revenue share is based on the net or gross price of the transaction (you specify which one), that is, a percentage of the gross or net price of each transaction is used to determine the revenue share. Because of this, monetization needs to know the gross or net price of a transaction, as applicable. It gets the gross or net price from settings you make in the transaction recording policy.

If you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. Monetization needs to know what the custom attribute is and where to find it. So you need to specify the custom attribute in the transaction recording policy.

In addition to specifying transaction attributes in the transaction recording policy, you can specify transaction success criteria to determine when a transaction is successful (for charging purposes). For examples of setting transaction success criteria, see Examples of setting transaction success criteria in a transaction recording policy. You can also specify custom attributes for an API product (on which you base rate plan charges).

Configuring a transaction recording policy

Access the Product Bundles page, as described below.

Configuring transaction attributes

In the Transaction Attributes section, specify the criteria that indicate a successful monetization transaction.

1. In the Transaction Success Criteria field, specify the expression based on the value of the Status attribute (described next) for determining when the transaction is successful (for charging purposes). Transactions that are not successful (that is, they do not meet the criteria in the expression) are recorded, but rate plans are not applied to them. For example:

   txProviderStatus == 'OK'

2. The Status attribute contains the value used by the expression configured in the Transaction Success Criteria field. Configure the Status attribute by defining the following fields:

   Field	Description
   API Resource	URI patterns defined in the API product that will be used in identifying monetized transactions.
   Response Location	Location of the response where the attribute is specified. Valid values include: Flow Variable, Header, JSON Body, and XML Body.
   Value	Value of the response. To specify more than one value, click + Add x (for example, + Add Flow Variable).

3. To configure optional transaction attributes, enable the Use Optional Attributes toggle and configure any of the transaction attributes defined in the following table.

   Attribute	Description
   Gross price	This attribute is applicable only for rate plans that use the revenue share model. For those rate plans, either Gross Price or Net Price is mandatory. Ensure that the numeric value is expressed as a String type. Gross price for a transaction. For revenue share plans, you need to record either the Gross Price attribute or the Net Price attribute. Which attribute is required depends on the basis of the revenue share. For example, you can set up a revenue share rate plan that is based on the gross price of a transaction. In that case, the Gross Price field is required.
   Net price	This attribute is applicable only for rate plans that use the revenue share model. For those rate plans, either Gross Price or Net Price is mandatory. Ensure that the numeric value is expressed as a String type. Net price for a transaction. For revenue share plans, you need to record either the Net Price field or the Gross Price field. Which field is required depends on the basis of the revenue share. For example, you can set up a revenue share rate plan that is based on the net price of a transaction. In that case, the Net Price field is required.
   Currency	This attribute is required for rate plans that use the revenue share model. Type of currency that applies to the transaction.
   Error Code	Error code associated with the transaction. It provides further information about a failed transaction.
   Item Description	Description of the transaction.
   Tax	This attribute is relevant only for revenue sharing models and only if the tax amount is captured in the API calls. Ensure that the numeric value is expressed as a String type. Tax amount on the purchase. Net price plus tax = gross price.

For example, by setting the following values, monetization gets the value of the flow variable from the message response in a variable called response.reason.phrase. If the value is OK, and the Monetization Limits Check policy is attached to the API proxy ProxyEndpoint request, monetization counts it as a transaction.

Field	Value
Transaction Success Criteria	txProviderStatus == 'OK'
Status: API Resource	**
Status: Response Location	Flow Variable
Status: Flow Variable	response.reason.phrase

Configuring custom attributes

In the Custom Attributes section, you identify custom attributes to include in the transaction recording policy. For example, if you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. You then need to include that custom attribute in the transaction recording policy.

Each of these attributes is stored in the transaction log, which you can query. They are also displayed when you create a rate plan (so that you can choose one or more of these attributes on which to base your rate for the plan).

You can include custom attributes defined in the transaction recording policy in your revenue summary reports, as described in Including custom transaction attributes in revenue summary reports.

To configure custom attributes, enable the Use Custom Attributes toggle and define up to 10 custom attributes. For each custom attribute that you include in the transaction recording policy, you need to specify the following information.

Field	Description
Custom Attribute Name	Enter a name that describes the custom attribute. If the rate plan is based on a custom attribute, this name is displayed to the user in the rate plan details. For example, if the custom attribute captures duration, then you should name the attribute duration. The actual units for the custom attribute (such as hours, minutes, or seconds) are set in the rating unit field when you create a custom attribute rate plan (see Specify rate plan with custom attribute details).
API Resource	Select one or more URI suffixes (that is, the URI fragment following the base path) of an API resource accessed in the transaction. The available resources are the same as for transaction attributes.
Response Location	Select the location in the response where the attribute is specified. Valid values include: Flow Variable, Header, JSON Body, and XML Body.
Value	Specify a value for the custom attribute. Each value that you specify corresponds to a field, parameter, or content element that provides the custom attribute in the location that you specified. To specify more than one value, click + Add x (for example, + Add Flow Variable). For example, if you configure a custom attribute named Content Length and select Header as the response location, if the Content Length value is provided in the HTTP Content-Length field, then you would specify Content-Length as the value.

Link resources with unique transaction ID

Some transactions are simple, involving an API call to one resource. However, other transactions can be more complex. For example, suppose a transaction for purchasing an in-app product in a mobile gaming app involves multiple resource calls:

• A call to a reserve API that ensures that a prepaid user has enough credit to purchase the product and allocates ("reserves") the funds for the purchase.
• A call to a charge API that deducts the funds from the prepaid user's account.

To process the entire transaction, monetization needs a way of linking the first resource (the call and response to and from the reserve API) with the second resource (the call and response to and from the charge API). To do this, it relies on information that you specify in the Link Resources with Unique Transaction ID section.

To configure custom attributes, enable the Use Unique Transaction IDs toggle and link the transactions. For each transaction, you specify a resource, response location, and attribute value that is linked with the corresponding values in the other transactions.

For example, suppose the reserve API call and the charge API call are linked as follows: a field named session_id in the response header from the reserve API corresponds to a response header named reference_id from the charge API. In this case, you might set the entries in the Link Resources with Unique Transaction ID section as follows:

Resource	Response location	Value
reserve/{id}**	Header	session_id
/charge/{id}**	Header	reference_id

Configuring refunds

In the Refunds section, you specify attributes that monetization uses to process refunds.

For example, suppose a user purchases a product from a mobile app that uses your monetized APIs. The transaction is monetized based on the shared revenue plan. However, suppose the user is unsatisfied with the product and wants to return it. If the product is refunded using a call to your API that does the refund, monetization makes the necessary monetization adjustments. It does this based on information that you specify in the Refunds section of the transaction recording policy.

To configure refunds, enable the Use Refund Attributes toggle and define the refund details:

1. Define the refund criteria by defining the following fields:

   Field	Description
   Response Location	Resource for the refund transaction. If the API product provides multiple resources, you can select only the resource that performs the refund.
   Refund Success Criteria	Expression based on the value of the Status attribute (described next) for determining when the refund transaction is successful (for charging purposes). Refund transactions that are not successful (that is, they do not meet the criteria in the expression) are recorded, but rate plans are not applied to them. For example: txProviderStatus == 'OK'

2. Configure the Status attribute by defining the following fields:

   Field	Description
   Response Location	Location of the response where the attribute is specified. Valid values include: Flow Variable, Header, JSON Body, and XML Body.
   Value	Value of the response. To specify more than one value, click + Add x (for example, + Add Flow Variable).

3. Configure the Parent ID attribute by defining the following fields:

   Field	Description
   Response Location	Location of the response where the attribute is specified. Valid values include: Flow Variable, Header, JSON Body, and XML Body.
   Value	ID of the transaction for which a refund is processed. For example, if a user purchases a product and then requests a refund, the Parent Transaction ID is the ID of the purchase transaction. To specify more than one value, click + Add x (for example, + Add Flow Variable).

4. To configure optional refund attributes, enable the Use Optional Refund Attributes toggle and configure the attributes. The optional refund attributes are the same as the optional transaction attributes, as defined in Configuring transaction attributes.

Managing transaction recording policies using the API

The following sections describe how to manage transaction recording policies using the API.

Creating a transaction recording policy using the API

You specify a transaction recording policy as an attribute of an API product. The value of the attribute identifies:

• The URI suffix of the product resource to which the transaction recording policy is attached. The suffix includes a pattern variable that is enclosed in curly braces. The pattern variable is evaluated by API Services at runtime. For example, the following URI suffix includes the pattern variable {id}.

  /reserve/{id}**
  

  In this case, API Services evaluates the URI suffix of the resource as /reserve followed by any sub-directory that begins with an ID defined by the API provider.

• The resource in the response to which it is attached. An API product can have multiple resources and each resource can have a transaction recording policy attached to a response from that resource.
• An extract variable policy that enables the transaction recording policy to extract content from a response message for the transaction parameters you want to capture.

You add the transaction recording policy attribute to an API product by issuing a PUT request to the management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (and not to a monetization API).

Specifying transaction success criteria using the API

You can specify transaction success criteria for determining when a transaction is successful (for charging purposes). Transactions that are not successful (that is, they do meet the criteria in the expression) are recorded, but rate plans are not applied to them. For examples of setting transaction success criteria, see Examples of setting transaction success criteria in a transaction recording policy.

You specify the transaction success criteria as an attribute of an API product. Do this by issuing a PUT request to the management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (and not to the monetization API).

For example, in the following request a transaction is successful if the value of txProviderStatus is success (the transaction success criteria-related specifications are highlighted).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Specifying custom attributes using the API

You can specify custom attributes for an API product on which you base rate plan charges. For example, if you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. When you create a rate plan, you can specify one or more custom attributes on which to base your rate for the plan. However, any specific product in a rate plan, can only have one custom attribute on which to base the rate for the plan.

You specify custom attributes as attributes of an API product. Do this by issuing a PUT request to the management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (and not to the monetization API).

For each custom attribute that you add to an API product, you need to specify a name and an attribute value. The name must be in the form MINT_CUSTOM_ATTRIBUTE_{num}, where {num} is an integer.

For example, the following request specifies three custom attributes.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Examples of setting transaction success criteria in a transaction recording policy

The following table provides examples of successful and unsuccessful transactions, based on the transaction success criteria expression and the txProviderStatus value returned by the API proxy. txProviderStatus is the internal variable that monetization uses to determine transaction success.

Success criteria expression	Valid expression?	txProviderStatus value from API proxy	Evaluation result
null	true	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	true	"200"	false
"txProviderStatus =='200'"	true	"200"	true
"true"	true	"200"	true
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Not Found"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"bad request"	true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus == 100"	true	"200"	false