==payment_subscriptions.search ==
==== Description ====
Search for user's subscription
NOTE:
Search can be performed against any of the DVIP CS urls
```
staging: https://cs-m1.dvipdev.com/
production: https://cs-m1.dvipapp.com/
query: /api.json?cmd=payment_subscriptions.search&//input1//=some_value&//input2//=some_other_vaule
```
==== Input Parameters ====
<table>
<tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr>
<tr><td>email</td><td>string</td><td>No (at least 2//*//)</td><td>User's email address</td></tr>
<tr><td>username</td><td>string</td><td>No (at least 2//*//)</td><td>Username used to register with DatingVIP website</td></tr>
<tr><td>ccname</td><td>string</td><td>No (at least 2//*//)</td><td>First name + Last name on credit card</td></tr>
<tr><td>ccnum</td><td>string</td><td>No (at least 2//*//)</td><td>Last four digits of credit card number</td></tr>
</table>
//*Required are at least 2 parameters of above mentioned ones, except username+ccname//
NOTE: username+ccnum is allowed, but limited
NOTE: username+ccname is not allowed
__About search against username+ccnum__
To perform search we must first find user by his username. Since we have 100+ systems with 100+ databases, full scale solution would require brute force over every single system(database), which is, obviously, too much. We discussed possible ways to make this happen somehow .. and since there are only partner websites(with merchant overrides) on m1 and a41(for now), we can make username+ccnum work on small number of systems - m1, a41 by default. As number of partner websites spreads over systems, at some point results will be incomplete. So, bottom line is, __email is preferable__, since there is no easy way to implement this kind of search that would completely support growth of partner websites across systems, but there are special cases - lower number of systems used - that are covered.
So, to allow at least some useful username+ccnum search in some cases, we have one more optional parameter, it is only relevant for username+ccnum.
==== Optional Input Parameters ====
<table>
<tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th><th>Default value</th></tr>
<tr><td>systems</td><td>string</td><td>No(optional)</td><td>Comma separated list of systems on which to perform search against username</td><td>m1,a41</td></tr>
</table>
This parameter allows to define systems that will be used to search for user by username - if not passed defaults to m1,a41 - mainstream, porn2 - where partner websites(with merchant overrides) exist at the moment. Of course, if number of used systems grows over some max value, search will fail. When number of used systems grows, we can just add more systems to default, or execute api call with appropriate systems passed, but up to some reasonable number of systems.
==== Return ====
Returns array of subscription data grouped by it's status on DVIP, where status is:
<table>
<tr><th>Status</th><th>Description</th></tr>
<tr><td>-1</td><td>Subscription is canceled - User is premium, at current cycle end won't be rebilled and will drop to free</td></tr>
<tr><td>0</td><td>Subscription is stopped - Subscriptions that expired</td></tr>
<tr><td>1</td><td>Subscription is active - User is premium, at current cycle end will be rebilled</td></tr>
</table>
<table>
<tr><th>Subscription fields</th></tr>
<tr><th>Name</th><th>Type</th><th>Description</th><th>Note</th><th>Important</th></tr>
<tr><td>sub_id</td><td>int</td><td>Subscription ID</td><td></td><td>payment_subscription.edit</td></tr>
<tr><td>rebill_count</td><td>int</td><td>How many times subscription was rebilled</td><td></td><td></td></tr>
<tr><td>status</td><td>string</td><td>DVIP Payment status</td><td>Don't mix this with subscription status on DVIP(-1,0,1)</td><td></td></tr>
<tr><td>next_rebill_amount</td><td>float</td><td>Amount to be used for next rebill only</td><td></td><td></td></tr>
<tr><td>item_id</td><td>int</td><td>Item ID</td><td></td><td>payment_subscription.cancel</td></tr>
<tr><td>order_id</td><td>int</td><td>Order ID</td><td></td><td></td></tr>
<tr><td>amount</td><td>float</td><td>Amount to be used for all rebills (except for next)</td><td></td><td></td></tr>
<tr><td>trial_amount</td><td>float</td><td>Original trial amount</td><td></td><td></td></tr>
<tr><td>trial_unit</td><td>string</td><td>Units of trial duration(month, day, etc.)</td><td></td><td></td></tr>
<tr><td>trial_period</td><td>int</td><td>Number of units of trial duration</td><td></td><td></td></tr>
<tr><td>rebill_unit</td><td>string</td><td>Units of rebill cycle(month, day, .etc)</td><td></td><td></td></tr>
<tr><td>rebill_period</td><td>int</td><td>Number of units for rebill cycle duration</td><td></td><td></td></tr>
<tr><td>max_rebill_count</td><td>int</td><td>How many times subscription will rebill</td><td></td><td></td></tr>
<tr><td>description</td><td>string</td><td>What user paid and how much</td><td></td><td></td></tr>
<tr><td>user_id</td><td>int</td><td>DVIP User ID</td><td></td><td></td></tr>
<tr><td>transactions</td><td>array</td><td>Array of transactions data</td><td>Described in table bellow</td><td></td></tr>
<tr><td>username</td><td>string</td><td>Username</td><td></td><td></td></tr>
<tr><td>site_domain</td><td>string</td><td>Domain of the DVIP website where user is registered</td><td></td><td></td></tr>
<tr><td>site_name</td><td>string</td><td>Name of the DVIP website where user is registered</td><td></td><td></td></tr>
<tr><td>system_id</td><td>string</td><td>DVIP System ID</td><td></td><td>payment_subscriptions.cancel payment_subscriptions.edit</td></tr>
<tr><td>descriptor</td><td>string</td><td>What credit card statement was billed as</td><td></td><td></td></tr>
<tr><td>site_id</td><td>int</td><td>DVIP Website ID</td><td></td><td></td></tr>
<tr><td>date_start</td><td>int</td><td>Timestamp of date subscription started</td><td></td><td></td></tr>
<tr><td>date_stop</td><td>int</td><td>Timestamp of date subscription was stopped</td><td>Irrelevant for not stopped(0) subscriptions</td><td></td></tr>
<tr><td>date_cancel</td><td>int</td><td>Timestamp of date subscription was canceled</td><td>Irrelevant for active(1) subscriptions</td><td></td></tr>
<tr><td>date_rebill</td><td>int</td><td>Timestamp of date subscription will rebill, if status is active(1), Timestamp of date subscription will expire, if status is canceled(-1)</td><td>Irrelevant for stopped(0) subscriptions</td><td></td></tr>
</table>
<table>
<tr><th>Transaction fields</th></tr>
<tr><th>Name</th><th>Type</th><th>Description</th></tr>
<tr><td>tran_id</td><td>int</td><td>Transaction ID</td></tr>
<tr><td>transaction_type</td><td>int</td><td>Transaction Type ('S' for sale, 'A' for auth, 'R' for refund)</td></tr>
<tr><td>amount</td><td>float</td><td>Transaction Amount</td></tr>
<tr><td>currency</td><td>string</td><td>Transaction currency</td></tr>
<tr><td>description</td><td>string</td><td> Transaction Description</td></tr>
<tr><td>status</td><td>string</td><td>Status (successful|failed|init)</td></tr>
<tr><td>refunded_tran_id</td><td>int</td><td>Refunded transaction ID (if transaction is refund)</td></tr>
<tr><td>refunded</td><td>int</td><td>Is transaction refunded</td></tr>
<tr><td>refunded_amount</td><td>float</td><td>Refunded Amount</td></tr>
<tr><td>ccnum</td><td>string</td><td>Credit Card Number</td></tr>
<tr><td>ccname</td><td>string</td><td>Credit Card Name</td></tr>
<tr><td>ccxpdate</td><td>string</td><td>Credit Card Expired Date</td></tr>
<tr><td>cctype</td><td>string</td><td>Credit Card Type (I.e. visa)</td></tr>
<tr><td>cccountry</td><td>string</td><td>Credit Card Country</td></tr>
<tr><td>processor</td><td>string</td><td>Payment Processor short name (NB, RG ...)</td></tr>
<tr><td>processor_name</td><td>string</td><td>Payment Processor full name (NetBilling, Rocket Gate, ...)</td></tr>
<tr><td>date</td><td>string</td><td>Transaction Date (unix timestamp)</td></tr>
</table>
==== Usage Example ====
example url:
```
/api.json?cmd=payment_subscriptions.search&email=knotiaw71@yahoo.com&ccnum=0474
/api.json?cmd=payment_subscriptions.search&email=knotiaw71@yahoo.com&ccname=Knotia Wilson
```
example of subscription found:
```lang=json
{
"meta": {
"status": "OK"
},
"result": {
"data": {
"1": [
{
"sub_id": "1267827",
"rebill_count": 1,
"status": "rebill",
"next_rebill_amount": "29.99",
"item_id": "2671757",
"order_id": "2635889",
"amount": "29.99",
"trial_amount": "4.99",
"trial_unit": "day",
"trial_period": "5",
"rebill_unit": "month",
"rebill_period": "1",
"max_rebill_count": "-1",
"description": "$4.99 5 day trial rebills at $29.99\/month",
"user_id": "7967584",
"transactions": [
{
"tran_id": "6675677",
"amount": "29.99",
"currency": "USD",
"status": "successful",
"refunded_tran_id": "0",
"refunded": 0,
"refunded_amount": 0,
"ccnum": "474472xxxxxx0474",
"ccname": "Knotia Wilson",
"ccxpdate": "2019-05-01",
"cctype": "visa",
"cccountry": "US",
"processor": "RG",
"processor_name": "RocketGate"
},
{
"tran_id": "6639402",
"amount": "29.99",
"currency": "USD",
"status": "failed",
"refunded_tran_id": "0",
"refunded": 0,
"refunded_amount": 0,
"ccnum": "474472xxxxxx0474",
"ccname": "Knotia Wilson",
"ccxpdate": "2019-05-01",
"cctype": "visa",
"cccountry": "US",
"processor": "RG",
"processor_name": "RocketGate"
},
{
"tran_id": "6596588",
"amount": "4.99",
"currency": "USD",
"status": "successful",
"refunded_tran_id": "0",
"refunded": 0,
"refunded_amount": 0,
"ccnum": "474472xxxxxx0474",
"ccname": "Knotia Wilson",
"ccxpdate": "2019-05-01",
"cctype": "visa",
"cccountry": "US",
"processor": "RG",
"processor_name": "RocketGate"
}
],
"username": "knotiaw71",
"site_domain": "www.bbwtoday.com",
"site_name": "BBW Today",
"system_id": "m1",
"descriptor": "DATINGCUSTSERV.COM 866-294-5787",
"site_id": "5017",
"date_start": "1459301206",
"date_stop": "",
"date_cancel": "",
"date_rebill": "1462325204"
}
]
},
"id": 0
}
}
```
example of failure response:
```lang=json
{
"meta": {
"errors": [
{
"code": "sub_not_found",
"params": null,
"sticky": false,
"text": "No subscription found"
}
],
"status": "ERROR"
},
"result": {
"data": false,
"id": 0
}
}
```