Dokumentacja API

Odniesienie

Trasy, modele obiektów, wyliczenia, ustawienia i kształty błędów.

Odniesienie do trasy

Metoda	Trasa
GET	`/api/partner/v1/companies`
Autoryzacja Sesja Zastosowanie Lista firm użytkownika Zwraca zespoły dostępne dla narzędzi portalu zalogowanego użytkownika MakeCrypto.
POST	`/api/partner/v1/onboarding/company`
Autoryzacja Sekret onboardingu partnera Zastosowanie Utwórz link onboardingu firmy Tworzy wstępnie wypełniony przez partnera szkic onboardingu i zwraca adres URL do przejęcia przez sprzedawcę.
GET	`/api/partner/v1/makepay/payment-links`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl lub utwórz linki płatnicze Odczytuje linki płatnicze firmy przypisanej do klucza API albo tworzy hostowane linki checkout MakePay.
POST	`/api/partner/v1/makepay/payment-links`
Autoryzacja Klucz MakePay API albo publiczne Zastosowanie Wyświetl lub utwórz linki płatnicze Odczytuje linki płatnicze firmy przypisanej do klucza API albo tworzy hostowane linki checkout MakePay.
POST	`/gateway/pay/{makepayKeyId}`
Autoryzacja Publiczny klucz formularza Zastosowanie Wyślij formularz płatności HTML Przyjmuje pola formularza z przeglądarki, tworzy hostowany link płatniczy i przekierowuje kupującego do checkout.
GET	`/api/partner/v1/makepay/payment-links/{uid}`
Autoryzacja Klucz MakePay API Zastosowanie Odczytaj lub zaktualizuj link płatniczy Odczytuje szczegóły linku płatniczego albo zmienia jego status na active, paused lub archived.
PATCH	`/api/partner/v1/makepay/payment-links/{uid}`
Autoryzacja Klucz MakePay API Zastosowanie Odczytaj lub zaktualizuj link płatniczy Odczytuje szczegóły linku płatniczego albo zmienia jego status na active, paused lub archived.
POST	`/api/partner/v1/makepay/payment-links/{uid}/send-request-email`
Autoryzacja Klucz MakePay API Zastosowanie Wyślij żądanie płatności Wysyła lub ponownie wysyła hostowany link na adres e-mail klienta.
GET	`/api/partner/v1/makepay/subscriptions`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl lub utwórz subskrypcje Zwraca cykliczne plany subskrypcji MakePay albo tworzy subskrypcję i pierwszą fakturę.
POST	`/api/partner/v1/makepay/subscriptions`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl lub utwórz subskrypcje Zwraca cykliczne plany subskrypcji MakePay albo tworzy subskrypcję i pierwszą fakturę.
GET	`/api/partner/v1/makepay/customers`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl lub zaktualizuj klientów Zwraca profile klientów MakePay albo tworzy/aktualizuje klientów po adresie e-mail.
POST	`/api/partner/v1/makepay/customers`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl lub zaktualizuj klientów Zwraca profile klientów MakePay albo tworzy/aktualizuje klientów po adresie e-mail.
POST	`/api/partner/v1/makepay/customers/{customerId}/portal`
Autoryzacja Klucz MakePay API Zastosowanie Utwórz link do portalu klienta Generuje na żądanie podpisany adres URL portalu klienta MakePay ważny przez 24 godziny.
GET	`/api/partner/v1/timezones`
Autoryzacja Publiczne Zastosowanie Wyświetl strefy czasowe Zwraca obsługiwane identyfikatory stref czasowych IANA.
GET	`/api/partner/v1/makepay/settings`
Autoryzacja Klucz MakePay API Zastosowanie Odczytaj lub zaktualizuj ustawienia MakePay Odczytuje lub aktualizuje ustawienia rozliczeń, przekierowań, opłat i obsługi niedopłat.
PUT	`/api/partner/v1/makepay/settings`
Autoryzacja Klucz MakePay API Zastosowanie Odczytaj lub zaktualizuj ustawienia MakePay Odczytuje lub aktualizuje ustawienia rozliczeń, przekierowań, opłat i obsługi niedopłat.
GET	`/api/partner/v1/makepay/destination-assets`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl aktywa docelowe Zwraca obsługiwane aktywa rozliczeniowe i bieżące aktywo domyślne.
GET	`/api/partner/v1/makepay/webhook-requests`
Autoryzacja Klucz MakePay API Zastosowanie Wyświetl dostarczenia webhooków Pokazuje próby dostarczenia webhooków płatności i subskrypcji wraz ze statusem ponowienia.

