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

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:

  1. The customer clicks “Pay”. Your server asks Epoint: “I want to take this amount for this order.”
  2. Epoint answers with a link. The customer follows it to the bank’s payment page.
  3. 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.
  4. If the payment works, the customer is sent back to your success page. If not, to your error page.
  5. 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_key identifies the merchant. It looks like i000000001 and is not a secret. private_key is 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_callback compares the signature in constant time. If it does not match, it raises SignatureError and 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 the order.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

  1. Trusting the redirect. The customer came back to success_url, so the order is marked paid. Anyone can type that address into a browser.
  2. Skipping the signature. Decoding data and seeing status: success is not enough. Without the check, anyone can post “payment succeeded” to your result address.
  3. Hex digest. Base64 of sha1(...).hexdigest(). You need the raw bytes from .digest().
  4. A callback that cannot handle repeats. The same message arrives twice, the customer gets two e-mails and the warehouse ships two boxes.
  5. Money in float. 19.9 and 19.90 look the same to you, float arithmetic disagrees in strange ways. Store amounts as Decimal. The library rejects things like 1.005 or a zero amount before anything is sent.
  6. Forgetting the currency. The document lists AZN as the payment currency. If you need another one, confirm it with Epoint first.
  7. The private key in the frontend. Code that signs in the browser hands the key to everyone who opens dev tools.
  8. 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

related