EPoint¶

Rəsmi Dokumentasiya (v1.0.3)¶

Azərbaycanca

İngliscə

Rusca

Markdown versiyaları (bu saytda):

• EPoint API (v1.0.3)
• Apple Pay & Google Pay (JS SDK)

Sürətli başlanğıc¶

Ödəniş yaratmaq, müştərini ödəniş səhifəsinə yönləndirmək və statusu yoxlamaq:

from integrify.epoint import EPointRequest

# 1. Ödəniş yaradın
resp = EPointRequest.pay(
    amount=10,
    currency='AZN',
    order_id='order-1',
    description='Sifariş #1',
)

if resp.ok:
    # 2. Müştərini EPoint ödəniş səhifəsinə yönləndirin
    print(resp.body.redirect_url)

    # 3. Nəticə callback-ə gəlir; istənilən vaxt statusu özünüz də yoxlaya bilərsiniz
    status = EPointRequest.get_transaction_status(transaction_id=resp.body.transaction)
    print(status.body.status)  # new, success, returned, error, server_error
else:
    print(resp.body.message)

Asinxron istifadə üçün EPointAsyncRequest import edib, eyni metodları await ilə çağırın.

Sorğular listi¶

Sorğu metodu	Məqsəd	EPoint API	Callback-ə sorğu atılır
pay	Ödəniş	/api/1/request
get_transaction_status	Ödəniş statusunun yoxlanılması	/api/1/get-status
save_card	Ödəniş olmadan kartı yadda saxlamaq	/api/1/card-registration
pay_with_saved_card	Saxlanılan kartla ödəniş	/api/1/execute-pay
pay_and_save_card	Ödəniş etmə və kartı yadda saxlamaq	/api/1/card-registration-with-pay
payout	Vəsaitlərin köçürülməsi	/api/1/refund-request
refund	Ödənişi tam və ya yarımçıq geri qaytarma	/api/1/reverse
split_pay	Ödənişi başqa EPoint istifadəçisi ilə bölüb ödəmə	/api/1/split-request
split_pay_with_saved_card	Saxlanılmış kartla ödənişi başqa EPoint istifadəçisi ilə bölüb ödəmə	/api/1/split-execute-pay
split_pay_and_save_card	Ödənişi başqa EPoint istifadəçisi ilə bölüb ödəmə və kartı saxlamaq	/api/1/split-card-registration-with-pay
create_widget	Apple Pay/Google Pay widget-i yaratmaq	/api/1/token/widget
create_token_payment	Apple Pay/Google Pay üçün token ödənişi yaratmaq	/api/1/token/payment
apple_pay_session	Apple Pay session-u almaq	/api/1/token/apple/session
apple_pay	Apple Pay ilə ödənişi tamamlamaq	/api/1/token/apple/pay
google_pay	Google Pay ilə ödənişi tamamlamaq	/api/1/token/google/pay

Apple Pay & Google Pay¶

Apple Pay və Google Pay-i iki yolla qoşmaq olar:

Widget¶

from integrify.epoint import EPointRequest

resp = EPointRequest.create_widget(amount=2.5, order_id='12345678', description='Ödəniş')
widget_url = resp.body.widget_url  # frontend-ə ötürün

widget_url-i saytda iframe, mobil tətbiqdə isə webview daxilində açın. Ödəniş bitdikdən sonra widget səhifəyə message event-i göndərir:

<iframe src="{{ widget_url }}" allow="payment"></iframe>

<script>
  window.addEventListener('message', function (event) {
    console.log(event.data); // {status: 'success', payment: {...}}
  });
</script>

Qeyd

event.data brauzerdən gəldiyi üçün ona tam güvənməyin: ödənişin nəticəsini backend-də get_transaction_status ilə yoxlayın.

JS SDK¶

Bu üsulda düymələr EPoint-in JS SDK-sı (epoint-token-pay) vasitəsilə göstərilir. Axın belədir:

1. Backend: create_token_payment ilə EPoint-də token ödənişi yaradın.
2. Frontend: SDK-nı qoşun, düymələri əlavə edin və initTokenPay-i 1-ci addımda gələn ödənişlə çağırın.
3. Apple Pay: SDK sizin session endpoint-inizə müraciət edir → apple_pay_session.
4. Ödəniş: İstifadəçi ödənişi təsdiqlədikdən sonra SDK pay endpoint-inizə id, token və billingContact göndərir → apple_pay / google_pay.

