Post refunds

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

Introduction

Monetization allows you to post refunds to developers for "purchase transactions". Suppose you are a mobile operator and you offer developers a payment API to charge mobile subscribers for the purchase of an application or content within the application. Each time a subscriber uses the API to make a purchase, it's a purchase transaction.

Purchase transactions can result in refunds. For example, the content might not be delivered, or the third party is otherwise unsatisfied with the purchase. In those cases, the developer issues a refund to the third party. Monetization enables you to make an analogous refund. This is especially pertinent to revenue share plans.

Imagine that the developer who issued the refund to the mobile subscriber purchased a revenue share plan for your API product. Suppose the plan calls for the developer to receive 70% of the net/gross price of the purchase transaction. By posting a refund, you, in effect, reverse the purchase transaction, that is, you deduct 70% from the payment due to the developer for the month when the refund was applied (the month may be different than the month in which the actual purchase transaction occurred).

Posting a refund using the Classic Edge UI (Edge for Private Cloud only)

You can post a refund for any "successful" purchase transaction, that is, where the API successfully charged the third party and for which you haven’t already issued a full refund. Posting a refund results in the creation of a refund transaction with a parent transaction ID, where the transaction ID is the ID of the purchase transaction.

You can post a refund for the full amount of the original purchase transaction or for a partial amount. You can also post multiple partial refunds, but the total amount of the refunds cannot be more than the original purchase amount.

To post a refund:

1. On the Monetization tab, select Refunds.

   

   This opens the Refunds page.

   

2. In the Billing Month, drop-down menu, select the month in which the purchase transaction took place. Then click + Refunds.

   This displays a list of all the successful purchase transactions for the selected month.

   

   You can filter the refund list by developer name or by searching on the actual transaction.

   To filter by developer, select the developer from the Developer drop-down menu. This displays a list of only the transactions relating to the selected developer.

   

   To filter by transaction ID, enter the transaction ID of the original purchase that you want to refund. This returns the transaction for that ID.

   

3. Check the Select box in the row(s) for the transaction(s) you want to refund.
4. Select either Total or Partial in the Type drop-down menu.

   If you select Total, the total amount of the purchase will be refunded. If you select Partial, a partial amount of the purchase will be refunded.

   If you select Partial, enter the amount of the partial refund in the Amount field. You can only refund up to the total amount of the purchase. If you have already posted a partial refund, you can only enter an amount up to the amount remaining on the purchase. Also, if the original purchase transaction has both gross and net prices, you will also need to state whether the partial amount you want to refund is gross or net.

   

5. Click Save to process the refund (or Cancel to cancel).

   The refund is posted to the month of the original purchase if the billing month is still open, otherwise the refund is posted to the current date.

   For a partial refund, the refund is processed for the partial amount and any revenue share is deducted based on the proportion of the partial amount over the full amount. In the partial refund example above, the partial amount is 0.50/1.12 = 45% of the gross price, so 45% of the developer’s revenue share will be deducted.

Checking in the UI if a refund has been processed

You can determine if a refund has been processed by selecting the billing month at the top of the Refunds page. This is the month of the purchase if the billing month is still open, or the current month if the billing month is closed. This displays a list of all refunds that have been posted in the month.

Posting a refund using the API

To post a refund, issue a POST request to /organizations/{org_name}/monetization-packages/{package_id}/refund-transactions, where {package_id} is the identification of the API package to which the refund applies.

When you issue the request, you need to specify as query parameters:

• The identification of the purchase transaction that is being refunded.
• The revenue type (GROSS or NET) of the purchase transaction.
• The refund amount.
• A note describing the reason for the refund.

Optionally, you can identify as a URL parameter an API package to which the refund applies.

See Refund configuration settings for a complete list of the URL parameters that you can specify in a refund request.

For example, the following request issues a refund for a purchase transaction. The refund amount is 50% of the gross amount of the purchase transaction.

$ curl -H "Content-Type:application/json" -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/payment/refund-transactions?revenueType=GROSS&refundAmount=0.5&parentTxId=abf50909-2492-4bf5-8704-ade05f4d43b3&transactionNote=Refund for purchase transaction" \
-u email:password

The response should look something like this (only part of the response is shown):

{
  "application" : {
    ...
    },
    "product" : [ {
      ...
      
     {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "Status=='200 OK'"
    } ],
    ...
  },
  "currency" : "USD",
  "developer" : {
    ...
    "legalName" : "DEV ONE",
    "name" : "Dev One",
    "organization" : {
      ...
    },
    ...
  },
  "endTime" : "2013-09-01 21:59:59",
  "environment" : "PROD",
  "euroExchangeRate" : 0.8123,
  "gbpExchangeRate" : 0.6910,
  "grossPrice" : 0.5,
  "id" : "61f7eb88-f8cc-4cda-afd8-4a61fba3dd33",
  "isRevOnGrossOrNet" : "NET",
  "isVirtualCurrency" : false,
  "notes" : "Refund for purchase transaction",
  "itemDesc" : "test application",
  "netPrice" : 0.4464,
  "orgRevenueShareAmount" : 0.1339,
  "parentId" : "abf50909-2492-4bf5-8704-ade05f4d43b3",
  "pkgId" : "myorg@@@payment",
  "pkgRatePlanProductName" : "Payment",
  ...
  },
  "ratePlanLevel" : "STANDARD",
  "revenueShareAmount" : 0.3125,
  "startTime" : "2013-09-01 21:59:59",
  "status" : "SUCCESS",
  "tax" : 0.0536,
  "taxModel" : "UNDISCLOSED",
  "txProviderStatus" : "SUCCESS",
  "type" : "REFUND",
  "usdExchangeRate" : 1.0724,
  "utcEndTime" : "2013-09-01 21:59:59",
  "utcStartTime" : "2013-09-01 21:59:59"
}

Refund configuration settings for the API

The following query parameters can be specified in a refund request:

Next steps

Learn how to schedule monetization-related jobs and about the jobs that are scheduled automatically in Schedule monetization jobs.