Guide

Django guide for calling the YKNPG transaction flow from a server-side view.

Back to docs Open Swagger

Prerequisites

Python 3.10+, Django 4+, requests, python-dotenv.
Keep YKNPG_API_TOKEN in .env (do not expose in templates/JS).

Create project

mkdir -p demo_django && cd demo_django
python -m venv .venv && source .venv/bin/activate
pip install django requests python-dotenv
django-admin startproject sitecore .
python manage.py startapp payments

Add environment

File: .env

YKNPG_API_TOKEN=replace-with-your-token
YKNPG_BASE_URL=https://yknpg.ngoul.com/api/v1

Enable app and dotenv

File: sitecore/settings.py
- Add "payments" to INSTALLED_APPS.
- Load dotenv near top:

from pathlib import Path
import dotenv, os
dotenv.load_dotenv()

Create form for input

File: payments/forms.py

from django import forms

class TransactionForm(forms.Form):
    phone = forms.CharField(label="Phone number", max_length=32)
    amount = forms.IntegerField(min_value=1)

Create service helper

File: payments/services.py

import os
import time
import requests

API_TOKEN = os.environ["YKNPG_API_TOKEN"]
BASE_URL = os.environ.get("YKNPG_BASE_URL", "https://yknpg.ngoul.com/api/v1")
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}


def create_transaction(amount: int, phone: str) -> dict:
    payload = {
        "amount": amount,
        "provider": "ORANGE_MONEY",
        "user_infos": {"number": phone},
        "callback_url": "http://example.com",
        "callback_method": "POST",
        "your_message": "pay this",
        "your_order_ref": "demo-1",
        "provider_fees_on_customer": True,
    }
    resp = requests.post(f"{BASE_URL}/transactions/", headers=HEADERS, json=payload, timeout=10)
    resp.raise_for_status()
    return resp.json()


def pay_transaction(uuid: str) -> dict:
    resp = requests.post(f"{BASE_URL}/transactions/{uuid}/pay/", headers=HEADERS, timeout=10)
    resp.raise_for_status()
    return resp.json()


def poll_status(uuid: str) -> str:
    status = "new"
    while status in {"new", "paying"}:
        time.sleep(5)
        resp = requests.get(f"{BASE_URL}/transactions/{uuid}/", headers=HEADERS, timeout=10)
        resp.raise_for_status()
        status = resp.json()["status"]
    return status

Create view

File: payments/views.py

from django.shortcuts import render
from .forms import TransactionForm
from .services import create_transaction, pay_transaction, poll_status


def start_payment(request):
    context = {"form": TransactionForm()}
    if request.method == "POST":
        form = TransactionForm(request.POST)
        if form.is_valid():
            data = form.cleaned_data
            trx = create_transaction(data["amount"], data["phone"])
            pay = pay_transaction(trx["uuid"])
            final_status = poll_status(trx["uuid"])
            context.update(
                {
                    "instructions": trx.get("instructions"),
                    "post_pay_instructions": pay.get("instructions"),
                    "final_status": final_status,
                    "form": form,
                }
            )
        else:
            context["form"] = form
    return render(request, "payments/start.html", context)

Add URL

File: payments/urls.py

from django.urls import path
from .views import start_payment

urlpatterns = [path("pay/", start_payment, name="start-payment")]

File: sitecore/urls.py (include payments)

from django.urls import include, path
urlpatterns = [
    path("", include("payments.urls")),
]

Add template

File: payments/templates/payments/start.html

<!DOCTYPE html>
<html>
  <body>
    <h1>Start payment</h1>
    <form method="post">
      {% csrf_token %}
      {{ form.as_p }}
      <button type="submit">Pay</button>
    </form>
    {% if instructions %}
      <p>Gateway instructions: {{ instructions }}</p>
      <p>Post-pay instructions: {{ post_pay_instructions }}</p>
      <p>Final status: {{ final_status }}</p>
    {% endif %}
  </body>
</html>

Run server

python manage.py migrate
python manage.py runserver 0.0.0.0:8000
Visit /pay/ and test.

Notes

Token stays server-side; frontend never sees it.
Flow mirrors management command: create → show instructions → pay → poll.