How to add Epoint payments to your website
How Epoint payments work on a website, first in plain words and then in code: keys, the signature, callbacks, status checks, refunds, saved cards and the mistakes I see most.
If you sell online in Azerbaijan, sooner or later someone tells you to use Epoint. You sign the merchant agreement, you get two keys, and then the real question shows up: how do you actually wire this into the site?
I wrote the open source Python library for Epoint, epoint-python-sdk. That meant reading Epoint’s API document line by line and testing every endpoint name against it. Everything below comes from that document and from the library. No guessed field names.
The post has two halves. The first is for the business owner and has no code. The second is for whoever writes the code, possibly also you.
How the payment actually flows
Epoint’s own document describes the flow in five steps. Here they are without the jargon:
- The customer clicks “Pay”. Your server asks Epoint: “I want to take this amount for this order.”
- Epoint answers with a link. The customer follows it to the bank’s payment page.
- The customer types the card details there, on the bank’s page. The card number never touches your site, which is good news, because storing card data is a whole compliance project on its own.
- If the payment works, the customer is sent back to your success page. If not, to your error page.
- The part that matters: Epoint sends the result separately, server to server, to your result address. That message is signed.
One rule falls out of this, and it is the one I would tattoo on every shop owner: a customer landing on your success page proves nothing. The proof is the signed message in step five. A site that does not know the difference will eventually ship an order nobody paid for.
What you need before you start
- A merchant agreement. Epoint issues the keys after it.
- Four addresses. For the merchant setup, the document asks for your website address, the success page (
success_url), the error page (error_url) and the address that receives the result (result_url). - Two keys.
public_keyidentifies the merchant. It looks likei000000001and is not a secret.private_keyis the shared secret. Whoever has it can send requests in your name and forge a “payment succeeded” message. It lives on the server only: not in JavaScript, not in a mobile app, not in git history.
Some features are switched on per merchant by Epoint: Apple Pay and Google Pay, installments, wallets. Ask Epoint whether yours has them before you build on them.
Under the hood: data and signature
Every request to Epoint carries two fields:
data: the parameters as JSON, then base64 encoded.signature:base64(sha1(private_key + data + private_key)).
There is one trap here that nearly everybody falls into once. The SHA-1 result must be the raw 20 bytes, not the hex string. Base64 the hex string and the signature is wrong, and Epoint rejects the request.
In plain Python:
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’s document includes a worked example: for its sample key and sample data, the signature must be a76GNudqblZtV8qF199hctA+cG0=. I ran the library’s sign function against it and got the same value. If you write your own client, make that your first test.
The main payment parameters, as the document lists them:
| Parameter | Required | Meaning |
|---|---|---|
public_key |
yes | merchant id |
amount |
yes | amount, for example 20.50 |
currency |
yes | currency, AZN in the document |
language |
yes | page language: az, en, ru |
order_id |
yes | unique order id in your system, up to 255 characters |
description |
no | description, up to 1000 characters |
success_redirect_url |
no | success page for this request only |
error_redirect_url |
no | error page for this request only |
The request goes by POST to https://epoint.az/api/1/request and the answer contains a redirect_url. There is also a second route: send the customer straight to https://epoint.az/api/1/checkout with an HTML form.
With the SDK: setup
I use the library so I don’t rewrite signing, encoding, error handling and retry rules in every project:
pip install epoint-python-sdk
Keep the keys in environment variables:
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/
One client for the whole project:
from epoint_sdk import Epoint
epoint = Epoint()
If a key is missing, Epoint() raises ConfigurationError straight away. A broken deployment fails when the server starts, not when a customer is halfway through paying.
Starting a payment
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)
Two details here save you a headache later.
First, the order_id is the order number plus an attempt counter: A1042-1, A1042-2. The document requires order_id to be unique. When a card is declined and the customer tries again, you need a new id, and the counter gives you one.
Second, the errors mean different things. NotSentError means the request never reached Epoint, so trying again is safe. OutcomeUnknownError means it was sent but no answer came back. On anything that moves money the library does not retry on its own in that case, because the payment could go through twice. You park the order as “needs check” and ask for its status.
The callback is the only truth
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")
Four protections in a few lines:
- Signature.
verify_callbackcompares the signature in constant time. If it does not match, it raisesSignatureErrorand no field of the request is read. - Matching. A valid signature only proves Epoint sent the message.
tx.matches(...)checks that it is about this order and this amount. - Repeats. The same callback can arrive twice.
select_for_update()locks the row and theorder.state != "paid"check means an order is marked paid exactly once. - CSRF. Epoint’s server has no CSRF token of yours, so the view has to be
csrf_exempt.
Send e-mails, invoices and anything slow after the transaction, in a background job. Answer the callback fast.
The success page is not a confirmation
On the success_url page, do not write “payment received”. Write “confirming your payment” and read the order state from your own database. If the callback has not arrived yet, ask from the server:
tx = epoint.payments.status(order.epoint_transaction)
if tx.paid:
...
status works with Epoint’s transaction id or with your own order id: epoint.payments.status(order_id="A1042-1").
Networks drop things and sometimes a callback never comes. Run a periodic job that finds orders stuck in “pending” and asks Epoint about them. It is the difference between a quiet month and a monthly phone call that starts with “the money left my card but…”.
Giving money back
Full refund:
result = epoint.payments.reverse(order.epoint_transaction)
if result.ok:
order.state = "refunded"
order.save(update_fields=["state"])
For a partial refund, pass the amount as the second argument:
epoint.payments.reverse(order.epoint_transaction, "5.00")
In the document, reverse cancels an earlier payment and accepts a partial amount. There is also a payout (refund-request), which is not tied to any earlier payment and sends money to a saved card. When a customer wants their money back, reverse is the one you want.
Saved cards
Subscriptions, one click checkout and top ups all sit on saved cards. The card stays with Epoint. You only keep a card_id.
Saving the card together with the first payment:
reg = epoint.cards.register_and_pay("9.90", "SUB-1001-1", description="Monthly plan")
user.card_id = reg.card_id
user.save(update_fields=["card_id"])
return redirect(reg.redirect_url)
Next month’s charge, with no page for the customer at all:
tx = epoint.cards.charge(user.card_id, "9.90", "SUB-1001-2", description="Monthly plan, March")
if tx.paid:
extend_subscription(user)
elif tx.failed:
notify_card_declined(user, tx.message)
A declined card does not raise. You get tx.failed with the bank’s code and message inside. Use a fresh order_id for every billing period.
Apple Pay and Google Pay
Epoint offers these through a widget. Check first whether your merchant has them:
methods = epoint.payments.methods()
methods.apple_pay, methods.google_pay
Then create the widget and show it in an iframe:
widget = epoint.widgets.create("19.90", "ORDER-1043", "Pro plan")
The page has to be served with Permissions-Policy: payment=(self "https://epoint.az"). The message the widget posts to the browser is only a hint. Confirm on the server with payments.status(widget.transaction) or the signed callback, same as always.
Testing
Epoint does not publish test cards. To build without a merchant account there is a community project, epoint-sandbox, which copies the gateway API and signs callbacks the same way. Point the SDK’s base_url at it, and switch back to https://epoint.az with real keys when you go live.
For callback tests the library has callback_form, which builds a form signed exactly the way Epoint would sign it:
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)
The mistakes I see most
- Trusting the redirect. The customer came back to
success_url, so the order is marked paid. Anyone can type that address into a browser. - Skipping the signature. Decoding
dataand seeingstatus: successis not enough. Without the check, anyone can post “payment succeeded” to your result address. - Hex digest. Base64 of
sha1(...).hexdigest(). You need the raw bytes from.digest(). - A callback that cannot handle repeats. The same message arrives twice, the customer gets two e-mails and the warehouse ships two boxes.
- Money in
float.19.9and19.90look the same to you, float arithmetic disagrees in strange ways. Store amounts asDecimal. The library rejects things like1.005or a zero amount before anything is sent. - Forgetting the currency. The document lists
AZNas the payment currency. If you need another one, confirm it with Epoint first. - The private key in the frontend. Code that signs in the browser hands the key to everyone who opens dev tools.
- No reconciliation job. When a callback goes missing, the order sits in “pending” forever.
Close those eight and an Epoint integration is not hard. It is just that in payment code, “we’ll fix it later” usually gets fixed at the worst possible moment.
If you want Epoint on your site, or a second pair of eyes on an existing integration, see payment integration or get in touch. For other everyday technical problems in a business: Common technical problems in business.
Sources
-
What is TikSocket, and is there anything like it?
2026-11-16 · 9 min
-
What is DDD, and how do you actually apply it?
2026-11-15 · 16 min
-
Why is my website slow, and how do I fix it?
2026-11-11 · 8 min