Skip to content
qiyas.cc
Problem Solver
cc · blog · Engineering 2026-11-12 · 8 min

Epoint ödənişini sayta necə qoşmaq olar

Epoint ödənişinin saytda necə işlədiyini əvvəlcə sadə dillə, sonra kodla izah edirəm: açarlar, imza, callback, status, geri qaytarma və ən çox edilən səhvlər.


Saytınızda kartla ödəniş qəbul etmək istəyirsiniz və bank sizə Epoint-i məsləhət görüb. Və ya artıq Epoint ilə müqavilə bağlamısınız, açarları almısınız, indi isə “bunu sayta necə qoşaq?” sualı qalıb.

Bu yazı həmin sual üçündür. Epoint üçün açıq mənbəli Python kitabxanası yazmışam, epoint-python-sdk. Onu yazarkən Epoint-in API sənədini sətir-sətir oxumalı oldum. Aşağıda həm o sənəddən, həm də kitabxananın özündən gələn real ad və ünvanlar var. Uydurma heç nə yoxdur.

Yazı iki hissədir. Birinci hissə biznes sahibi üçündür: kod yoxdur, sadəcə nə baş verdiyi. İkinci hissə proqramçı üçündür.

Ödəniş əslində necə işləyir

Epoint-in öz sənədində axın beş addımla təsvir olunur. Mən onu bir az insan dilinə çevirirəm:

  1. Müştəri saytınızda “Ödə” düyməsini basır. Sizin server Epoint-ə sorğu göndərir: “bu sifariş üçün bu qədər pul almaq istəyirəm”.
  2. Epoint cavabında bir keçid qaytarır. Müştəri o keçidlə bankın ödəniş səhifəsinə gedir.
  3. Müştəri kart məlumatlarını orada, bankın səhifəsində daxil edir. Kart nömrəsi sizin sayta heç vaxt gəlmir. Bu yaxşıdır, çünki kart məlumatını saxlamaq ayrıca böyük məsuliyyətdir.
  4. Ödəniş uğurlu olsa, müştəri sizin “uğurlu” səhifənizə, olmasa “uğursuz” səhifənizə qaytarılır.
  5. Ən vacib addım: Epoint nəticəni ayrıca, serverdən serverə, sizin “nəticə ünvanınıza” göndərir. Bu mesaj imzalanıb.

Biznes sahibi üçün buradan bir qayda çıxır: müştərinin “uğurlu” səhifəsinə qayıtması ödənişin olduğunu sübut etmir. Sübut beşinci addımdakı imzalı mesajdır. Bu fərqi bilməyən sayt gec-tez pulu alınmamış sifarişi göndərəcək.

Başlamaq üçün nə lazımdır

  • Tacir müqaviləsi. Açarları Epoint müqavilədən sonra verir.
  • Dörd ünvan. Sənəd tacir qeydiyyatı üçün bunları istəyir: saytın ünvanı, uğurlu ödəniş səhifəsi (success_url), uğursuz ödəniş səhifəsi (error_url) və nəticənin göndərildiyi ünvan (result_url).
  • İki açar. public_key tacirin identifikatorudur, i000000001 kimi görünür və sirr deyil. private_key isə məxfi açardır. Kimdə olsa, sizin adınızdan sorğu göndərə və saxta “ödəniş oldu” mesajı düzəldə bilər. O, yalnız serverdə yaşamalıdır: JavaScript-də, mobil tətbiqdə, git tarixçəsində yox.

Apple Pay, Google Pay, taksit, pul kisələri kimi bəzi imkanları Epoint hər tacir üçün ayrıca açır. Onlara əsaslanan kod yazmazdan əvvəl Epoint-dən soruşun ki, sizdə aktivdirmi.

Pərdə arxasında: data və signature

Epoint-ə gedən hər sorğu iki sahədən ibarətdir:

  • data: parametrlər JSON şəklində, sonra base64 ilə kodlanmış.
  • signature: base64(sha1(private_key + data + private_key)).

Burada hamının ən azı bir dəfə ilişdiyi yer var: sha1-in nəticəsi xam 20 baytdır, hex sətir deyil. Hex sətri base64-ə çevirsəniz, imza alınmayacaq və Epoint sorğunu qəbul etməyəcək.

Python-da təmiz halda belə görünür:

import base64
import hashlib
import json

