MB WAY (Portugal)

MB WAY is a popular mobile payment method in Portugal. The customer authorizes the payment directly in the MB WAY app on their phone by simply providing their phone number.

Flow diagram

Klient

Twój serwer

dpay.pl

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Endpoint

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

Request parameters

Field	Type	Required	Description
transactionType	string	Yes	"mb_way_direct"
service	string	Yes	Service name from the dashboard
value	string	Yes	Amount in EUR
currency_code	string	Yes	"EUR"
channel	string	Yes	"373"
phone_number	string	Yes	Phone number in 351#XXXXXXXXX format
url_success	string	Yes	URL after successful payment
url_fail	string	Yes	URL after failed payment
url_ipn	string	Yes	URL for IPN notifications
checksum	string	Yes	SHA-256 checksum
device_info	object	Yes	Customer device information

Phone number format

The phone number must be in the following format:

351#XXXXXXXXX

Where:

• 351 - Portugal country code
• # - separator
• XXXXXXXXX - 9-digit phone number

Example: 351#912345678

device_info object

{
  "browserJavaEnabled": false,
  "browserLanguage": "pt-PT",
  "browserColorDepth": "24",
  "browserScreenHeight": "1080",
  "browserScreenWidth": "1920",
  "browserTZ": "0",
  "browserUserAgent": "Mozilla/5.0 ...",
  "browserAcceptHeader": "text/html,application/xhtml+xml",
  "browserJavascriptEnabled": true
}

Request example

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",
    "phone_number": "351#912345678",
    "url_success": "https://myshop.com/success",
    "url_fail": "https://myshop.com/error",
    "url_ipn": "https://myshop.com/api/ipn",
    "checksum": "e3b0c44298fc1c149afb...",
    "device_info": {
      "browserJavaEnabled": false,
      "browserLanguage": "pt-PT",
      "browserColorDepth": "24",
      "browserScreenHeight": "1080",
      "browserScreenWidth": "1920",
      "browserTZ": "0",
      "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "browserAcceptHeader": "text/html,application/xhtml+xml",
      "browserJavascriptEnabled": true
    }
  }'

PHP

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

$value = '14.99';
$urlSuccess = 'https://myshop.com/success';
$urlFail = 'https://myshop.com/error';
$urlIpn = 'https://myshop.com/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',
    'phone_number'    => '351#' . $_POST['phone_number'],
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
    'device_info'     => [
        'browserJavaEnabled'       => false,
        'browserLanguage'          => 'pt-PT',
        'browserColorDepth'        => '24',
        'browserScreenHeight'      => '1080',
        'browserScreenWidth'       => '1920',
        'browserTZ'                => '0',
        'browserUserAgent'         => $_SERVER['HTTP_USER_AGENT'],
        'browserAcceptHeader'      => 'text/html,application/xhtml+xml',
        'browserJavascriptEnabled' => true,
    ],
]);

$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);

API response

Success - awaiting confirmation

{
  "error": false,
  "msg": "Waiting for MB WAY confirmation",
  "status": "PENDING",
  "transactionId": "abc-def-123-456"
}

After receiving the PENDING status, the customer must confirm the payment in the MB WAY app. You will receive the payment result via IPN.

Error

{
  "error": true,
  "msg": "Invalid phone number format",
  "status": false
}

Form example

<form id="mbway-form">
  <label for="phone">Phone number (Portugal)</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">Pay with 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) {
    // Show a message about waiting for confirmation
    alert('Confirm the payment in the MB WAY app');
  }
});
</script>

Common errors

Error	Cause	Solution
Invalid phone number format	Invalid number format	Use the 351#XXXXXXXXX format
MB WAY not available	Customer does not have MB WAY	Suggest an alternative payment method
Transaction timeout	Customer did not confirm in time	Ask them to try again

info

MB WAY is available exclusively for customers with a Portuguese phone number and the MB WAY app installed.