Import usage from CSV
Overview
Upload usage data through the 2Checkout API from a CSV (comma-separated values) file for active and trial subscriptions. Usage data uploaded via JSON-RPC APIv6 will be used to charge subscribers for the metered resources they consume. Metered billing allows for usage fees in arrears to be added to recurring subscription costs.
2Checkout will capture the parameters sent via JSON-RPC APIv6 and import the usage data into the system. Once the upload process is complete, you'll be able to access the uploaded file in the Usage area of the Merchant Control Panel.
Set the DATE parameter to GMT+2 time zone, when making the API call to the Usage Upload endpoint.
Method and URL
POST: https://api.2checkout.com/subscription/payperusage/receiver/index.php
Parameters
|
Parameters |
Type |
Required/Optional |
Description |
Used in HASH validation* |
|---|---|---|---|---|
|
merchant |
String |
Required |
Your unique 2Checkout merchant code. View merchant code. |
YES |
|
secret_key |
String |
Required |
The secret key associated to your account. View secret key. |
YES |
|
file_MD5 |
String |
Required |
The md5 hash of the CSV file used to upload usage. |
YES |
|
hash |
String |
Required |
The MD5 hmac key for the request. |
N/A |
| UsageStart | Datetime | Required | The datetime when the usage started; can be the same as UsageEnd. For existing records, this will be updated to time 00:00:00. | N/A |
| UsageEnd | Datetime | Required | The datetime when the usage ended and was recorded. For existing records this will be updated to time 23:59:59, this will be enforced in the CSV upload as well. | N/A |
| OptionCode | String | Required | Unique codes you provided as identifiers of specific Pricing Options in the Usage Scale Pricing Options Group scheme. Example: metered pricing. | N/A |
| Description | String | Optional | It can be used to store a short merchant comment of the usage being uploaded. This can be anything, from the source of usage (mobile, web, etc.), to why changes occurred, etc. Example: Subscription usage for September. | N/A |
| SubscriptionRef | String | Required | Unique code that represents a subscription. Example: 83FE4FEF2. | N/A |
Request Example
<?php
//hmac
$date = date("Y-m-d");
$fileReceived_md5 = md5_file("[Path to the CSV file used for usage upload]");
$merchantCode = "";
/* 2Checkout Code */
$merchantKey = "";
/* Merchant Secret Key */
$hashParams = "MERCHANT={$merchantCode}&FILE={$fileReceived_md5}&DATE={$date}";
$hmac = hash_hmac('md5', $hashParams, $merchantKey);
?>
<html>
<body>
<form method="post" action="https://api.2checkout.com/subscription/payperusage/receiver/index.php" enctype="multipart/form-data">
<input type="text" name="MERCHANT" value="<?php
echo $merchantCode;
?>" /><br />
<input type="text" name="HASH" value="<?php
echo $hmac;
?>" /><br />
<input type="file" name="OPTIONS" /><br />
<input type="hidden" name="FILE_MD5" value="<?php
echo $fileReceived_md5;
?>" />
<input type="hidden" name="DATE" value="<?php
echo $date;
?>" />
<input type="submit" /><br />
</form>
</body>
</html>
Error handling
|
Message code |
Message description |
Resolution |
|---|---|---|
|
1 |
The upload operation completed successfully. |
N/A |
|
Invalid account! |
The merchant code provided does not belong to a vendor in the 2Checkout system. |
Please check your merchant code and make sure you're using the correct version. View merchant code. |
|
Bad signature on the received file! |
The upload CSV file's md5 signature is different than the one sent as a parameter. |
Please make sure that you're using the correct md5 signature for the CSV file, or that you're uploading the CSV file for which the signature was generated. |
|
Invalid signature |
The HMAC calculated by the 2Checkout system is different from the one you're sending. |
Please make sure that all parameters use correct values. |