def encode(payload):
    body = json.dumps(payload, separators=(",", ":"))
    return base64.b64encode(body.encode()).decode()

def sign(private_key, data):
    digest = hashlib.sha1(f"{private_key}{data}{private_key}".encode()).digest()
    return base64.b64encode(digest).decode()

Epoint-in sənədində hazır nümunə var: məlum test açarı və məlum data üçün imza a76GNudqblZtV8qF199hctA+cG0= olmalıdır. SDK-dakı sign funksiyasını bu nümunə ilə yoxladım, eyni nəticəni verir. Öz kodunuzu yazırsınızsa, ilk testiniz bu olsun.

Ödəniş sorğusunun əsas parametrləri sənəddə belədir:

Parametr Məcburi Mənası
public_key bəli tacirin identifikatoru
amount bəli məbləğ, məsələn 20.50
currency bəli valyuta, sənəddə AZN
language bəli səhifənin dili: az, en, ru
order_id bəli sizin sistemdə unikal sifariş nömrəsi, 255 simvola qədər
description xeyr təsvir, 1000 simvola qədər
success_redirect_url xeyr bu sorğu üçün ayrıca uğurlu səhifə
error_redirect_url xeyr bu sorğu üçün ayrıca uğursuz səhifə

Sorğu https://epoint.az/api/1/request ünvanına POST ilə gedir və cavabda redirect_url gəlir. Alternativ yol da var: müştərini birbaşa forma ilə https://epoint.az/api/1/checkout ünvanına göndərmək.

SDK ilə: quraşdırma

İmzanı, kodlamanı, xətaları və təkrar cəhdləri hər layihədə yenidən yazmamaq üçün kitabxananı istifadə edirəm:

pip install epoint-python-sdk

Açarları mühit dəyişənlərində saxlayın:

export EPOINT_PUBLIC_KEY=i000000001
export EPOINT_PRIVATE_KEY=your-private-key
export EPOINT_SUCCESS_URL=https://shop.az/payments/ok/
export EPOINT_ERROR_URL=https://shop.az/payments/fail/

Bütün layihə üçün bir klient:

from epoint_sdk import Epoint

epoint = Epoint()

Açarlardan biri yoxdursa, Epoint() dərhal ConfigurationError atır. Yəni səhv yerləşdirmə müştəri ödəniş edəndə yox, server açılanda üzə çıxır.

Ödənişi başlatmaq

from django.shortcuts import get_object_or_404, redirect, render
from django.views.decorators.http import require_POST
from epoint_sdk import GatewayError, InvalidRequestError, NotSentError, OutcomeUnknownError

from .epoint import epoint
from .models import Order

@require_POST
def pay(request, number):
    order = get_object_or_404(Order, number=number, state__in=["new", "failed"])
    order.attempt += 1
    order.epoint_order_id = f"{order.number}-{order.attempt}"
    order.state = "pending"
    order.save(update_fields=["attempt", "epoint_order_id", "state"])

    try:
        checkout = epoint.payments.create(order.total, order.epoint_order_id, description=order.title)
    except (InvalidRequestError, GatewayError):
        order.state = "failed"
        order.save(update_fields=["state"])
        return render(request, "payments/error.html", {"order": order})
    except NotSentError:
        order.state = "new"
        order.save(update_fields=["state"])
        return render(request, "payments/retry_later.html", {"order": order})
    except OutcomeUnknownError:
        order.state = "needs_check"
        order.save(update_fields=["state"])
        return render(request, "payments/checking.html", {"order": order})

    order.epoint_transaction = checkout.transaction or ""
    order.save(update_fields=["epoint_transaction"])
    return redirect(checkout.redirect_url)

Burada iki detal var ki, sonradan baş ağrısından qoruyur.

Birincisi, order_id sifariş nömrəsi ilə cəhd sayğacından düzəlir: A1042-1, A1042-2. Sənəd order_id-nin unikal olmasını tələb edir. Müştərinin kartı rədd edilsə və o yenidən cəhd etsə, yeni nömrə lazımdır. Sayğac bunu həll edir.

