Przejdź do głównej zawartości

MB WAY (Portugalia)

wskazówka

Akceptacja tego kanału płatności wymaga dodatkowej umowy z agentem rozliczeniowym wskazanym przez dpay.pl.

MB WAY to popularna metoda płatności mobilnych w Portugalii. Klient autoryzuje płatność bezpośrednio w aplikacji MB WAY na swoim telefonie, podając jedynie numer telefonu.

Schemat działania​

POST/api/v1_0/payments/registerPełny kontrakt rejestracji płatności: parametry, checksum i kody błędów.Pełny kontrakt w API Reference

Endpoint​

POST https://api-payments.dpay.pl/api/v1_0/payments/register
Content-Type: application/json
Limity zapytań

Endpoint rejestracji płatności obsługuje do 120 zapytań na minutę.

Parametry zapytania​

PoleTypWymaganeOpis
transactionTypestringTak"mb_way_direct"
servicestringTakNazwa serwisu z panelu
valuestringTakKwota w EUR
currency_codestringTak"EUR"
channelstringTak"373" - kanał MB WAY
emailstringTak (przy channel)Adres e-mail klienta
client_namestringTak (przy channel)Imię klienta
client_surnamestringTak (przy channel)Nazwisko klienta
accept_tosbooleanTak (przy channel)Potwierdzenie akceptacji regulaminu przez klienta
phone_numberstringTakNumer telefonu w formacie +351XXXXXXXXX
url_successstringTakURL po udanej płatności
url_failstringTakURL po nieudanej płatności
url_ipnstringTakURL do powiadomień IPN
checksumstringTakSuma kontrolna SHA-256
device_infoobjectTakInformacje o urządzeniu klienta (komplet pól poniżej)
Pole channel i pola towarzyszące

Pole channel z wartością "373" jest wymagane dla transactionType: "mb_way_direct". Podawaj je zawsze, także w trybie testowym - symulator go nie sprawdza, ale na usłudze produkcyjnej rejestracja bez channel się nie powiedzie. Podanie pola channel wymaga jednoczesnego przekazania pól email, client_name, client_surname oraz accept_tos. Ich brak spowoduje błąd walidacji (HTTP 422).

Waluta EUR

MB WAY przyjmuje wyłącznie EUR. Usługa musi mieć włączoną walutę EUR - jeśli jej nie ma, rejestracja kończy się błędem Currency code "EUR" does not match the service currency code "PLN". W takiej sytuacji skontaktuj się ze swoim opiekunem w dpay.pl.

Format numeru telefonu​

Numer telefonu w standardowym formacie międzynarodowym:

+351XXXXXXXXX

Gdzie:

  • +351 - kierunkowy Portugalii
  • XXXXXXXXX - 9-cyfrowy numer telefonu

Przykład: +351912345678

Obiekt device_info​

Dla transakcji mb_way_direct wszystkie poniższe pola są wymagane:

{
  "browserAcceptHeader": "text/html,application/xhtml+xml",
  "browserJavaEnabled": "false",
  "browserLanguage": "pt-PT",
  "browserColorDepth": 24,
  "browserScreenHeight": 1080,
  "browserScreenWidth": 1920,
  "browserTZ": 0,
  "browserUserAgent": "Mozilla/5.0 ...",
  "systemFamily": "Windows",
  "deviceID": "device-uuid-1234",
  "applicationName": "Chrome",
  "geoLocalization": "38.7223,-9.1393"
}
Typy pól device_info

Pole browserJavaEnabled jest wymagane i musi być łańcuchem znaków "true" lub "false" (nie wartością logiczną). Pola browserColorDepth, browserScreenHeight, browserScreenWidth i browserTZ są liczbami całkowitymi. Brak któregokolwiek z pól obiektu device_info spowoduje błąd walidacji (HTTP 422).

browserJavaEnabled w SDK dpay

W SDK dpay pole browserJavaEnabled jest opcjonalne - jeśli go nie ustawisz, SDK nie wyśle go w zapytaniu, a rejestracja MB WAY skończy się błędem walidacji (HTTP 422). Ustaw je jawnie, np. withBrowserJavaEnabled(false) w PHP i Javie, with_browser_java_enabled(False) w Pythonie, with_browser_java_enabled(false) w Ruby, browserJavaEnabled: false w Node.js albo BrowserJavaEnabled: dpay.Bool(false) w Go. SDK zamieni wartość logiczną na wymagany łańcuch znaków.

Przykład zapytania​