Session və pay endpoint-ləri EPoint-dən gələn cavabı olduğu kimi (resp.body) qaytarmalıdır.

Frontend¶

<script src="https://epoint.az/js/epoint-token-pay.min.js"></script>

<google-pay-button type="pay" color="white"></google-pay-button>
<apple-pay-button type="pay" color="black"></apple-pay-button>

<script>
  initTokenPay({
    payment: { id: 9998887, amount: '2.50' },  // create_token_payment cavabından
    endpoints: {
      apple: { session: '/epoint/apple/session', pay: '/epoint/apple' },
      google: { pay: '/epoint/google' },
    },
    onError: function (error) { console.log({ error }) },
    onSuccess: function (success) { console.log({ success }) },
  });
</script>

Backend (FastAPI nümunəsi)¶

from fastapi import APIRouter, Request
from integrify.epoint import EPointAsyncRequest

router = APIRouter(prefix='/epoint')


@router.post('/apple/session')
async def apple_session(request: Request):
    resp = await EPointAsyncRequest.apple_pay_session(origin=request.headers['origin'])
    return resp.body


@router.post('/apple')
async def apple_pay(request: Request):
    body = await request.json()
    resp = await EPointAsyncRequest.apple_pay(
        payment_id=body['id'],
        token=body['token'],
        billing_contact=body.get('billingContact'),
    )
    return resp.body.model_dump()


@router.post('/google')
async def google_pay(request: Request):
    body = await request.json()
    resp = await EPointAsyncRequest.google_pay(
        payment_id=body['id'],
        token=body['token'],
        billing_contact=body.get('billingContact'),
    )
    return resp.body.model_dump()

Qeyd

apple_pay/google_pay sorğularının cavabında redirect_url gələ bilər (məs., 3DS üçün) — SDK bunu özü idarə edir. Uğurlu ödənişdən sonra statusu get_transaction_status ilə də yoxlaya bilərsiniz.

Callback Sorğusu¶

Bəzi sorğular müştəri məlumat daxil etdikdən və arxa fonda bank işləmləri bitdikdən sonra, tranzaksiya haqqında məlumat sizin EPoint dashboard-da qeyd etdiyiniz callback URL-ə POST sorğusu göndərilir. Data siz adətən sorğu göndərdiyiniz formatda gəlir:

{
    'data': 'base64data'
    'signature': 'sha1signature'
}

Bu data-nı signature-ni yoxladıqdan sonra, decode etmək lazımdır. Callback üçün API yazdıqda, datanı alıb, helpers.py-dakı decode_callback_data funksiyası ilə həm signature yoxlanması həm də datanın decode-unu edə bilərsiniz. Bu funksiya sizə DecodedCallbackDataSchema formatında decode olunmuş datanı qaytarır.

Qeyd

FastAPI istifadəçiləri kiçik "shortcut"-dan istifadə edə bilərlər:

from fastapi import Fastapi, APIRouter, Depends
from integrify.epoint.schemas.callback import DecodedCallbackDataSchema
from integrify.epoint.helpers import decode_callback_data

router = APIRouter()

@router.post('/epoint/callback')
async def epoint_callback(data: DecodedCallbackDataSchema = Depends(decode_callback_data)):
   ...

Funksiyanı belə yazdıqda, data avtomatik signature-i yoxlanaraq decode edilir.

Callback Data formatı¶

Nə sorğu göndərməyinizdən asılı olaraq, callback-ə gələn data biraz fərqlənə bilər. DecodedCallbackDataSchema bütün bu dataları özündə cəmləsə də, hansı fieldlərin gəlməyəcəyini (yəni, decode-dan sonra None olacağını) bilmək yaxşı olar. Ümumilikdə, mümkün olacaq datalar bunlardır:

Sorğudan asılı olaraq, bu data-lar callback-də GƏLMİR (yəni, avtomatik None dəyəri alır):

Qeyd

Qalan bütün data-lar sorğu success olduqda gəlir, əks halda, onlar da None dəyəri alır.