README

پکیج PHP برای اتصال به سرویسهای پرداخت دیجیپی UPG

نصب

composer require ebrahimsalahi/digipay-php

پیکربندی

use EbrahimSalahi\DigiPay\DigiPay;
use EbrahimSalahi\DigiPay\DigiPayConfig;

$config = new DigiPayConfig(
    username: 'merchant-username',
    password: 'merchant-password',
    clientId: 'client-id',
    clientSecret: 'client-secret',
);

$sdk = new DigiPay($config);

مقادیر لازم

• username
• password
• clientId
• clientSecret

خواندن از env

use EbrahimSalahi\DigiPay\DigiPayConfig;

$config = DigiPayConfig::fromEnv(
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret'
);

این متد فقط این دو متغیر محیطی را بررسی می‌کند:

• DIGIPAY_USERNAME
• DIGIPAY_PASSWORD

clientId و clientSecret باید هنگام ساخت config به‌صورت صریح داده شوند.

محیط تست و عملیاتی

• Sandbox URL: https://uat.mydigipay.info/digipay/api
• Production URL: https://api.mydigipay.com/digipay/api

دریافت توکن / login example

$token = $sdk->login();

ساخت تیکت ساده خرید

use EbrahimSalahi\DigiPay\Enums\PreferredGateway;

$response = $sdk->createSimpleTicket(
    amount: 150000,
    cellNumber: '09120000000',
    providerId: 'ORDER-1001',
    callbackUrl: 'https://example.com/digipay/callback',
    preferredGateway: PreferredGateway::WALLET
);
header('Location: ' . $response->redirectUrl());
exit;

دریافت callback

$callback = $sdk->parseCallback($_POST);

$callback->assertMatchesOrder(
    expectedAmount: 150000,
    expectedProviderId: 'ORDER-1001'
);

تایید پرداخت

use EbrahimSalahi\DigiPay\Enums\TicketType;

$verify = $sdk->verify(
    trackingCode: $callback->trackingCode,
    providerId: $callback->providerId,
    type: TicketType::WALLET
);

قبل از verify باید amount و providerId برگشتی از دیجیپی با سفارش داخلی سیستم مقایسه شود.

بازگشت دستی / reverse

use EbrahimSalahi\DigiPay\Enums\TicketType;

$reverse = $sdk->reverse(
    purchaseTrackingCode: $callback->trackingCode,
    providerId: $callback->providerId,
    type: TicketType::IPG
);

طبق مستندات رسمی، بازگشت دستی فقط برای خریدهای IPG/DPG مجاز است و این SDK هم همین محدودیت را اعمال می‌کند.

تحویل خرید

use EbrahimSalahi\DigiPay\Enums\TicketType;

$deliver = $sdk->deliver(
    deliveryDate: 1592502763000,
    invoiceNumber: '7471288365484',
    trackingCode: '5239470511667728782510',
    products: ['product-4', 'product-5'],
    type: TicketType::CREDIT
);

این سرویس فقط برای CREDIT و BNPL استفاده می‌شود.

بازگشت خرید / refund

use EbrahimSalahi\DigiPay\Enums\TicketType;

$refund = $sdk->refund(
    providerId: 'REFUND-1',
    amount: 150000,
    saleTrackingCode: '5239470511667728782510',
    type: TicketType::WALLET
);

پیگیری refund

use EbrahimSalahi\DigiPay\Enums\TicketType;

$inquiry = $sdk->refundInquiry(
    inquiryId: 'REFUND-1',
    type: TicketType::WALLET
);

هندل خطاها

use EbrahimSalahi\DigiPay\Exceptions\AuthenticationException;
use EbrahimSalahi\DigiPay\Exceptions\ValidationException;
use EbrahimSalahi\DigiPay\Exceptions\BusinessException;
use EbrahimSalahi\DigiPay\Exceptions\ApiException;

try {
    $sdk->login();
} catch (AuthenticationException $e) {
    // احراز هویت
} catch (ValidationException $e) {
    // ورودی نامعتبر
} catch (BusinessException $e) {
    echo $e->getBusinessCode();
    echo $e->getBusinessMessageFa();
    echo $e->isRetryable() ? 'retry' : 'stop';
} catch (ApiException $e) {
    // خطای سرویس
}

ذخیره توکن

• InMemoryTokenStore: مناسب اجرای موقت
• FileTokenStore: مناسب ذخیره محلی با قفل فایل

نکات امنیتی:

• رمز عبور و clientSecret ذخیره نمی‌شوند
• توکن‌ها نباید در لاگ چاپ شوند
• فایل توکن را در مسیر امن نگه دارید

خطاها

جزئیات خطاها و کدهای خطای دیجی‌پی فقط در فایل مرجع زیر آمده است:

docs/digipay-upg-reference.fa.md

اجرای تست‌ها

composer test

یا:

vendor/bin/phpunit

تناقض‌های مستندات

• Digipay-Version در بعضی جدول‌ها با فرمت دیگری نوشته شده، اما نمونه‌های عملی 2022-02-02 را نشان می‌دهند. این SDK مقدار پیش‌فرض را روی 2022-02-02 گذاشته و قابل تنظیم است.
• نمونه JSON بخش refund در مستندات رسمی معیوب است.
• در reverse، trackingCode و purchaseTrackingCode هر دو دیده می‌شوند. این SDK از purchaseTrackingCode استفاده می‌کند.

مستندات رسمی دیجیپی

https://www.mydigipay.com/developers/docs/upg/?php#1