cURL​

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "mb_way_direct",
    "service": "abc123",
    "value": "14.99",
    "currency_code": "EUR",
    "channel": "373",
    "email": "klient@example.com",
    "client_name": "Joao",
    "client_surname": "Silva",
    "accept_tos": true,
    "phone_number": "+351912345678",
    "url_success": "https://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/błąd",
    "url_ipn": "https://mojsklep.pl/api/ipn",
    "checksum": "e3b0c44298fc1c149afb...",
    "device_info": {
      "browserAcceptHeader": "text/html,application/xhtml+xml",
      "browserJavaEnabled": "false",
      "browserLanguage": "pt-PT",
      "browserColorDepth": 24,
      "browserScreenHeight": 1080,
      "browserScreenWidth": 1920,
      "browserTZ": 0,
      "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "systemFamily": "Windows",
      "deviceID": "device-uuid-1234",
      "applicationName": "Chrome",
      "geoLocalization": "38.7223,-9.1393"
    }
  }'

PHP​

<?php
$service = getenv('DPAY_SERVICE');
$secretHash = getenv('DPAY_SECRET_HASH');

$value = '14.99';
$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/błąd';
$urlIpn = 'https://mojsklep.pl/api/ipn';

$checksum = hash('sha256',
    $service . '|' . $secretHash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

$payload = json_encode([
    'transactionType' => 'mb_way_direct',
    'service'         => $service,
    'value'           => $value,
    'currency_code'   => 'EUR',
    'channel'         => '373',
    'email'           => $_POST['email'],
    'client_name'     => $_POST['client_name'],
    'client_surname'  => $_POST['client_surname'],
    'accept_tos'      => true,
    'phone_number'    => '+351' . $_POST['phone_number'],
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
    'device_info'     => [
        'browserAcceptHeader' => 'text/html,application/xhtml+xml',
        'browserJavaEnabled'  => 'false',
        'browserLanguage'     => 'pt-PT',
        'browserColorDepth'   => 24,
        'browserScreenHeight' => 1080,
        'browserScreenWidth'  => 1920,
        'browserTZ'           => 0,
        'browserUserAgent'    => $_SERVER['HTTP_USER_AGENT'],
        'systemFamily'        => 'Windows',
        'deviceID'            => $_POST['device_id'],
        'applicationName'     => 'Chrome',
        'geoLocalization'     => $_POST['geo'],
    ],
]);

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

Odpowiedź API​

Sukces - oczekiwanie na potwierdzenie​

{
  "error": false,
  "msg": "Internal processing",
  "status": true,
  "transactionId": "abc-def-123-456"
}

Pole status jest wartością logiczną (true/false). Odpowiedź Internal processing oznacza, że transakcja została przyjęta - klient musi teraz potwierdzić płatność w aplikacji MB WAY. Wynik przyjdzie asynchronicznie (patrz Wynik płatności).

Błąd rejestracji (HTTP 400)​

Błędy wykryte przy rejestracji (np. brak numeru telefonu) zwracane są w formacie:

{
  "status": "failed",
  "message": "Phone number is required for MB Way Direct transactions.",
  "errors": []
}

Odrzucenie płatności w odpowiedzi na rejestrację​

Gdy płatność zostanie odrzucona już przy rejestracji, transakcja zostaje anulowana, a kod i opis błędu znajdziesz w polu additionalInfo:

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "abc-def-123-456",
  "additionalInfo": {
    "error": "E0506",
    "error_description": "Alias does not exist"
  }
}

Na produkcji w ten sposób wracają błędy wykryte przed wysłaniem powiadomienia do aplikacji MB WAY, np. numer niezarejestrowany w MB WAY (E0506) albo błędne dane zapytania (E0103). W trybie testowym w tym formacie wracają wszystkie scenariusze niepowodzenia - z kodami symulatora (patrz Testowanie w trybie testowym).

Wynik płatności​

SytuacjaNa produkcjiW trybie testowym
Klient potwierdził płatnośćIPN i webhook payment.succeeded po potwierdzeniu w aplikacjiIPN i webhook payment.succeeded kilka sekund po rejestracji
Klient odrzucił płatność w aplikacji albo jej nie potwierdziłZwykle asynchronicznie, po decyzji klienta albo upływie czasu na potwierdzenie: webhook payment.failed; wyjątkowo od razu w odpowiedzi na rejestrację (E0399)Od razu w odpowiedzi na rejestrację (USER_DECLINED, TIMEOUT) oraz webhook payment.failed
Numer niezarejestrowany, błędne daneOd razu w odpowiedzi na rejestrację (np. E0506, E0103) oraz webhook payment.failedOd razu w odpowiedzi na rejestrację (ALIAS_NOT_FOUND, SYSTEM_ERROR) oraz webhook payment.failed
IPN tylko przy sukcesie

IPN nie zawiera statusu i jest wysyłany wyłącznie po opłaceniu płatności. Odmowę i brak potwierdzenia zgłasza tylko webhook payment.failed - jeśli korzystasz wyłącznie z IPN, o nieudanej płatności dowiesz się, odpytując o status transakcji. Przy odmowie zwróconej w odpowiedzi na rejestrację zdarzenie ma w failure.code wartość generic_decline, a kod odmowy (np. USER_DECLINED) w failure.provider_code (patrz Kody odmów).

