Integrate Spotflow Initialize/Redirect API Into Your Application
This tutorial will help you integrate the Spotflow API into your application.
Watch the full demo:
Integrating a payment gateway into your application goes beyond processing payments.You need to ensure customers can make payments easily, without delays or frustrating declined error messages that make them hiss. At the same time, you want to ensure transactions are adequately secure to protect customer-sensitive data and prevent malicious actors from manipulating transaction status.This is where the Spotflow Initialize Payment API shines. It allows you to seamlessly initialize a payment, complete the checkout process, and securely verify the transaction to ensure only valid transactions are approved.This tutorial provides a practical step-by-step process for integrating the Initialize Payment API in your application. It explains how to:
Initialize a payment.
Redirect to the checkout URL to complete the payment.
To integrate the Spotflow Initialize Payment API endpoint, you must have the following:
A Spotflow merchant account that is KYB Verified and Configured. You can sign up for an account here.
Get your API Credentials(API Keys) i.e your test secret key or live secret key from your Spotflow dashboard. This will be used to authenticate your request.
Step-by-step Process on How to Integrate Spotflow Initialize Payment API
To make this tutorial practical, we will build a simple event ticket app. Although this may differ from the app you want to build, the process is usually the same.
This way, you can understand how the integration works and easily add the API to your application.
Retrieve the basic customer information you need to process their transactions. E.g., name, email address, amount, etc.
You can retrieve customer information from your database or from an HTML form, just like the one in the example below.
Step 2: Temporarily store the retrieved data if you are using the HTML form method
Copy
def ticket(request): if request.method == "POST": username = request.POST.get("username") email = request.POST.get("email") ticket = request.POST.get("ticket") try: ticket = int(ticket) #converts the ticket input to integer request.session["ticket"] = ticket # temporarily store the ticket input request.session["username"] = username # temporarily store the username request.session["email"] = email # temporarily store the email return redirect("checkout") except ValueError: messages.info(request, "Invalid input") # throws an error if the input is not an integer return redirect("ticket") return render(request, "ticket.html",)
This represents the specific URL you want to redirect customers to immediately after the checkout process.
You can set this on your Spotflow dashboard in Settings —> Payments —> API Keys —> Webhooks & CallBack —> CallBack URL.
Step 6: Retrieve all the information you need to send a request to the initalize API in your checkout function.
Information like username, amount, and email is compulsory.
Copy
def checkout(request): ticket = request.session.get("ticket") # retrieves the number of tickets username = request.session.get("username") # retrieves the username email = request.session.get("email") # retrieves the email price = 1000 # represents the ticket price amount = price * ticket # calculates the ticket amount reference = f"ref-{uuid.uuid4()}" # this represents the unique ID, but should be replaced by a unique ID generated by your company currency = "NGN" API_KEY = "YOUR_SECRET_KEY" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }
The reference in the example above generates a universally unique identifier, but must be replaced by a unique ID from your system to make payments easy to track.
Step 10: Retrieve reference and checkoutUrl from the response.
These are the two important keys you need.
Copy
if response.status_code == 200: converter = response.json() extractData = { "reference": converter.get("reference"), # this retrieves the reference from the response stored in the `converter` variable "checkoutURL": converter.get("checkoutUrl"), # this retrieves checkoutUrl from the response stored in the `converter` variable }
Step 11: Redirect the user to the checkoutUrl to complete the checkout process.
This is where users will securely make payments using the Spotflow secure payment gateway.
Copy
if response.status_code == 200: converter = response.json() extractData = { "reference": converter.get("reference"), "checkoutURL": converter.get("checkoutUrl"), } return redirect(extractData["checkoutURL"]) # redirects user to the checkout page else: messages.info(request, "An error occurred.") return redirect("ticket")
Once a user clicks the “Pay” button in the frontend, it initializes a transaction by making a POST request to the Initialize API and then redirects to the checkoutUrl to make payments.You should have something like this:
The user can then complete their payment via bank transfer or card. This is one of the most important aspects of using the Spotflow API.
It enables you to securely process transactions faster without revealing sensitive customer financial details.
To pay with a card, you can use Spotflow’s test cards in test mode and then a real card in live mode.
Step 12: Once the payment is complete, it will automatically redirect them to the callBackUrl you specified earlier.
Important Notes:
You, as the merchant that owns the application and the user who made the payment, will receive the payment receipt in your email once the payment is successful.
If you don’t specify the callbackUrl, the user will not be redirected to your site after payments.
Now, the next step is to verify their transaction.
Once the user completes payment, you need to verify the transaction status to prevent fraud.There are two ways to verify a transaction status. You can either use the verify payment API or the webhooks.
However, the webhook method is often preferred because it provides real-time updates and is more efficient than calling the verify payment API repeatedly to check transaction status.
Webhooks are event-triggered messages that automatically update you whenever a payment status changes.For instance, when a customer makes a payment and the transaction is successful/failed, that is an event. Spotflow instantly sends a POST request to the webhook URL you set.This request provides information about the event, such as the reference, amount, etc. Then you can retrieve the data and determine how you want to update your user on the status of their transaction or the next steps.There are two main steps involved when using the webhook methods.
You can instantly create a webhook URL on sites like webhook.site when testing and then create a new URL (specific endpoint) in your backend when you want to go live.
1
How to Set Up Webhook URL in Your Backend
Set up the webhook URL path in the urls.py if you are using Django.
In your views function, set up a simple POST request that Spotflow can send updates to.
Copy
import jsonfrom django.http import JsonResponse, HttpResponseBadRequestfrom django.views.decorators.csrf import csrf_exempt@csrf_exempt # This exempts the view function from CSRF protectiondef webhook (request): if request.method == "POST": try: payload = json.loads(request.body) # retrieves the request body eventType = payload.get("event") # retrieves the event type data = payload.get("data", {}) # retrieves the data if eventType == "payment_successful": # checks if payment is successful reference = data.get("reference") # retrieves the payment reference from the data amount = data.get("amount") # retrieves the amount from the data print("Payment successful with ID", reference, "Amount", amount) # displays success message or provide a logic to update the database elif eventType == "payment_failed": # checks if payment failed reference = data.get("reference") # retrieves the payment reference from the data print("Payment failed with ID", reference) # failure message or provide a logic to update the database return JsonResponse({"status": "success"}, status=200) # must always return a 200 status code to acknowledge an event occurred and to prevent triggering the webhook multiple times except Exception as e: print("Error processing webhook", e) # displays an error message return JsonResponse({"status": "error"}, status=400) return JsonResponse({"status": "Method not allowed"}, status=405)
Navigate to the “Settings” section and click the “Payments” tab.
Click the “API Keys” option and scroll down to the “Webhook” section.
Enter your webhook URL in the box and click the save/update button.
If you are using a unique webhook URL from webhook testing tools like webhook.site, paste it here directly.
If you configured it in your backend, paste the deployed URL here.
Enter the OTP from your authenticator app to complete the process.
2
After setting this up, your webhook URL will be triggered whenever an event occurs. Then you can use the event information to verify transaction status.You will receive something like this in your server logs whenever an event is triggered. E.g., when a payment is successful.
How to Verify Transaction Status Using the Verify Payment API
The Spotflow Verify Payment API allows you to verify transaction status using your set unique reference ID at payment creation.Here is how the verification process typically works.
Step 6: Display the necessary details you want users to see in the verification page.
Something like this:
Now, you have securely verified the transaction status using the Spotflow verify payment endpoint.You can watch the demo video above to see the complete payment workflow, or check the live demo.
Congratulations! You’ve Implemented the Initialize/Redirect API
You’ve successfully integrated the Redirect checkout with Spotflow! Here’s what you accomplished:
Secure Payment Processing
Your application can now accept payments securely through Spotflow
Payment Initialization
You can create payment sessions and generate unique checkout URLs for your customers
Smooth Checkout Experience
Your users are automatically redirected to Spotflow’s secure checkout page to complete payments
Transaction Verification & Professional Payment Flow
You’ve implemented either webhook or API-based verification to confirm payment status & prevent fraud with a complete end-to-end payment workflow from initialization to verification
This example demonstrates only a minimal implementation of the Initialize/Redirect API. For production use, you should add robust error handling, authentication, data validation, security measures, and adapt the logic to fit your application’s requirements.