İkincisi, xətalar fərqlidir. NotSentError sorğunun Epoint-ə heç getmədiyini bildirir, yenidən cəhd etmək təhlükəsizdir. OutcomeUnknownError isə sorğunun getdiyini, amma cavabın gəlmədiyini bildirir. Pul hərəkət edən əməliyyatda SDK belə halda özbaşına təkrar göndərmir, çünki ödəniş iki dəfə keçə bilər. Sifarişi “yoxlanmalı” vəziyyətinə salırsınız və statusu soruşursunuz.

Callback: yeganə həqiqət

from django.db import transaction
from django.http import HttpResponse, HttpResponseBadRequest
from django.utils import timezone
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from epoint_sdk import SignatureError

@csrf_exempt
@require_POST
def callback(request):
    try:
        tx = epoint.verify_callback(request.POST)
    except SignatureError:
        return HttpResponseBadRequest()

    with transaction.atomic():
        order = Order.objects.select_for_update().filter(epoint_order_id=tx.order_id).first()
        if order is None or not tx.matches(order_id=order.epoint_order_id, amount=order.total):
            return HttpResponse("OK")

        if tx.paid and order.state != "paid":
            order.state = "paid"
            order.epoint_transaction = tx.transaction or order.epoint_transaction
            order.paid_at = timezone.now()
            order.save(update_fields=["state", "epoint_transaction", "paid_at"])
        elif tx.failed and order.state == "pending":
            order.state = "failed"
            order.save(update_fields=["state"])

    return HttpResponse("OK")

Bu kiçik funksiyada dörd qoruma var:

  • İmza. verify_callback imzanı sabit vaxtda müqayisə edir. Uyğun gəlmirsə, SignatureError atır və sorğunun heç bir sahəsi oxunmur.
  • Uyğunluq. Düzgün imza yalnız mesajın Epoint-dən gəldiyini sübut edir. Mesajın məhz bu sifariş və bu məbləğ haqqında olduğunu tx.matches(...) yoxlayır.
  • Təkrara dözümlülük. Eyni callback iki dəfə gələ bilər. select_for_update() sətri kilidləyir, order.state != "paid" yoxlaması isə sifarişin iki dəfə “ödənilib” olmasının qarşısını alır.
  • CSRF istisnası. Epoint-in serverində sizin CSRF tokeniniz yoxdur, ona görə bu view csrf_exempt olmalıdır.

Müştəriyə e-poçt, faktura və digər ağır işlər transaction-dan sonra, fon tapşırığında getsin. Callback-ə tez cavab verin.

Uğurlu səhifə təsdiq deyil

success_url səhifəsində “ödəniş qəbul olundu” yazmayın. “Ödənişinizi təsdiqləyirik” yazın və sifarişin statusunu öz bazanızdan oxuyun. Callback hələ gəlməyibsə, serverdən soruşun:

tx = epoint.payments.status(order.epoint_transaction)
if tx.paid:
    ...

status həm Epoint-in tranzaksiya nömrəsi ilə, həm də öz order_id-niz ilə işləyir: epoint.payments.status(order_id="A1042-1").

Şəbəkə bəzən kəsilir və callback heç gəlmir. Ona görə uzun müddət “gözləyir” vəziyyətində qalan sifarişləri tapıb Epoint-dən statusunu soruşan dövri tapşırıq qurun. Bu, ayda bir dəfə “pul çıxıb, sifariş görünmür” zənginin qarşısını alır.

Pulu geri qaytarmaq

Tam qaytarma:

result = epoint.payments.reverse(order.epoint_transaction)
if result.ok:
    order.state = "refunded"
    order.save(update_fields=["state"])

Qismən qaytarma üçün məbləği ikinci arqument kimi verin:

epoint.payments.reverse(order.epoint_transaction, "5.00")

Sənəddə reverse əməliyyatı əvvəlki ödənişi ləğv edir və qismən məbləği qəbul edir. Bundan başqa, “payout” (refund-request) var: o, əvvəlki ödənişə bağlı deyil, pulu yadda saxlanmış karta göndərir. Müştəri pulunu geri istəyirsə, sizə lazım olan reverse-dir.

Kartı yadda saxlamaq

Abunəlik, bir kliklə ödəniş və balans artırma yadda saxlanmış kart üzərində qurulur. Kartın özü Epoint-də qalır, sizdə yalnız card_id olur.

İlk ödənişlə birlikdə kartı saxlamaq:

reg = epoint.cards.register_and_pay("9.90", "SUB-1001-1", description="Aylıq plan")
user.card_id = reg.card_id
user.save(update_fields=["card_id"])
return redirect(reg.redirect_url)

