references/details.md GitHub Copy Downloadpaypal-integration — detailed patterns and worked examples
Express Checkout Implementation
Server-Side Order Creation
import requests
import json
class PayPalClient :
def __init__ (self, client_id, client_secret, mode='sandbox' ):
self .client_id = client_id
self .client_secret = client_secret
self .base_url = 'https://api-m.sandbox.paypal.com' if mode == 'sandbox' else 'https://api-m.paypal.com'
self .access_token = self .get_access_token()
def get_access_token (self ):
"""Get OAuth access token."""
url = f"{self.base_url} /v1/oauth2/token"
headers = {"Accept" : "application/json" , "Accept-Language" : "en_US" }
response = requests.post(
url,
headers=headers,
data={"grant_type" : "client_credentials" },
auth=(self .client_id, self .client_secret)
)
return response.json()['access_token' ]
def create_order (self, amount, currency='USD' ):
"""Create a PayPal order."""
url = f"{self.base_url} /v2/checkout/orders"
headers = {
"Content-Type" : "application/json" ,
"Authorization" : f"Bearer {self.access_token} "
}
payload = {
"intent" : "CAPTURE" ,
"purchase_units" : [{
"amount" : {
"currency_code" : currency,
"value" : str (amount)
}
}]
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
def capture_order (self, order_id ):
"""Capture payment for an order."""
url = f"{self.base_url} /v2/checkout/orders/{order_id} /capture"
headers = {
"Content-Type" : "application/json" ,
"Authorization" : f"Bearer {self.access_token} "
}
response = requests.post(url, headers=headers)
return response.json()
def get_order_details (self, order_id ):
"""Get order details."""
url = f"{self.base_url} /v2/checkout/orders/{order_id} "
headers = {
"Authorization" : f"Bearer {self.access_token} "
}
response = requests.get(url, headers=headers)
return response.json()
IPN (Instant Payment Notification) Handling
IPN Verification and Processing
from flask import Flask, request
import requests
from urllib.parse import parse_qs
app = Flask(__name__)
@app.route('/ipn' , methods=['POST' ] )
def handle_ipn ():
"""Handle PayPal IPN notifications."""
ipn_data = request.form.to_dict()
if not verify_ipn(ipn_data):
return 'IPN verification failed' , 400
payment_status = ipn_data.get('payment_status' )
txn_type = ipn_data.get('txn_type' )
if payment_status == 'Completed' :
handle_payment_completed(ipn_data)
elif payment_status == 'Refunded' :
handle_refund(ipn_data)
elif payment_status == 'Reversed' :
handle_chargeback(ipn_data)
return 'IPN processed' , 200
def verify_ipn (ipn_data ):
"""Verify IPN message authenticity."""
verify_data = ipn_data.copy()
verify_data['cmd' ] = '_notify-validate'
paypal_url = 'https://ipnpb.sandbox.paypal.com/cgi-bin/webscr'
response = requests.post(paypal_url, data=verify_data)
return response.text == 'VERIFIED'
def handle_payment_completed (ipn_data ):
"""Process completed payment."""
txn_id = ipn_data.get('txn_id' )
payer_email = ipn_data.get('payer_email' )
mc_gross = ipn_data.get('mc_gross' )
item_name = ipn_data.get('item_name' )
if is_transaction_processed(txn_id):
return
print (f"Payment completed: {txn_id} , Amount: ${mc_gross} " )
def handle_refund (ipn_data ):
"""Handle refund."""
parent_txn_id = ipn_data.get('parent_txn_id' )
mc_gross = ipn_data.get('mc_gross' )
print (f"Refund processed: {parent_txn_id} , Amount: ${mc_gross} " )
def handle_chargeback (ipn_data ):
"""Handle payment reversal/chargeback."""
txn_id = ipn_data.get('txn_id' )
reason_code = ipn_data.get('reason_code' )
print (f"Chargeback: {txn_id} , Reason: {reason_code} " )
Subscription/Recurring Billing
Create Subscription Plan
def create_subscription_plan (name, amount, interval='MONTH' ):
"""Create a subscription plan."""
client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
url = f"{client.base_url} /v1/billing/plans"
headers = {
"Content-Type" : "application/json" ,
"Authorization" : f"Bearer {client.access_token} "
}
payload = {
"product_id" : "PRODUCT_ID" ,
"name" : name,
"billing_cycles" : [{
"frequency" : {
"interval_unit" : interval,
"interval_count" : 1
},
"tenure_type" : "REGULAR" ,
"sequence" : 1 ,
"total_cycles" : 0 ,
"pricing_scheme" : {
"fixed_price" : {
"value" : str (amount),
"currency_code" : "USD"
}
}
}],
"payment_preferences" : {
"auto_bill_outstanding" : True ,
"setup_fee" : {
"value" : "0" ,
"currency_code" : "USD"
},
"setup_fee_failure_action" : "CONTINUE" ,
"payment_failure_threshold" : 3
}
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
def create_subscription (plan_id, subscriber_email ):
"""Create a subscription for a customer."""
client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
url = f"{client.base_url} /v1/billing/subscriptions"
headers = {
"Content-Type" : "application/json" ,
"Authorization" : f"Bearer {client.access_token} "
}
payload = {
"plan_id" : plan_id,
"subscriber" : {
"email_address" : subscriber_email
},
"application_context" : {
"return_url" : "https://yourdomain.com/subscription/success" ,
"cancel_url" : "https://yourdomain.com/subscription/cancel"
}
}
response = requests.post(url, headers=headers, json=payload)
subscription = response.json()
for link in subscription.get('links' , []):
if link['rel' ] == 'approve' :
return {
'subscription_id' : subscription['id' ],
'approval_url' : link['href' ]
}
Refund Workflows
def create_refund (capture_id, amount=None , note=None ):
"""Create a refund for a captured payment."""
client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
url = f"{client.base_url} /v2/payments/captures/{capture_id} /refund"
headers = {
"Content-Type" : "application/json" ,
"Authorization" : f"Bearer {client.access_token} "
}
payload = {}
if amount:
payload["amount" ] = {
"value" : str (amount),
"currency_code" : "USD"
}
if note:
payload["note_to_payer" ] = note
response = requests.post(url, headers=headers, json=payload)
return response.json()
def get_refund_details (refund_id ):
"""Get refund details."""
client = PayPalClient(CLIENT_ID, CLIENT_SECRET)
url = f"{client.base_url} /v2/payments/refunds/{refund_id} "
headers = {
"Authorization" : f"Bearer {client.access_token} "
}
response = requests.get(url, headers=headers)
return response.json()
Error Handling
class PayPalError (Exception ):
"""Custom PayPal error."""
pass
def handle_paypal_api_call (api_function ):
"""Wrapper for PayPal API calls with error handling."""
try :
result = api_function()
return result
except requests.exceptions.RequestException as e:
raise PayPalError(f"Network error: {str (e)} " )
except Exception as e:
raise PayPalError(f"PayPal API error: {str (e)} " )
try :
order = handle_paypal_api_call(lambda : client.create_order(25.00 ))
except PayPalError as e:
log_error(e)