Rozwój API

PHP SDK na Packagist

Zainstaluj PHP SDK za pomocą Kompozytora.

Utwórz i zapytanie o zlecenia płatnicze ze strony PHP. Zachowaj referencje API na serwerze.

v1.0.2 · PHP 7.4+ · MIT

composer require mochipay/php-sdk:^1.0

Darmowe pliki do pobrania. Prenumerata płatności na żywo.

Wybierz pakiet źródłowy aplikacji

Jeden obecny ZIP na język lub platformę mobilną. Włączone są angielskie instrukcje konfiguracji. Wtyczki do sklepu natywnego pozostają osobne, a istniejące integracje nadal działają.

Uruchom kompletny przepływ oparcia

1. Konfiguracja prywatnych pełnomocnictw MochiPay, aktywnych portfeli, publicznego HTTPS wywołania pochodzenia i niezależnego znacznika dostępu. Serwer posiada cenę demo; przeglądarka nie może jej zastąpić.
2. Utwórz lub odzyskaj, korzystając z tego samego zapisanego request_id i niezmienionego ładunku. Dokładne bajty żądań UTF-8 i zakodowane ciągi zapytań są podpisane HMAC-SHA256.
3. Otwórz zapisane wyskakujące okienko ON_SITE lub przekierowanie HPP. Obydwa korzystają z jednego zlecenia płatniczego. ON_SITE zawiera kod QR, kontrolę kopiowania i selektor dziesięciu języków.
4. Przetwórz notify_url na serwerze i ponownie zapytaj o zapisany identyfikator. Synchroniczne trasy zwrotne i odpytujące ponownie korzystają z tej samej weryfikacji binding/exact-amount.
5. Zapis zweryfikowanego opłacanego państwa raz. Zastąp magazyn i marker plików do instalacji z uwierzytelnioną własnością aplikacji i atomową aktualizacją zamówienia bazy danych przed produkcją.

PHP zachowuje pierwotny przepływ order.php / checkout.php / callback.php. Cztery nowe tła ujawniają wspólne trasy poniżej dla przeglądarki i klientów mobilnych.

Mobile checkout bez mobilnych tajemnic API

Projekty źródłowe Swift i Kotlin korzystają z jednego z czterech popularnych backendów. Skonfiguruj w aplikacji tylko pochodzenie sprzedawcy HTTPS. ON_SITE pokazuje Twoją lokalną kasę w WKWebView lub Android WebView; HPP otwiera trasę przekierowania sprzedawcy w zewnętrznej przeglądarce. Aplikacja ponownie sprawdza backend, jeśli jest aktywny; zamknięcie aplikacji nigdy nie powoduje zatrzymania powiadomień serwera.

Zapisane żądanie ID przetrwa ponownie / ponownie uruchamia. Interfejs i zmiany językowe ponownego użycia tej samej kolejności. Token dostępu do instalacji jest oddzielony od referencji MochiPay; należy go zastąpić uwierzytelnioną sesją użytkownika aplikacji.

Są to demo źródła integracji, a nie rodzime płatności SDK lub app- store aprobaty. Aktualny przegląd Zasady rozliczania Apple 'a oraz Polityka płatności Google Play dla produktu i regionu docelowego.

Weryfikacja przed przejściem na żywo

Użyj każdego opakowania README i TESTING.md. Lokalne podpisane urządzenia obejmują ponowne próby, wiążące rozbieżności, niezapłacone stany i duplikaty powiadomień. Native Xcode / Android Studio akceptacja urządzenia i małe prawdziwe płatności nadal potrzebują aprobatę. Nie jest wymagana nowa tabela bazy danych MochiPay ani ponowne zainstalowanie wtyczki.

Trzy wejścia. Jedna zweryfikowana aktualizacja zamówienia.

HPP: synchroniczny powrót przeglądarki

Podczas tworzenia płatności zapisz redirect_url z możliwością zamówienia lokalnego. Przykład ustawia go na Twojego sprzedawcę HTTPS /complete?r=…&t=…. Po zrealizowaniu transakcji hostowanej przeglądarka powraca tutaj. Załaduj zapisane zamówienie lokalne, zatwierdź jego własność/uprawnienia dostępu, a następnie podpisz Zamówienie zapytania, używając zapisanego MochiPay order_id.

