319 lines
11 KiB
Python
Executable file
319 lines
11 KiB
Python
Executable file
#!/usr/bin/python3
|
|
"""Download or cancel subscribers or subscriber transactions from PayPal."""
|
|
|
|
import argparse
|
|
import collections
|
|
import datetime
|
|
import os
|
|
import sys
|
|
|
|
import requests
|
|
|
|
HELP = """This tool is used to help Conservancy keep track of Sustainers.
|
|
|
|
With the "transactions" or "profiles" commands, this tool reports either a list
|
|
of recurring payment transactions or a list of unique recurring payment
|
|
subscriber profiles respectively. This recreates the features available in the
|
|
previous PayPal SOAP API where you could query for all ProfileIDs (identifying
|
|
unique subscribers).
|
|
|
|
With the "suspend" command, this tool will find recurring subscriptions matching
|
|
a given transaction subject, and interactively prompt you to review and suspend
|
|
them.
|
|
|
|
Run them like this:
|
|
|
|
$ export PAYPAL_CLIENT_ID=XXX
|
|
$ export PAYPAL_CLIENT_SECRET=YYY
|
|
$ python3 paypal_report.py transactions 2021-11-01T00:00:00-07:00 2021-11-30T23:59:59-07:00 > transactions.txt
|
|
$ python3 paypal_report.py profiles 2021-11-01T00:00:00-07:00 2021-11-30T23:59:59-07:00 > profiles.txt
|
|
$ python3 paypal_report.py suspend 2022-10-01T00:00:00-07:00 2022-10-31T23:59:59-07:00 homebrew
|
|
|
|
NOTE: Newly created PayPal "apps"/credentials initially authenticate, but can
|
|
then return PERMISSION_DENIED for ~ 40 mins.
|
|
|
|
The PayPal OAuth 2.0 client ID and secret can be obtained from the Developer
|
|
Dashboard as described here: https://developer.paypal.com/api/rest/.
|
|
|
|
This tool isn't directly related Beancount, but it may duplicate some
|
|
functionality from the PayPal importer and paypal_rest tools. See also:
|
|
|
|
- conservancy_beancount/doc/PayPalQuery.md
|
|
- NPO-Accounting/paypal_rest
|
|
"""
|
|
|
|
HTTP_TIMEOUT = 10 # seconds
|
|
|
|
|
|
class PayPalException(Exception):
|
|
pass
|
|
|
|
|
|
def paypal_login(client_id, client_secret):
|
|
url = 'https://api-m.paypal.com/v1/oauth2/token?grant_type=client_credentials'
|
|
response = requests.post(
|
|
url,
|
|
auth=(client_id, client_secret),
|
|
headers={
|
|
'Accept': 'application/json',
|
|
'Accept-Language': 'en_US',
|
|
},
|
|
timeout=HTTP_TIMEOUT,
|
|
)
|
|
data = response.json()
|
|
if response.status_code != 200:
|
|
raise PayPalException(f'PayPal login failed: \"{data["error_description"]}\"')
|
|
print('Successfully logged in to PayPal.')
|
|
return data['access_token']
|
|
|
|
|
|
def paypal_get(url, access_token):
|
|
response = requests.get(
|
|
url,
|
|
headers={
|
|
'Accept': 'application/json',
|
|
'Accept-Language': 'en_US',
|
|
'Content-Type': 'application/json',
|
|
'Authorization': f'Bearer {access_token}',
|
|
},
|
|
timeout=HTTP_TIMEOUT,
|
|
)
|
|
data = response.json()
|
|
if response.status_code != 200:
|
|
raise PayPalException(f'PayPal request failed: \"{data["message"]}\"')
|
|
return data
|
|
|
|
|
|
def paypal_post(url, access_token):
|
|
response = requests.post(
|
|
url,
|
|
headers={
|
|
'Accept': 'application/json',
|
|
'Accept-Language': 'en_US',
|
|
'Content-Type': 'application/json',
|
|
'Authorization': f'Bearer {access_token}',
|
|
},
|
|
json={
|
|
'reason': 'suspended',
|
|
},
|
|
timeout=HTTP_TIMEOUT,
|
|
)
|
|
if response.status_code != 204:
|
|
data = response.json()
|
|
raise PayPalException(f'PayPal update failed: \"{data["message"]}\"')
|
|
return response
|
|
|
|
|
|
def main():
|
|
args = parse_args()
|
|
client_id, client_secret = load_paypal_keys()
|
|
try:
|
|
access_token = paypal_login(client_id, client_secret)
|
|
transactions = get_all_transactions(access_token, args.start_date, args.end_date)
|
|
if args.report == 'profiles':
|
|
report_on_unique_profiles(transactions)
|
|
elif args.report == 'transactions':
|
|
report_on_transactions(transactions)
|
|
else:
|
|
suspend_subscriptions_interactively(transactions, args.pattern, access_token)
|
|
except PayPalException as e:
|
|
sys.exit(e)
|
|
|
|
|
|
def parse_args():
|
|
parser = argparse.ArgumentParser(
|
|
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
description="""Download or cancel subscribers or subscriber transactions from PayPal.""",
|
|
epilog=HELP,
|
|
)
|
|
parser.add_argument(
|
|
'report', help='report or action"', choices=['profiles', 'transactions', 'suspend']
|
|
)
|
|
parser.add_argument(
|
|
'start_date',
|
|
help='start date inclusive (eg. 2021-11-01T00:00:00-07:00)',
|
|
type=parse_iso_time,
|
|
)
|
|
parser.add_argument(
|
|
'end_date',
|
|
help='end date inclusive (eg. 2021-11-30T23:59:59-07:00)',
|
|
type=parse_iso_time,
|
|
)
|
|
parser.add_argument('pattern')
|
|
return parser.parse_args()
|
|
|
|
|
|
def parse_iso_time(time_str):
|
|
try:
|
|
time = datetime.datetime.fromisoformat(time_str)
|
|
except ValueError as e:
|
|
raise argparse.ArgumentTypeError(
|
|
'Date did not match ISO format eg. 2021-11-01T00:00:00-07:00'
|
|
) from e
|
|
return time
|
|
|
|
|
|
def load_paypal_keys():
|
|
try:
|
|
client_id = os.environ['PAYPAL_CLIENT_ID']
|
|
client_secret = os.environ['PAYPAL_CLIENT_SECRET']
|
|
except KeyError:
|
|
sys.exit(
|
|
'Please set PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET environment variables.'
|
|
)
|
|
return client_id, client_secret
|
|
|
|
|
|
def get_all_transactions(access_token, start_date, end_date):
|
|
periods = get_time_periods(start_date, end_date)
|
|
transactions = []
|
|
for start, end in periods:
|
|
transactions += get_transactions_for_period(access_token, start, end)
|
|
return transactions
|
|
|
|
|
|
def get_time_periods(start_date, end_date):
|
|
"""Break a time period into smaller periods of up to 31 days.
|
|
|
|
PayPal only supports querying for up to 31 days of transactions at a time.
|
|
"""
|
|
periods = []
|
|
while start_date < end_date:
|
|
periods.append((start_date, start_date + datetime.timedelta(days=31)))
|
|
start_date += datetime.timedelta(days=31)
|
|
return periods
|
|
|
|
|
|
def get_transactions_for_period(access_token, start_date, end_date, page=1):
|
|
"""Downloads all pages of transactions for a time period of 31 days or less."""
|
|
print(
|
|
f'Requesting page {page} of transactions from {start_date} to {end_date}...',
|
|
file=sys.stderr,
|
|
)
|
|
url = f'https://api-m.paypal.com/v1/reporting/transactions?start_date={start_date.isoformat()}&end_date={end_date.isoformat()}&fields=all&page_size=500&page={page}'
|
|
data = paypal_get(url, access_token)
|
|
if page < data['total_pages']:
|
|
return data['transaction_details'] + get_transactions_for_period(
|
|
access_token, start_date, end_date, page + 1
|
|
)
|
|
else:
|
|
return data['transaction_details']
|
|
|
|
|
|
def report_on_unique_profiles(transactions):
|
|
"""Print a list of subscribers from a set of transactions.
|
|
|
|
PayPal doesn't provide a way to query for subscribers directly, so we build
|
|
this by scanning through the list of transactions and finding the unique
|
|
subscribers.
|
|
"""
|
|
records = set()
|
|
for t in transactions:
|
|
transaction_info = t['transaction_info']
|
|
if 'paypal_reference_id' in transaction_info:
|
|
records.add(
|
|
(
|
|
transaction_info['paypal_reference_id'],
|
|
transaction_info.get('transaction_subject', 'NO TRANSACTION SUBJECT'),
|
|
),
|
|
)
|
|
else:
|
|
print(
|
|
f'Skipping transaction {transaction_info["transaction_id"]} with no PayPal Reference ID.',
|
|
file=sys.stderr,
|
|
)
|
|
|
|
for ref_id, desc in sorted(records):
|
|
print(f'{ref_id} {desc}')
|
|
count = collections.Counter([ref_id for ref_id, _ in records])
|
|
dupes = [id for id, total in count.items() if total > 1]
|
|
print(f'Reference IDs with changing subject: {dupes}', file=sys.stderr)
|
|
|
|
|
|
def get_subscriptions_matching_subject(transactions, pattern):
|
|
records = set()
|
|
for t in transactions:
|
|
transaction_info = t['transaction_info']
|
|
if (
|
|
'paypal_reference_id' in transaction_info
|
|
and pattern.lower()
|
|
in transaction_info.get('transaction_subject', 'CANT MATCH ME').lower()
|
|
):
|
|
records.add(
|
|
(
|
|
transaction_info['paypal_reference_id'],
|
|
transaction_info.get('transaction_subject', 'NO TRANSACTION SUBJECT'),
|
|
),
|
|
)
|
|
else:
|
|
# print(f'Skipping transaction {transaction_info["transaction_id"]} with no PayPal Reference ID.', file=sys.stderr)
|
|
pass
|
|
return records
|
|
|
|
|
|
def report_on_transactions(transactions):
|
|
"""Print a formatted list of transactions."""
|
|
for t in transactions:
|
|
transaction_info = t['transaction_info']
|
|
if 'paypal_reference_id' in transaction_info:
|
|
print(
|
|
"%-19s %s"
|
|
% (
|
|
transaction_info['transaction_id'],
|
|
transaction_info['paypal_reference_id'],
|
|
)
|
|
)
|
|
print(
|
|
"%-19s %s"
|
|
% (
|
|
transaction_info['paypal_reference_id'],
|
|
transaction_info['paypal_reference_id'],
|
|
)
|
|
)
|
|
else:
|
|
print(
|
|
f'Skipping transaction {transaction_info["transaction_id"]} with no PayPal Reference ID.',
|
|
file=sys.stderr,
|
|
)
|
|
|
|
|
|
def suspend_subscriptions_interactively(transactions, pattern, access_token):
|
|
subscriptions = get_subscriptions_matching_subject(transactions, pattern)
|
|
for (sub_id, subject) in sorted(subscriptions):
|
|
try:
|
|
sub_before = paypal_get(
|
|
f'https://api.paypal.com/v1/billing/subscriptions/{sub_id}', access_token
|
|
)
|
|
except PayPalException as e:
|
|
sys.exit(e)
|
|
status_before = sub_before['status']
|
|
|
|
# Donor name / total donations / last donation / donation amount / FULL text of the profile Memo description / profile-id " with "Should I cancel this one? (y/n)"
|
|
given_name = sub_before['subscriber'].get('name', {}).get('given_name', '')
|
|
surname = sub_before['subscriber'].get('name', {}).get('surname', '')
|
|
name = ' '.join(filter(bool, [given_name, surname]))
|
|
payments = sub_before['billing_info']['cycle_executions'][0]['cycles_completed']
|
|
last_payment = sub_before['billing_info']['last_payment']
|
|
last_payment_total = last_payment['amount']['value']
|
|
last_payment_currency = last_payment['amount']['currency_code']
|
|
last_payment_time = last_payment['time']
|
|
print(
|
|
f'Subscriber {sub_id} {subject} {status_before}: {name}, {payments} payments with last payment {last_payment_time}, {last_payment_total} {last_payment_currency}'
|
|
)
|
|
if status_before == 'ACTIVE':
|
|
url = f'https://api.paypal.com/v1/billing/subscriptions/{sub_id}/suspend'
|
|
if input('Cancel this one? (y/n) ') == 'y':
|
|
print(f'Updating subscription {sub_id}...')
|
|
paypal_post(url, access_token)
|
|
sub_after = paypal_get(
|
|
f'https://api.paypal.com/v1/billing/subscriptions/{sub_id}',
|
|
access_token,
|
|
)
|
|
status_after = sub_after['status']
|
|
print(f'Subscriber {sub_id} status is now: {status_after}')
|
|
else:
|
|
print(' ignoring inactive status')
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|