Bizum (Spain)

Bizum is a popular mobile payment method in Spain, enabling fast transfers between users and payments in online stores. The customer authorizes the transaction directly in their bank's mobile app.

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	"bizum_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 34#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

34#XXXXXXXXX

Where:

• 34 - Spain country code
• # - separator
• XXXXXXXXX - 9-digit phone number

Example: 34#612345678

Generating the checksum

Identical to the standard integration:

sha256({service}|{SecretHash}|{value}|{url_success}|{url_fail}|{url_ipn})

Request examples

cURL

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "bizum_direct",
    "service": "abc123",
    "value": "24.99",
    "currency_code": "EUR",
    "channel": "373",
    "phone_number": "34#612345678",
    "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": "es-ES",
      "browserColorDepth": "24",
      "browserScreenHeight": "1080",
      "browserScreenWidth": "1920",
      "browserTZ": "-60",
      "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 = '24.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' => 'bizum_direct',
    'service'         => $service,
    'value'           => $value,
    'currency_code'   => 'EUR',
    'channel'         => '373',
    'phone_number'    => '34#' . $_POST['phone_number'],
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
    'device_info'     => [
        'browserJavaEnabled'       => false,
        'browserLanguage'          => 'es-ES',
        'browserColorDepth'        => '24',
        'browserScreenHeight'      => '1080',
        'browserScreenWidth'       => '1920',
        'browserTZ'                => '-60',
        '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);

if (!$result['error']) {
    echo 'Payment registered. Waiting for customer confirmation.';
} else {
    echo 'Error: ' . $result['msg'];
}

Node.js

const crypto = require('crypto');
const axios = require('axios');

async function processBizumPayment(phoneNumber, amount) {
  const service = process.env.DPAY_SERVICE;
  const secretHash = process.env.DPAY_SECRET_HASH;

  const urlSuccess = 'https://myshop.com/success';
  const urlFail = 'https://myshop.com/error';
  const urlIpn = 'https://myshop.com/api/ipn';

  const checksum = crypto
    .createHash('sha256')
    .update(`${service}|${secretHash}|${amount}|${urlSuccess}|${urlFail}|${urlIpn}`)
    .digest('hex');

  const response = await axios.post(
    'https://api-payments.dpay.pl/api/v1_0/payments/register',
    {
      transactionType: 'bizum_direct',
      service,
      value: amount,
      currency_code: 'EUR',
      channel: '373',
      phone_number: `34#${phoneNumber}`,
      url_success: urlSuccess,
      url_fail: urlFail,
      url_ipn: urlIpn,
      checksum,
      device_info: {
        browserJavaEnabled: false,
        browserLanguage: 'es-ES',
        browserColorDepth: '24',
        browserScreenHeight: '1080',
        browserScreenWidth: '1920',
        browserTZ: '-60',
        browserUserAgent: 'Mozilla/5.0',
        browserAcceptHeader: 'text/html,application/xhtml+xml',
        browserJavascriptEnabled: true,
      },
    }
  );

  return response.data;
}

API response

Success

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

Error

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

Comparison with MB WAY

Feature	Bizum	MB WAY
Country	Spain	Portugal
transactionType	bizum_direct	mb_way_direct
Country code	34	351
Currency	EUR	EUR
channel	373	373

Both systems work on the same principle - the customer provides their phone number and confirms the payment in their mobile app.

Common errors

Error	Cause	Solution
Invalid phone number format	Incorrect number format	Use 34#XXXXXXXXX
Bizum not available	Customer does not have Bizum	Suggest an alternative method
Transaction timeout	No confirmation received	Ask to try again
User declined	Customer rejected the payment	Inform the customer

info

Bizum requires the customer to have an active Bizum service in their bank's mobile app. Most major Spanish banks support Bizum.