Wyświetla PAID tylko po zakończeniu połączenia i dokładnie otrzymanej kwoty przejść. W przeciwnym razie pokaż czekanie lub recenzję. Flaga URL, wiadomość przeglądarki lub screenshot nie jest dowodem zapłaty. Dostawa Callback może wystąpić przed lub po tej wizycie przeglądarki.

HPP i ON_SITE: asynchroniczne powiadomienie serwera

Zapisz notify_url podczas tworzenia; w przykładach użyto /callback?r=…&t=…. MochiPay wysyła tutaj POSTy niezależnie od przeglądarki klienta. Traktuj przychodzące pola jako niezaufane wskazówki wyszukiwania. Zapytaj uwierzytelniony interfejs API i porównaj zapisany identyfikator, numer referencyjny, pierwotną kwotę/walutę, zasób/sieć, adres i dokładną kwotę do zapłaty.

Wymagaj PAID, dodatnich oczekiwanych/otrzymanych kwot i dokładnej równości lub ścisłej wartości logicznej manual_payment_accepted=true z tego uwierzytelnionego zapytania. Jednorazowo zarejestruj zweryfikowaną płatność lokalną; powtarzane zweryfikowane powiadomienia zwracają OK bez dwukrotnej aktualizacji lub dostarczania. Niepotwierdzone stany, nieprawidłowe powiązania i awarie przesyłania/magazynowania nie mogą być uznawane za pomyślną płatność.

W wersjach demonstracyjnych utrzymuje się jednorazowy znacznik paid_verified. Zastąp ją transakcją we własnej bazie zamówień; nie spełnia dóbr. Sama treść wywołania zwrotnego nigdy nie powoduje aktualizacji zamówienia.

ON_SITE: aktualizacje asynchroniczne i odpytywanie wyskakujących okienek

ON_SITE ustawia to samo notify_url, więc weryfikacja płatności będzie kontynuowana po zamknięciu wyskakującego okienka lub aplikacji w trybie offline. Wyskakujące okienko odpytuje tylko Twój uwierzytelniony backend w odstępach 15-sekundowych, gdy jest widoczne. Jego backend wysyła zapytanie do MochiPay i zwraca DTO małej płatności z kwotami w postaci ciągu dziesiętnego. Wyświetlacz PAID wykorzystuje ten sam weryfikator co wywołanie zwrotne; do przeglądarki nie zostanie wprowadzona żadna tajemnica API ani pełna odpowiedź klienta.

Zamknięcie, ponowne otwarcie lub zmiana ON_SITE/HPP powoduje ponowne wykorzystanie jednej zapisanej płatności. Zachowaj request_id i dokładny ładunek tworzenia po przekroczeniu limitu czasu; zmiana referencji może spowodować niechciane dodatkowe zamówienie.

Kod dostępny w każdym pakiecie

Każdy przykład obejmuje obie gałęzie prezentacji, procedurę obsługi powiadomień, stronę zwrotną, punkt końcowy stanu bezpiecznego i trwałą próbę etapową. Pola API to notify_url i redirect_url; tryb realizacji transakcji to preferencja lokalna, a nie pole Utwórz zamówienie.

async function verify(r,t){const a=load(r);if(!equal(a.token,t)||!a.snapshot)throw Error('Invalid payment capability');const d=await api('/api/v1/orders/query','order_id='+encodeURIComponent(a.snapshot.order_id));bind(a,d);if(d.status==='PAID'&&!a.paid_verified){a.paid_verified=true;save(r,a)}return d}

// HPP redirect_url -> GET /complete: verify before displaying result.
await verify(r,t);
// notify_url -> POST /callback: same verification and atomic once-only marker.
const d=await verify(r,t);
output(res,d.status==='PAID'?200:409,'text/plain',d.status==='PAID'?'OK':'Payment not confirmed');
// ON_SITE polling -> GET /status: only the safe DTO reaches the browser.
json(res,200,{success:true,data:safe(await verify(r,t))});

def verify(r, t):
    a = load(r)
    if not isinstance(t,str) or not hmac.compare_digest(a['token'],t) or not a.get('snapshot'): raise ValueError('Invalid capability')
    d = api('/api/v1/orders/query',urlencode({'order_id':a['snapshot']['order_id']})); bind(a,d)
    if d.get('status') == 'PAID' and not a['paid_verified']: a['paid_verified'] = True; save(r,a)
    return d