Przykład formularza​

<form id="mbway-form">
  <label for="phone">Numer telefonu (Portugalia)</label>
  <div style="display: flex; align-items: center;">
    <span>+351</span>
    <input
      type="tel"
      id="phone"
      name="phone_number"
      maxlength="9"
      pattern="[0-9]{9}"
      placeholder="912345678"
      required
    />
  </div>
  <button type="submit">Zapłać przez MB WAY</button>
</form>

<script>
document.getElementById('mbway-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const phone = document.getElementById('phone').value;

  const response = await fetch('/api/pay/mb-way', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone_number: phone }),
  });

  const result = await response.json();
  if (!result.error) {
    // Pokaż komunikat o oczekiwaniu na potwierdzenie
    alert('Potwierdź płatność w aplikacji MB WAY');
  }
});
</script>

Testowanie w trybie testowym​

W trybie testowym możesz użyć specjalnych numerów telefonu, które symulują różne scenariusze, bez potrzeby posiadania aplikacji MB WAY:

Numer telefonuScenariuszOdpowiedź na rejestracjęKod w additionalInfo.error
+351900000001Płatność zakończona sukcesemInternal processing, po kilku sekundach IPN i payment.succeeded-
+351900000002Sukces po dłuższym oczekiwaniuInternal processing, IPN i payment.succeeded po dłuższej chwili-
+351900000400Użytkownik odrzucił w aplikacjiTransaction canceledUSER_DECLINED
+351900000401Timeout - brak potwierdzeniaTransaction canceledTIMEOUT
+351900000402Numer niezarejestrowany w MB WAYTransaction canceledALIAS_NOT_FOUND
+351900000500Błąd systemuTransaction canceledSYSTEM_ERROR

W trybie testowym odmowa i timeout przychodzą od razu w odpowiedzi na rejestrację - na produkcji klient decyduje w aplikacji, więc ten sam wynik przychodzi asynchronicznie, webhookiem payment.failed (patrz Wynik płatności). Przykładowa odpowiedź dla +351900000400:

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "abc-def-123-456",
  "additionalInfo": {
    "error": "USER_DECLINED",
    "error_description": "User declined the transaction"
  }
}
Numer testowy dokładnie z plusem

Numer testowy podaj dokładnie tak jak w tabeli, z + na początku (spacje i myślniki są usuwane). Numer bez +, np. 351900000400, zostanie odrzucony błędem Phone number is required for MB Way Direct transactions., a poprawny numer spoza tabeli (np. +351912345678) symulator potraktuje jak nieznany i zasymuluje płatność zakończoną sukcesem.

Pełna lista numerów testowych i szczegóły działania dostępne na stronie Środowisko testowe.

Najczęstsze błędy​

Komunikat / kodGdzie występujePrzyczynaRozwiązanie
Phone number is required for MB Way Direct transactions.message (HTTP 400)Brak numeru telefonu lub format niemożliwy do znormalizowania (numer zostaje odrzucony)Użyj formatu +351XXXXXXXXX
Currency code "EUR" does not match the service currency code "PLN".message (HTTP 400)Usługa nie ma włączonej waluty EURPoproś opiekuna w dpay.pl o włączenie EUR dla usługi
PLN currency code is not allowed for MB WAY DIRECT transactions.message (HTTP 400)Waluta PLN w zapytaniu MB WAYUżyj currency_code: "EUR"
Błąd walidacji device_info.browserJavaEnabledHTTP 422Brak pola albo wartość logiczna zamiast łańcucha znaków (częste przy SDK bez jawnego ustawienia pola)Wyślij "true" albo "false"
USER_DECLINED, TIMEOUT, ALIAS_NOT_FOUND, SYSTEM_ERRORadditionalInfoScenariusze symulatora w trybie testowymPatrz Testowanie w trybie testowym
E0506 - Alias does not existadditionalInfoNumer niezarejestrowany w MB WAYZaproponuj inną metodę płatności
E0508 - Alias not availableadditionalInfoAlias chwilowo niedostępnyPoproś o ponowną próbę
E0399 - Transaction declinedadditionalInfoPłatność odrzucona (np. brak potwierdzenia lub odmowa klienta)Poproś o ponowną próbę
E0309 - Transaction not foundadditionalInfoTransakcja nieznana u dostawcyZarejestruj płatność ponownie
E0103 - Request validation failedadditionalInfoBłędne dane zapytaniaSprawdź komplet pól, w tym device_info
E0099 - Operation not allowed for this aliasadditionalInfoOperacja niedozwolona dla tego numeruZaproponuj inną metodę płatności
informacja

MB WAY jest dostępny wyłącznie dla klientów z portugalskim numerem telefonu i zainstalowaną aplikacją MB WAY.

Ostatnia aktualizacja dnia