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

Klient

Twój serwer

dpay.pl

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

Pole	Typ	Wymagane	Opis
`transactionType`	string	Tak	`"mb_way_direct"`
`service`	string	Tak	Nazwa serwisu z panelu
`value`	string	Tak	Kwota w EUR
`currency_code`	string	Tak	`"EUR"`
`channel`	string	Tak	`"373"`
`email`	string	Tak (przy `channel`)	Adres e-mail klienta
`client_name`	string	Tak (przy `channel`)	Imię klienta
`client_surname`	string	Tak (przy `channel`)	Nazwisko klienta
`accept_tos`	boolean	Tak (przy `channel`)	Potwierdzenie akceptacji regulaminu przez klienta
`phone_number`	string	Tak	Numer telefonu w formacie `+351XXXXXXXXX`
`url_success`	string	Tak	URL po udanej płatności
`url_fail`	string	Tak	URL po nieudanej płatności
`url_ipn`	string	Tak	URL do powiadomień IPN
`checksum`	string	Tak	Suma kontrolna SHA-256
`device_info`	object	Tak	Informacje o urządzeniu klienta (komplet pól poniżej)

Pola towarzyszące channel

Podanie pola channel wymaga jednoczesnego przekazania pól email, client_name, client_surname oraz accept_tos. Ich brak spowoduje błąd walidacji (HTTP 422).

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 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).

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 płatności otrzymasz przez IPN.

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

Gdy dostawca odrzuci płatność, 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"
  }
}

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 sandbox

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

Numer telefonu	Scenariusz
`+351900000001`	Płatność zakończona sukcesem
`+351900000002`	Sukces po dłuższym oczekiwaniu
`+351900000400`	Użytkownik odrzucił w aplikacji
`+351900000401`	Timeout - brak potwierdzenia
`+351900000402`	Numer niezarejestrowany w MB WAY
`+351900000500`	Błąd systemu

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

Najczęstsze błędy

Komunikat / kod	Gdzie występuje	Przyczyna	Rozwią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`
`E0506` - `Alias does not exist`	`additionalInfo`	Numer niezarejestrowany w MB WAY	Zaproponuj inną metodę płatności
`E0508` - `Alias not available`	`additionalInfo`	Alias chwilowo niedostępny	Poproś o ponowną próbę
`E0399` - `Transaction declined`	`additionalInfo`	Płatność odrzucona (np. brak potwierdzenia lub odmowa klienta)	Poproś o ponowną próbę
`E0309` - `Transaction not found`	`additionalInfo`	Transakcja nieznana u dostawcy	Zarejestruj płatność ponownie
`E0103` - `Request validation failed`	`additionalInfo`	Błędne dane zapytania	Sprawdź komplet pól, w tym `device_info`
`E0099` - `Operation not allowed for this alias`	`additionalInfo`	Operacja niedozwolona dla tego numeru	Zaproponuj 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.

Schemat działania​

Endpoint​

Parametry zapytania​

Format numeru telefonu​

Obiekt device_info​

Przykład zapytania​

cURL​

PHP​

Odpowiedź API​

Sukces - oczekiwanie na potwierdzenie​

Błąd rejestracji (HTTP 400)​

Odrzucenie płatności​

Przykład formularza​

Testowanie w trybie sandbox​

Najczęstsze błędy​