Wdrażanie partnera OAuth

POST /api/partner/v1/onboarding/company może zawierać opcjonalny oauth obiekt. MakeCrypto sprawdza aplikację OAuth, URI przekierowania, zakresy i PKCE wyzwanie przed utworzeniem linku wprowadzającego. Kiedy kupiec zakończy onboarding, MakeCrypto tworzy firmę, przyznaje dostęp do niej aplikacji OAuth firmy i przekierowuje do zarejestrowanego redirectUri z autoryzacją code.

{
  "idempotencyKey": "merchant_123",
  "company": {
    "name": "Acme Markets",
    "website": "https://acme.example"
  },
  "oauth": {
    "clientId": "mco_app_example",
    "redirectUri": "https://apps.makecrypto.io/oauth/callback",
    "scope": "company:read makepay:payment-links:write makepay:settings:read",
    "state": "merchant_123",
    "codeChallenge": "PKCE_S256_CODE_CHALLENGE",
    "codeChallengeMethod": "S256"
  }
}

Aplikacja partnerska powinna zachować pasującą PKCE code_verifier i wymienić zwrócił kod poprzez POST /oauth/token.

Obiekt PaymentLink

Pole	Typ	Notatki
`id`	`string`	Wewnętrzny identyfikator UUID.
`uid`	`string`	Publiczny identyfikator łącza płatniczego używany w hostowanych i osadzonych trasach checkout.
`status`	`"active" \| "paused" \| "archived"`	Stan łącza zarządzanego przez sprzedawcę.
`payload`	`PaymentLinkPayload`	Pola zamówienia sprzedawcy, kwoty, klienta, przekierowania, metadanych, marki i czasu wykonania.
`created_at`	`string`	Znacznik czasu ISO.
`updated_at`	`string`	Znacznik czasu ISO.
`expires_at`	`string \| null`	Rozwiązany znacznik czasu wygaśnięcia lub `null` w przypadku braku wygaśnięcia.
`publicUrl`	`string`	Hostowany adres URL MakePay checkout, dołączany do odpowiedzi na utworzenie, listę, szczegóły i aktualizację statusu.

PaymentLinkPayload

Pole	Typ	Notatki
`title`	`string`	Wyświetl etykietę płatności.
`description`	`string`	Opis skierowany do klienta.
`amount`	`string`	Kwota dziesiętna do zebrania.
`fiatCurrency`	`string`	Opcjonalna wyświetlana waluta, taka jak `USD` lub `EUR`.
`currency`	`string`	Symbol rozliczenia, taki jak `USDT`, `USDC` lub `BTC`.
`asset`	`string`	Dokładny identyfikator zasobu docelowego. Użyj tej opcji, jeśli symbol występuje w wielu łańcuchach.
`orderId`	`string`	Numer zamówienia sprzedawcy lub faktury.
`customerEmail`	`string`	Używany do żądań e-mail i ładunków webhook.
`clientId`	`string`	Opcjonalny identyfikator klienta po stronie sprzedawcy.
`returnUrl`	`string`	Adres URL sprzedawcy do ogólnej nawigacji powrotnej.
`successUrl`	`string`	Adres URL sprzedawcy dla zrealizowanych płatności.
`failureUrl`	`string`	Adres URL sprzedawcy dla nieudanych lub anulowanych płatności.
`expirationTime`	`"15m" \| "1h" \| "12h" \| "24h" \| "72h" \| "never"`	Żądany czas życia linku do płatności.
`metadata`	`Record<string, unknown>`	Metadane zdefiniowane przez sprzedawcę zwracane w panelach kontrolnych i webhooks.
`runtimeMode`	`"merchant_target_net_v2"`	Wstrzyknięty przez API dla nowych łączy płatniczych.
`billingVersion`	`"v2"`	Wstrzyknięty przez API dla nowych łączy płatniczych.
`merchantName`	`string`	Wstrzykiwany z marki firmy, jeśli jest dostępny.
`merchantPictureUrl`	`string`	Wstrzykiwany z profilu firmy, jeśli jest dostępny.
`merchantLogoUrl`	`string`	Wstrzykiwany z marki sprzedawcy, jeśli jest dostępny.
`merchantPaymentLinkTheme`	`"light" \| "dark" \| "system"`	Wstrzyknięto z ustawień motywu checkout sprzedawcy.

