Bizum (Hiszpania)

Bizum to popularna metoda płatności mobilnych w Hiszpanii, umożliwiajaca szybkie przelewy między uzytkownikami oraz płatności w sklepach internetowych. Klient autoryzuje transakcję bezpośrednio w aplikacji swójego banku.

Schemat działania

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

Parametry zapytania

Pole	Typ	Wymagane	Opis
transactionType	string	Tak	"bizum_direct"
service	string	Tak	Nazwa serwisu z panelu
value	string	Tak	Kwota w EUR
currency_code	string	Tak	"EUR"
channel	string	Tak	"373"
phone_number	string	Tak	Numer telefonu w formacie 34#XXXXXXXXX
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

Format numeru telefonu

34#XXXXXXXXX

Gdzie:

• 34 - kierunkowy Hiszpanii
• # - separator
• XXXXXXXXX - 9-cyfrowy numer telefonu

Przykład: 34#612345678

Generowanie checksum

Identycznie jak w standardowej integracji:

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

Przykład zapytania

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://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/błąd",
    "url_ipn": "https://mojsklep.pl/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://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' => '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 'Platnosc zarejestrowana. Czekamy na potwierdzenie klienta.';
} else {
    echo 'Błąd: ' . $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://mojsklep.pl/sukces';
  const urlFail = 'https://mojsklep.pl/błąd';
  const urlIpn = 'https://mojsklep.pl/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;
}

Odpowiedz API

Sukces

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

Błąd

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

Porównanie z MB WAY

Cecha	Bizum	MB WAY
Kraj	Hiszpania	Portugalia
transactionType	bizum_direct	mb_way_direct
Kierunkowy	34	351
Waluta	EUR	EUR
channel	373	373

Oba systemy działają na tej samej zasadzie - klient podaje numer telefonu i potwierdza płatność w aplikacji mobilnej.

Najczęstsze błędy

Błąd	Przyczyna	Rozwiązanie
Invalid phone number format	Zly format numeru	Użyj 34#XXXXXXXXX
Bizum not available	Klient nie ma Bizum	Zaproponuj inną metode
Transaction timeout	Brak potwierdzenia	Popros o ponowną próbę
User declined	Klient odrzućil płatność	Poinformuj klienta

informacja

Bizum wymaga, aby klient mial aktywną usluge Bizum w aplikacji swójego banku. Większość dużyćh bankow hiszpanskich obsługuje Bizum.