Welcome to the recursiv integration guide. Here you'll find all you need to effectively use our services. This is version 1.0 of the product, a FREE version for businesses, which currently integrates with the Stripe gateway via Stripe Connect to sustain our base offering. Future versions will expand to include additional payment gateways, enhancing our flexibility and reach. Head over the next section to get started.
The first thing you'll need to do is get your API keys, which is no more than a PKCE Oauth2 client.
This type of authentication flow is based on the Authorization Code grant with the addition of PKCE (Proof Key for Code Exchange). It is recommended for Single Page Applications (SPAs) and other public clients that cannot securely store a client secret. However, it enhances security in confidential ones too. You'll use the token obtained through this flow when pushing your user's customer_id. It's the token you'll present to the https://recursiv.io/api/customers endpoint. To set it up, go to the OAuth tab and follow these steps:
Note: For production, you may be better served by an Oauth library that can handle clients, store tokens securely and auto-refreshes them. Here's a list of python Oauth2 libraries
Flask code to obtain token in the PKCE flow:
from flask import Flask, redirect, request, jsonify, session
import requests
import base64
import os
import hashlib
app = Flask(__name__)
app.secret_key = 'your_flask_secret_key' # Necessary for session management
CLIENT_ID = "your_client_id"
AUTHORIZATION_BASE_URL = 'https://recursiv.io/o/authorize/'
TOKEN_URL = 'https://recursiv.io/o/token/'
REDIRECT_URI = 'your_redirect_uri'
def generate_pkce_verifier():
return base64.urlsafe_b64encode(os.urandom(30)).rstrip(b'=').decode('utf-8')
def generate_pkce_challenge(verifier):
challenge = hashlib.sha256(verifier.encode('utf-8')).digest()
return base64.urlsafe_b64encode(challenge).rstrip(b'=').decode('utf-8')
@app.route('/')
def index():
pkce_verifier = generate_pkce_verifier()
pkce_challenge = generate_pkce_challenge(pkce_verifier)
authorization_url = f"{AUTHORIZATION_BASE_URL}?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&code_challenge={pkce_challenge}&code_challenge_method=S256&approval_prompt=auto"
session['pkce_verifier'] = pkce_verifier # Store the PKCE verifier in the session
html_content = f"""
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>OAuth2 Authorization</title>
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tailwind.min.css" rel="stylesheet">
</head>
<body class="bg-black flex items-center justify-center h-screen">
<div class="absolute top-0 left-0 p-8 text-left w-full max-w-md">
<h1 class="text-2xl text-white font-bold mb-4">OAuth2 Authorization</h1>
<p class="mb-6 text-white font-bold">Click the button below to authorize:</p>
<a href="{authorization_url}" class="bg-indigo-500 text-white py-2 px-4 rounded hover:bg-blue-600">Authorize</a>
</div>
</body>
</html>
"""
return html_content
@app.route('/callback/')
def callback():
code = request.args.get('code')
pkce_verifier = session.get('pkce_verifier') # Retrieve the PKCE verifier from the session
token_data = {
'code': code,
'redirect_uri': REDIRECT_URI,
'client_id': CLIENT_ID,
'code_verifier': pkce_verifier,
'grant_type': 'authorization_code',
}
headers = {
'Cache-Control': 'no-cache',
'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.post(TOKEN_URL, data=token_data, headers=headers)
return jsonify(response.json())
if __name__ == '__main__':
app.run(debug=True)
We will use Stripe Connect to fetch user subscription data such as prices and renewal dates, and also to create customer portal sessions. This allows users to manage their subscriptions and payment details easily. For this integration, we need the Stripe account owner's authorization. To provide authorization, simply go to the Connect tab and click the button to authorize.
You can revoke authorization at any moment from the same tab or from your Stripe's dashboard.
With the previous steps completed, you are now set to make an API call using the token you previously obtained. In the API call, you will pass your user's Stripe customer_id, which is what will be used to make the requests to Stripe on your behalf with the authorization provided in the Connect step.
To effectively learn how to use the API, you can either check it out at the browsable API, where you don't need to present an oauth token and can simply use your session credentials to make calls (useful for inspection purposes), or check the endpoints in redoc.
Overview of each field in the JSON object:
If you need further assistance, please contact our support team at Slack or at [email protected]