Obiekt klienta

Pole	Typ	Notatki
`id`	`string`	Wewnętrzny identyfikator UUID.
`uid`	`string`	Publiczny identyfikator klienta MakePay używany w łączach portalu.
`email`	`string`	E-mail klienta.
`name`	`string \| null`	Wyświetlana nazwa klienta. Możliwość edycji z poziomu portalu klienta.
`clientId`	`string \| null`	Identyfikator klienta po stronie sprzedawcy. Tylko do odczytu w portalu.
`metadata`	`Record<string, unknown>`	Metadane zdefiniowane przez sprzedawcę.
`createdAt`	`string`	Znacznik czasu ISO.
`updatedAt`	`string`	Znacznik czasu ISO.
`urls`	`{ customerPortal: string }`	Obecne na odpowiedziach generacji portalu. Nie utrwalaj tego adresu URL.

Odpowiedź portalu klienta

POST /api/partner/v1/makepay/customers/{customerId}/portal zwraca podpisany adres URL portalu dla zapisanego klienta.

json

{
  "ok": true,
  "companyId": "acct_123",
  "customer": {
    "id": "b834dd77-69b8-41a9-a4b6-95bc9dd14c2d",
    "uid": "cus_01hzy4k6p4w9y2x7e2z7n8a2xm",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "clientId": "client_1042",
    "metadata": {
      "source": "api"
    },
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "urls": {
      "customerPortal": "https://makepay.io/billing?company=acct_123&customer=cus_01hzy4k6p4w9y2x7e2z7n8a2xm&expires=1776765600&signature=8d1f..."
    }
  },
  "expiresAt": "2026-04-21T10:00:00.000Z"
}

Adres URL jest ważny przez 24 godziny i korzysta ze zweryfikowanej firmy payment_link_domain, jeśli jest dostępny. W przeciwnym razie wraca do MakePay pochodzenie publiczne.

Parametr zapytania	Notatki
`company`	Identyfikator konta firmowego MakeCrypto, do którego należy klient.
`customer`	UID klienta MakePay.
`expires`	Znacznik czasu Uniksa w sekundach.
`signature`	Podpis HMAC na `v1:{companyId}:{customerUid}:{expires}`.

Generuj łącza do portalu na żądanie, gdy klient otworzy rozliczenia. Wygasł, naruszone lub adresy URL różnych klientów są odrzucane przed załadowaniem danych portalu.

Obiekt subskrypcji

