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:
- 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”.
- Epoint cavabında bir keçid qaytarır. Müştəri o keçidlə bankın ödəniş səhifəsinə gedir.
- 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.
- Ödəniş uğurlu olsa, müştəri sizin “uğurlu” səhifənizə, olmasa “uğursuz” səhifənizə qaytarılır.
- Ə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_keytacirin identifikatorudur,i000000001kimi görünür və sirr deyil.private_keyisə 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_callbackimzanı sabit vaxtda müqayisə edir. Uyğun gəlmirsə,SignatureErroratı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_exemptolmalı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
- 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. - İmzanı yoxlamamaq. Callback-dəki
data-nı açıbstatus: successgö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. - Hex digest.
sha1(...).hexdigest()-i base64-ə çevirmək. Lazım olan xam baytlardır,.digest(). - 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.
- Məbləği
floatilə saxlamaq.19.9və19.90sizin üçün eynidir, amma float hesabında qəribə qalıqlar yaranır. MəbləğiDecimalkimi saxlayın. SDK1.005kimi üç rəqəmli qəpikləri və sıfır məbləği sorğu getməmiş rədd edir. - 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. - Məxfi açarı frontend-ə qoymaq. Brauzerdə imza hesablayan kod məxfi açarı hamıya paylayır.
- 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
-
TikSocket nədir? Bənzəri varmı?
2026-11-16 · 8 min
-
DDD nədir? Necə tətbiq olunur?
2026-11-15 · 14 min
-
Saytım niyə yavaş açılır və necə düzəlir
2026-11-11 · 7 min