Square

Czego potrzebujesz

Dlaczego prosimy o każde pole

Access token

Autoryzuje utworzenie linku do checkoutu, by obciążenie przeszło przez Twoje konto.

Webhook signature key

Dowodzi, że przychodzący webhook naprawdę pochodzi od Square, by nikt nie mógł sfałszować zdarzenia "opłacono". To wartość odrębna od access token.

Location ID

Mówi Square, która lokalizacja otrzymuje pieniądze, i ustala walutę checkoutu. Nie jest tajny.

Success URL i Cancel URL

Zwykłe ustawienia: gdzie trafia kupujący po zapłacie lub rezygnacji. Nie są tajne.

Konfiguracja

1. Otwórz panel Square Developer

   Zaloguj się na developer.squareup.com. Każda aplikacja ma własne poświadczenia, a darmowy Sandbox jest tworzony obok niej do testów. Ten przewodnik prowadzi przez Sandbox; przebieg Live jest identyczny, wystarczy przełączyć przełącznik Sandbox / Production i użyć poświadczeń produkcyjnych. Aby utworzyć nową aplikację, kliknij kafelek + na ekranie Applications.

   ⤢
2. Nazwij swoją aplikację

   Nadaj aplikacji nazwę, którą rozpoznasz (na przykład "Coin Moebius"), a następnie kliknij Next.

   ⤢
3. Skopiuj swój access token

   Otwórz aplikację i przejdź do Credentials. Upewnij się, że przełącznik Sandbox / Production u góry odpowiada środowisku, które konfigurujesz. Kliknij ikonę kopiowania obok Access token i zachowaj go.

   ⤢

   Access token jest tajny, traktuj go jak hasło. Sandbox i Production mają osobne tokeny, więc ich nie mieszaj.

4. Skopiuj swój Location ID

   W menu bocznym otwórz Locations. Skopiuj Location ID lokalizacji, która ma otrzymywać płatności. Ustala on walutę checkoutu, więc wybierz tę, której walutą chcesz obciążać.

   ⤢
5. Otwórz Webhooks → Subscriptions

   Square nazywa endpoint webhooka "subskrypcją". W menu bocznym rozwiń Webhooks, otwórz Subscriptions i kliknij Add subscription.

   ⤢
6. Dodaj subskrypcję i wybierz zdarzenia

   Nadaj jej nazwę (np. "coin-moebius"). W Notification URL wklej adres webhooka Square Twojego projektu (poniżej). Następnie w sekcji Events wyszukaj i zaznacz zdarzenia, których Coin Moebius nasłuchuje, i kliknij Save.

   • Płatności jednorazowe: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
   • Subskrypcje (tylko jeśli je sprzedajesz): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Jeśli nie rozliczasz cyklicznie, pomiń je.

   https://api.coinmoebius.com/webhook/square/<your project id>

   ⤢

   Identyfikator Twojego projektu znajduje się pod nazwą projektu w panelu Coin Moebius; wstaw go do powyższego adresu. Dodatkowe zdarzenia są nieszkodliwe, ignorujemy wszystko, czego nie używamy. Karta podłączonego dostawcy (ostatni krok) pokazuje ten sam adres URL w celach informacyjnych.

7. Otwórz właśnie utworzoną subskrypcję

   Square zapisuje subskrypcję i wyświetla ją pod Webhooks ze statusem Enabled. Kliknij jej nazwę, by otworzyć panel szczegółów, gdzie znajduje się klucz podpisywania.

   ⤢
8. Skopiuj Signature key

   W panelu Properties subskrypcji kliknij ikonę kopiowania obok Signature key. To wartość, której Coin Moebius używa do potwierdzenia, że każdy webhook naprawdę pochodzi od Square. Istnieje dopiero po utworzeniu subskrypcji, dlatego krok z webhookiem wyprzedza krok podłączenia.

   ⤢
9. W Coin Moebius: Add provider → Square

   W swoim projekcie otwórz zakładkę Providers, kliknij Add provider, wybierz Connect a service i wybierz Square. Ustaw Success URL i Cancel URL. Na zakładce Live wklej Access token, Webhook signature key i Location ID, a następnie kliknij Save. Konfigurujesz najpierw z poświadczeniami sandbox? Wklej je na zakładce Test, a poświadczenia live dodaj później przez Edit.

   ⤢
10. Jesteś podłączony

    Square pojawia się teraz na zakładce Providers z datą podłączenia. Karta pokazuje ten sam adres URL webhooka, który wkleiłeś do Square, oraz przyciski Edit i Disconnect. Użyj przełącznika Test mode, by przeprowadzić zamówienie sandbox od początku do końca przed wejściem na żywo.

    ⤢

    Karty sandbox nigdy nie obciążają prawdziwej karty. Użyj karty 4111 1111 1111 1111, CVV 111, dowolnej przyszłej daty ważności, dowolnego prawidłowego kodu pocztowego (na przykład 94103).

Po podłączeniu

Wykonaj jedną płatność testową przed wejściem na żywo:

1. Utwórz produkt i ustaw jego Environment na Testing. To uruchamia produkt na Twoich poświadczeniach sandbox, więc możesz złożyć pełne zamówienie bez przepływu pieniędzy. (Jeśli pominąłeś zestaw sandbox, produkt Testing wraca do live, więc najpierw go dodaj.)
2. Umieść przycisk kupna na stronie (wystarczy lokalny plik HTML) wskazującej na Twój projekt.
3. Dokończ checkout testową kartą sandbox z powyższej listy.
4. Otwórz zakładkę Transactions. Pojawi się nowy wiersz z etykietą Testing. Gdy jego status osiągnie succeeded, Twoje poświadczenia i webhook działają od początku do końca.

Przełącz Environment produktu na Live, gdy będziesz gotowy na prawdziwe płatności.

Rozwiązywanie problemów

Zacznij od Verify. W panelu kliknij Verify (lub Verify test credentials), by sprawdzić access token i lokalizację.

Verify się nie udaje.

Skopiuj ponownie access token i Location ID. Production i Sandbox mają osobne tokeny, więc ich nie mieszaj.

Weryfikacja podpisu się nie udaje albo zamówienie pozostaje pending.

Square podpisuje dokładny notification URL plus treść. URL, który rejestrujesz w Square, musi pasować do Twojego adresu URL webhooka znak po znaku, bez końcowego ukośnika i bez dodatkowego ciągu zapytania. Następnie skopiuj ponownie signature key z tego samego endpointu.

Potwierdź od początku do końca.

Square Developer Console → Webhooks → Twoja subskrypcja → Send Test Event, a potem obserwuj aktualizację zamówienia.

Warto wiedzieć

Waluta zależy od lokalizacji. Checkout obciąża w walucie lokalizacji, której id podajesz.

Rotacja sekretów. Zmieniaj access token lub signature key kiedy chcesz, a potem wklej nową wartość. Pola tajne pozostają puste przy edycji.

Pytania? Join our Discord