Pole	Typ	Notatki
`id`	`string`	Wewnętrzny identyfikator UUID.
`uid`	`string`	Identyfikator subskrypcji widoczny dla sprzedawcy.
`status`	`"active" \| "paused" \| "overdue" \| "cancelled"`	Aktualny stan subskrypcji.
`customerEmail`	`string`	Adres e-mail klienta używany do przypomnień i dopasowywania portalu.
`label`	`string`	Etykieta subskrypcji skierowana do klienta.
`description`	`string \| null`	Opcjonalny opis subskrypcji.
`amountUsd`	`string`	Powtarzająca się kwota w USD.
`settlementAsset`	`string`	Identyfikator docelowego składnika aktywów rozliczeniowych.
`cadence`	`"weekly" \| "biweekly" \| "monthly" \| "custom_months" \| "yearly"`	Wyświetl rytm.
`billingIntervalUnit`	`"week" \| "month" \| "year"`	Jednostka interwału rozliczeniowego.
`billingIntervalCount`	`number`	Liczba jednostek pomiędzy cyklami rozliczeniowymi.
`startAt`	`string`	Znacznik czasu ISO dla pierwszego cyklu rozliczeniowego.
`timezone`	`string`	Strefa czasowa IANA używana do pomiaru czasu przypomnienia.
`metadata`	`Record<string, unknown>`	Metadane zdefiniowane przez sprzedawcę i zaawansowane ustawienia przekierowań/tolerancji.
`cycles`	`SubscriptionCycle[]`	Wygenerowane cykle rozliczeniowe zwracane przez trasy list i wywołania pulpitu nawigacyjnego.

Subskrypcje przechodzą na overdue, gdy bezpłatny cykl minie co najmniej 24 godziny jego znacznik czasu dueAt. MakePay wysyła podpisany makepay.subscription.status_changed webhook zawsze, gdy wyświetlany jest status subskrypcji zmiany.

Ustawienia MakePay

Pole	Typ	Notatki
`status`	`"active" \| "paused"`	Dostępność produktów dla zespołu.
`defaultDestinationAsset`	`string \| null`	Domyślny identyfikator zasobu używany, gdy łącza płatnicze udostępniają tylko `currency`.
`feePaidBy`	`"client" \| "merchant"`	Określa, czy klient lub sprzedawca pobiera opłaty MakePay.
`returnRedirectUrl`	`string \| null`	Przekierowanie zastępcze po checkout.
`successRedirectUrl`	`string \| null`	Przekieruj po dokonaniu płatności.
`failureRedirectUrl`	`string \| null`	Przekierowanie po anulowaniu lub nieudanej płatności.
`underpaymentPercentEnabled`	`boolean`	Włącza tolerancję procentową.
`underpaymentPercentThreshold`	`number`	Dopuszczalny procent niedopłaty.
`underpaymentFixedEnabled`	`boolean`	Umożliwia stałą tolerancję.
`underpaymentFixedThreshold`	`number`	Dopuszczalna stała kwota niedopłaty.

Zasób docelowy

Pole	Typ	Notatki
`assetIdentifier`	`string`	Łańcuch kanoniczny, symbol i identyfikator kontraktu.
`chainCode`	`string`	Kod łańcucha rozliczeniowego.
`chainName`	`string`	Nazwa łańcucha czytelna dla człowieka.
`symbol`	`string`	Symbol zasobu.
`name`	`string`	Nazwa zasobu.
`decimals`	`number`	Tokeny dziesiętne.
`isDefault`	`boolean`	Określa, czy ten zasób jest bieżącą wartością domyślną firmy.

Wartości stanu

active: link można otworzyć i opłacić.
paused: link pozostaje widoczny dla sprzedawcy, ale nie powinien akceptować nowych uruchomień płatności.
archived: łącze jest ukryte w aktywnych widokach i powinno być traktowane jako zamknięte.

Wartości stanu subskrypcji:

active: subskrypcja normalnie zbiera zaplanowane faktury.
paused: przypomnienia i zmiany sprzedawcy/klienta spowodowały wstrzymanie subskrypcji.
overdue: co najmniej jeden bezpłatny cykl jest przeterminowany o 24 godziny lub więcej.
cancelled: subskrypcja zostaje zakończona, a nieopłacone wygenerowane cykle zostają anulowane.

Kształt błędu

Błędy zwracają JSON z error i, jeśli są dostępne, errorCode.

{
  "errorCode": "invalid_destination_asset",
  "error": "payload.asset ETH.USDT-... is not available for supported settlement routes."
}