VL Group

Rhymba v3.6 Documentation

Reporting a Purchase

Reporting a purchase to Rhymba's Purchase API works much like validating a purchase, except you'll call a different method and pass some additional information. All of the same processes and procedures apply, as well as the same potential error messages for invalid content.

The key differences, however, are that we require some additional info about the end user passed as a part of the URL to which you'll POST your data. This additional information is used in our reporting to the content providers.

Using ReportPurchase

The ReportPurchase method in the Purchases API is what you hit to actually... report a purchase. Shocking, we know. Here's what you need to do:

  1. You generate your hashed request access token for the method ReportPurchase.
  2. Generate a POST to the URL https://purchases.mcnemanager.com/Purchases.svc/ReportPurchase?externalUserId=abcdef&zip=11101&currencyCode=USD&countryCode=US&affiliateName=YourAffiliateName&affiliateTransactionId=YourUniqueInternalTransactionId&isTest=false&saleDateUtc=MM-dd-yyyy HH:mm&confirm=true and POST the items that you're reporting a purchase of in a field called purchasedItems, as described on the Verifying Items page. Let's walk you through the components of that URL and what you need.
    • First up, https://purchases.mcnemanager.com/Purchases.svc/ReportPurchase? is your base method URL.
    • You need to specify the access_hint, access_req, and access_token values you received when generating your hashed request access token in the HTTP headers.
    • Next, you need to specify the end user's unique user ID within your system with the externalUserId query string parameter. This is saved on our end, and makes any customer service & troubleshooting more straightforward, since you'll be able to provide your internal user ID for any customer.
    • We need to know the end user's ZIP/postal code. You pass that using the &zip= query string parameter.
    • Next up are the &currencyCode and &countryCode parameters. You can find a complete list of valid country codes on the Country & Currency Codes page.
    • The next two query string parameters are &affiliateName=YourAffiliateName and affiliateTransactionId=YourUniqueInternalTransactionId. We will provide you with your affiliate name as a part of your system turn-up process. The content providers request that we include the affiliate name in our reporting process to them. Your affiliate transaction ID should be a unique, internal transaction ID you use within your system to identify purchases; this allows us to map back to your internal ID for customer service purposes.
    • The &isTest query string parameters is a boolean that allows you to specify whether this is a test transaction or not. Test transactions are primarily used during development; as a part of "going to production", you should change this to false.
    • Next, you specify the transaction date in the query string parameter &saleDateUtc. This should be in UTC, in the format two-digit month-two-digit day-four-digit year 24-hour, two-digit hour-two-digit minute. Example: 05-06-2013 18:36 would equal May 6th, 2013, 6:36pm.
    • Finally, we have the &confirm query string parameter. This boolean, if set to true, allows you to treat the purchase process like a database transaction. If you don't specify this query string parameter, it defaults to false.
      • If set to true, a successful call to ReportPurchase will return a token which you must in turn pass to the FinalizePurchase method to actually "complete" the purchase and save it in our system.
      • If this is false, and your ReportPurchase call is successful, you'll receive back our unique purchase ID for this transaction right away.
      Both have their purposes and uses. If, for example, you're going to do some things on your end that may fail (and thus, you wouldn't want the ReportPurchase call to complete), you should set &confirm=true and later call FinalizePurchase.
  3. If any of the items you are attempting to report are invalid, a response will be returned similar to that describe on the Verifying Items page.

Using FinalizePurchase

If, in the ReportPurchase call above, you've chosen to set &confirm=true, you'll need to call FinalizePurchase to actually complete the purchase reporting process. If you don't call FinalizePurchase, the purchase will never exist in our system, and the token returned from ReportPurchase will eventually be purged.

Calling FinalizePurchase is super easy: Just hit the URL https://purchases.mcnemanager.com/Purchases.svc/FinalizePurchase?token=YourReportPurchaseToken, where YourReportPurchaseToken is the purchase token returned from ReportPurchase as described above.

If this call to FinalizePurchase succeeds, the purchase is stored in our system and you'll receive back our unique purchase ID for this transaction. If this should fail for any reason — and, it shouldn't, but things happen — you'll get back the message "Purchase failed with no message. See server logs for details." Contact us to investigate, should that happen.