# HPP browser return
verify(r,t)
# HPP and ON_SITE server notification (inside the handler lock)
d = verify(r,t)
self.out(200 if d['status']=='PAID' else 409,'text/plain','OK' if d['status']=='PAID' else 'Payment not confirmed')
# ON_SITE display only
self.jout(200,dict(success=True,data=safe(verify(r,t))))

        static JObject Verify(string r,string t)
        {
            var a=Load(r);if(!Equal(S(a,"token"),t)||a["snapshot"]==null)throw new Exception("Invalid capability");var d=Api("/api/v1/orders/query",null,"order_id="+Uri.EscapeDataString(S(a["snapshot"],"order_id")));Bind(a,d);
            if(S(d,"status")=="PAID"&&!(bool)a["paid_verified"]){a["paid_verified"]=true;Save(r,a);}return d;
        }

// GET /complete: verified HPP return.
Verify(r,t);
// POST /callback: asynchronous notification for both modes.
var d=Verify(r,t);
Out(res,S(d,"status")=="PAID"?200:409,"text/plain",S(d,"status")=="PAID"?"OK":"Payment not confirmed");
// GET /status: display only the minimal DTO.
JOut(res,200,new JObject {{"success",true},{"data",Safe(Verify(r,t))}});

    static JsonObject verify(String r,String t)throws Exception{JsonObject a=load(r);if(!equal(s(a,"token"),t)||!a.has("snapshot"))throw new IllegalArgumentException("Invalid capability");JsonObject d=api("/api/v1/orders/query",null,"order_id="+enc(s(a.getAsJsonObject("snapshot"),"order_id")));bind(a,d);if(s(d,"status").equals("PAID")&&!a.get("paid_verified").getAsBoolean()){a.addProperty("paid_verified",true);save(r,a);}return d;}

// GET /complete: verified HPP return.
verify(r,t);
// POST /callback: both presentation modes use this route.
boolean paid=s(verify(r,t),"status").equals("PAID");
out(x,paid?200:409,"text/plain",paid?"OK":"Payment not confirmed");
// GET /status: minimal safe display DTO.
jout(x,200,object("success",true,"data",safe(verify(r,t))));

    // Authenticate the result by querying MochiPay server-to-server.
    $verified = mochipay_query_order('order_id', $orderId);
    if (!$verified['ok'] || !is_array($verified['data'])) {
        callback_text(503, 'VERIFICATION_FAILED');
    }

    $order = $verified['data'];
    if (!isset($order['order_id']) || !hash_equals((string) $order['order_id'], $orderId)) {
        callback_text(409, 'ORDER_MISMATCH');
    }

    $verifiedMerchantId = isset($order['merchant_order_id']) ? (string)$order['merchant_order_id'] : '';
    try { $record = mochipay_load($verifiedMerchantId); }
    catch (Exception $e) { callback_text(503, 'LOCAL_STORAGE_UNAVAILABLE'); }
    if (!mochipay_bound($record, $order) || (isset($callback['merchant_order_id']) && !hash_equals($verifiedMerchantId, (string)$callback['merchant_order_id']))) callback_text(409, 'LOCAL_ORDER_MISMATCH');
    if (!MochiPayPortable::paidAmountAccepted($order)) callback_text(409, 'PAYMENT_AMOUNT_REQUIRES_REVIEW');

    if (!isset($order['status']) || strtoupper((string) $order['status']) !== 'PAID') {
        callback_text(409, 'ORDER_NOT_PAID');
    }

    /*
     * TODO: In your production database, atomically fulfill the bound local order.
     * This demo acknowledges verification only; it does not deliver goods.
     * Make the operation idempotent: repeated callbacks must not deliver goods
     * or credit the customer more than once.
     */
    try { mochipay_record_verified($record, $order); }
    catch (Exception $e) { callback_text(503, 'LOCAL_UPDATE_FAILED'); }
    callback_text(200, 'OK');
}

// GET browser return verifies the saved capability, then queries the saved ID.
$authorized = $record && $returnToken !== '' && hash_equals($record['token'], $returnToken);
if ($authorized) {
    $verified = mochipay_query_order('order_id', $record['snapshot']['order_id']);
    $paid = $verified['ok'] && mochipay_record_verified($record, $verified['data']);
}