MB WAY (Portugal)

tip

Accepting this payment channel requires an additional agreement with the acquiring agent designated by dpay.pl.

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 providing only their phone number.

How it works

Customer

Your server

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.

POST/api/v1_0/payments/register→Complete payment registration contract: parameters, checksum, and error codes.Full contract in the API Reference

Endpoint

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

Rate limits

The payment registration endpoint supports up to 120 requests per minute.

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"
email	string	Yes (with channel)	Customer's email address
client_name	string	Yes (with channel)	Customer's first name
client_surname	string	Yes (with channel)	Customer's last name
accept_tos	boolean	Yes (with channel)	Confirmation that the customer accepts the terms and conditions
phone_number	string	Yes	Phone number in +351XXXXXXXXX format
url_success	string	Yes	URL after a successful payment
url_fail	string	Yes	URL after a failed payment
url_ipn	string	Yes	URL for IPN notifications
checksum	string	Yes	SHA-256 checksum
device_info	object	Yes	Customer device information (all fields listed below)

Fields accompanying channel

Providing the channel field also requires email, client_name, client_surname, and accept_tos. If any of them is missing, the request fails validation (HTTP 422).

Phone number format

Use the standard international phone number format:

+351XXXXXXXXX

Where:

• +351 - Portugal's country code
• XXXXXXXXX - 9-digit phone number

Example: +351912345678

device_info object

For mb_way_direct transactions, all fields below are required:

{
  "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"
}

device_info field types

The browserJavaEnabled field must be the string "true" or "false" (not a boolean). The browserColorDepth, browserScreenHeight, browserScreenWidth, and browserTZ fields are integers. If any field in the device_info object is missing, the request fails validation (HTTP 422).

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",
    "email": "customer@example.com",
    "client_name": "Joao",
    "client_surname": "Silva",
    "accept_tos": true,
    "phone_number": "+351912345678",
    "url_success": "https://myshop.example/success",
    "url_fail": "https://myshop.example/failure",
    "url_ipn": "https://myshop.example/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://myshop.example/success';
$urlFail = 'https://myshop.example/failure';
$urlIpn = 'https://myshop.example/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);

API response

Success - awaiting confirmation

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

The status field is a boolean (true/false). The Internal processing response means the transaction has been accepted and the customer must now confirm the payment in the MB WAY app. You will receive the payment result via IPN.

Registration error (HTTP 400)

Errors detected during registration, such as a missing phone number, use the following response format:

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

Payment rejection

When the provider rejects a payment, the transaction is cancelled and the error code and description are returned in additionalInfo:

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

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 while waiting for confirmation
    alert('Confirm the payment in the MB WAY app');
  }
});
</script>

Testing in sandbox mode

In test mode, you can use special phone numbers to simulate different scenarios without having the MB WAY QLY app:

Phone number	Scenario
+351900000001	Payment completed successfully
+351900000002	Success after a longer wait
+351900000400	User rejected the payment in the app
+351900000401	Timeout - no confirmation
+351900000402	Phone number not registered with MB WAY
+351900000500	System error

The full list of test numbers and details is available on the Test environment page.

Common errors

Message / code	Where it appears	Cause	Solution
Phone number is required for MB Way Direct transactions.	message (HTTP 400)	Missing phone number or a format that cannot be normalized (the number is rejected)	Use the +351XXXXXXXXX format
E0506 - Alias does not exist	additionalInfo	Phone number not registered with MB WAY	Suggest another payment method
E0508 - Alias not available	additionalInfo	Alias temporarily unavailable	Ask the customer to try again
E0399 - Transaction declined	additionalInfo	Payment rejected (for example, no confirmation or the customer declined it)	Ask the customer to try again
E0309 - Transaction not found	additionalInfo	Transaction unknown to the provider	Register the payment again
E0103 - Request validation failed	additionalInfo	Invalid request data	Check that all fields, including device_info, are present
E0099 - Operation not allowed for this alias	additionalInfo	Operation not allowed for this phone number	Suggest another payment method

info

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