Növbəti ayın ödənişi, müştəri heç bir səhifəyə getmədən:

tx = epoint.cards.charge(user.card_id, "9.90", "SUB-1001-2", description="Aylıq plan, mart")
if tx.paid:
    extend_subscription(user)
elif tx.failed:
    notify_card_declined(user, tx.message)

Rədd edilmiş kart xəta atmır. tx.failed olur, bankın kodu və mesajı içində gəlir. Hər ödəniş dövrü üçün yeni order_id istifadə edin.

Apple Pay və Google Pay

Epoint bunları widget ilə verir. Əvvəlcə sizdə aktiv olub-olmadığını yoxlayın:

methods = epoint.payments.methods()
methods.apple_pay, methods.google_pay

Sonra widget yaradıb səhifədə iframe kimi göstərirsiniz:

widget = epoint.widgets.create("19.90", "ORDER-1043", "Pro plan")

Səhifə Permissions-Policy: payment=(self "https://epoint.az") başlığı ilə verilməlidir. Widget-in brauzerə göndərdiyi mesaj yalnız ipucudur. Nəticəni yenə serverdə, payments.status(widget.transaction) və ya imzalı callback ilə təsdiqləyin.

Test etmək

Epoint açıq test kartları dərc etmir. Tacir hesabı olmadan inkişaf etdirmək üçün icma tərəfindən yazılmış epoint-sandbox var: Epoint API-ni təqlid edir və callback-ləri eyni qaydada imzalayır. SDK-da base_url-i ona yönəldirsiniz, canlıya keçəndə https://epoint.az və real açarlara qayıdırsınız.

Callback testləri üçün SDK-da callback_form var, Epoint-in göndərəcəyi kimi imzalanmış forma düzəldir:

from epoint_sdk import callback_form

form = callback_form(PRIVATE_KEY, {"status": "success", "order_id": "A1042-1", "transaction": "te1", "amount": "19.90"})
response = client.post("/payments/epoint/callback/", form)

Ən çox gördüyüm səhvlər

  1. Redirect-ə inanmaq. Müştəri success_url-ə qayıtdı deyə sifariş “ödənilib” olur. Həmin ünvanı hər kəs brauzerə yaza bilər.
  2. İmzanı yoxlamamaq. Callback-dəki data-nı açıb status: success görmək kifayət deyil. İmzasız yoxlama ilə istənilən adam sizin nəticə ünvanınıza “ödəniş oldu” göndərə bilər.
  3. Hex digest. sha1(...).hexdigest()-i base64-ə çevirmək. Lazım olan xam baytlardır, .digest().
  4. Təkrara dözümsüz callback. Eyni mesaj iki dəfə gəlir, müştəriyə iki məktub gedir, anbardan iki məhsul çıxır.
  5. Məbləği float ilə saxlamaq. 19.9 və 19.90 sizin üçün eynidir, amma float hesabında qəribə qalıqlar yaranır. Məbləği Decimal kimi saxlayın. SDK 1.005 kimi üç rəqəmli qəpikləri və sıfır məbləği sorğu getməmiş rədd edir.
  6. Valyutanı unutmaq. Sənəddə ödəniş valyutası AZN-dir. Başqa valyuta lazımdırsa, bunu əvvəlcədən Epoint ilə dəqiqləşdirin.
  7. Məxfi açarı frontend-ə qoymaq. Brauzerdə imza hesablayan kod məxfi açarı hamıya paylayır.
  8. Uzlaşdırma tapşırığının olmaması. Callback gəlməyəndə sifariş əbədi “gözləyir” qalır.

Bu səkkiz maddəni bağlasanız, Epoint inteqrasiyası çətin deyil. Sadəcə ödəniş kodunda “sonra düzəldərik” deyilən hər şey, adətən, ən pis vaxtda düzəldilir.

Saytınıza Epoint qoşmaq və ya mövcud inteqrasiyanı yoxlatmaq istəyirsinizsə, ödəniş sistemi inteqrasiyası səhifəsinə baxın və ya yazın. Biznesdə tez-tez qarşılaşılan başqa texniki problemlər üçün: Biznesdə ən çox rast gəlinən texniki problemlər.

Mənbələr

Oxşar yazılar