Przejdź do głównej zawartości

Multibanco (Portugalia)

wskazówka

Akceptacja tego kanału płatności wymaga dodatkowej umowy z agentem rozliczeniowym wskazanym przez dpay.pl.

Multibanco to popularna w Portugalii metoda płatności referencją. Po rejestracji płatności dpay.pl wystawia dane do zapłaty: numer podmiotu (Entidade), numer referencji (Referência) i kwotę. Płatnik płaci nimi w bankomacie Multibanco albo w bankowości internetowej lub mobilnej swojego banku (opcja płatności za usługi i zakupy - Pagamentos de Serviços/Compras).

Wynik płatności jest asynchroniczny. Płatnik może zapłacić od razu, ale też po kilku godzinach lub dniach - aż do upływu terminu ważności referencji. O opłaceniu albo wygaśnięciu referencji dowiesz się z powiadomień, a nie z odpowiedzi na rejestrację.

Schemat działania​

  1. Twój serwer rejestruje płatność z kanałem Multibanco w walucie EUR.
  2. dpay.pl zwraca dane referencji (obiekt multibanco) i adres bramki w polu msg.
  3. Przekierowujesz płatnika na bramkę - widzi tam dane do zapłaty, termin ważności i instrukcję.
  4. Płatnik płaci referencją w bankomacie albo w bankowości.
  5. dpay.pl potwierdza opłacenie IPN-em i webhookiem payment.succeeded. Gdy referencja wygaśnie bez zapłaty, wysyła webhook payment.failed z kodem expired.
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​

PoleTypWymaganeOpis
transactionTypestringTak"transfers"
servicestringTakNazwa serwisu z panelu
valuestringTakKwota w EUR (z kropką dziesiętną, np. "10.00")
currency_codestringTak"EUR"
channelstringTak"390" - kanał Multibanco
emailstringTak (przy channel)Adres e-mail klienta
client_namestringTak (przy channel)Imię klienta
client_surnamestringTak (przy channel)Nazwisko klienta
accept_tosbooleanTak (przy channel)Potwierdzenie akceptacji regulaminu przez klienta
url_successstringTakURL, na który bramka przekieruje płatnika po opłaceniu
url_failstringTakURL, na który bramka przekieruje płatnika po wygaśnięciu referencji
url_ipnstringNieURL do powiadomień IPN (wysyłanych tylko po opłaceniu)
checksumstringTakSuma kontrolna SHA-256
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).

Waluta EUR

Multibanco przyjmuje wyłącznie EUR - inna waluta kończy się błędem rejestracji. Usługa musi mieć włączoną walutę EUR. Jeśli jej nie ma, rejestracja zwraca błąd Currency code "EUR" does not match the service currency code "PLN". - wtedy skontaktuj się ze swoim opiekunem w dpay.pl.

Suma kontrolna jest liczona tak samo jak przy każdej rejestracji płatności (szczegóły: Checksum):

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": "transfers",
    "service": "abc123",
    "value": "10.00",
    "currency_code": "EUR",
    "channel": "390",
    "email": "klient@example.com",
    "client_name": "Joao",
    "client_surname": "Silva",
    "accept_tos": true,
    "url_success": "https://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/blad",
    "url_ipn": "https://mojsklep.pl/api/ipn",
    "checksum": "e3b0c44298fc1c149afb..."
  }'

PHP​

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

$value = '10.00';
$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/blad';
$urlIpn = 'https://mojsklep.pl/api/ipn';

$checksum = hash('sha256',
    $service . '|' . $secretHash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

$payload = json_encode([
    'transactionType' => 'transfers',
    'service'         => $service,
    'value'           => $value,
    'currency_code'   => 'EUR',
    'channel'         => '390', // Multibanco
    'email'           => $_POST['email'],
    'client_name'     => $_POST['client_name'],
    'client_surname'  => $_POST['client_surname'],
    'accept_tos'      => true,
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
]);

$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['status'] === true && !$result['error']) {
    // Zapisz dane referencji przy zamówieniu - przydadzą się np. w e-mailu do płatnika
    saveMultibancoReference(
        $result['transactionId'],
        $result['multibanco']['entity'],
        $result['multibanco']['reference'],
        $result['multibanco']['expires_at'],
    );

    header('Location: ' . $result['msg']);
    exit;
}

Odpowiedź API​

Sukces​

{
  "error": false,
  "msg": "https://gateway.dpay.pl/pt/pay/42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "status": true,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "multibanco": {
    "entity": "99999",
    "reference": "123456789",
    "amount": "10.00",
    "currency": "EUR",
    "expires_at": "2026-10-18T12:00:00+00:00"
  }
}

Pole status jest wartością logiczną (true/false), a msg zawiera adres bramki, na którą przekierowujesz płatnika. Traktuj go jako gotowy adres - nie składaj go samodzielnie. Pole transactionId identyfikuje płatność w powiadomieniach, w zapytaniach o status i w symulacji.

Obiekt multibanco:

PoleTypOpis
entitystringNumer podmiotu (Entidade) - 5 cyfr
referencestringNumer referencji (Referência) - 9 cyfr bez spacji. Płatnikowi pokazuj go w grupach po trzy cyfry, np. 123 456 789
amountstringKwota do zapłaty, z kropką dziesiętną
currencystringZawsze EUR
expires_atstringTermin ważności referencji (ISO 8601). Po nim referencji nie da się opłacić

Płatnik płaci poza Twoją stroną, często później. Dane referencji możesz pokazać także u siebie, np. na stronie podziękowania albo w e-mailu z potwierdzeniem zamówienia.

Błąd rejestracji (HTTP 400)​

Błędy wykryte przy rejestracji zwracane są w formacie:

{
  "status": "failed",
  "message": "Multibanco supports only currency_code \"EUR\".",
  "errors": []
}

Przekierowanie płatnika na bramkę​

Na bramce płatnik widzi:

  • numer podmiotu (Entidade) i numer referencji (Referência) z przyciskami kopiowania,
  • kwotę (Montante) i termin ważności (Válido até),
  • krótką instrukcję zapłaty w bankomacie Multibanco albo w bankowości internetowej.

Bramka sama sprawdza stan płatności. Po opłaceniu przekierowuje płatnika na url_success, a po wygaśnięciu referencji - na url_fail. Płatnik nie musi czekać na bramce: może ją zamknąć i zapłacić później, więc powrót na Twoją stronę nie jest potwierdzeniem płatności.

Statusy i powiadomienia​

ZdarzenieStatus transakcjiIPNWebhook
Rejestracja - referencja czeka na zapłatęcreatedNie-
Płatnik opłacił referencjępaidTakpayment.succeeded
Referencja wygasła bez zapłatyexpiredNiepayment.failed z kodem expired

Transakcja Multibanco nie przechodzi przez stan processing - czeka w created do opłacenia albo wygaśnięcia referencji (opis stanów: Statusy transakcji).

IPN tylko przy sukcesie

IPN nie zawiera statusu i jest wysyłany tylko po opłaceniu. O wygaśnięciu referencji dowiesz się z webhooka payment.failed (kod expired) albo odpytując o status transakcji. Przy Multibanco zalecamy więc webhooki.

W webhookach metoda płatności zawiera dane referencji:

"payment_method": {
  "type": "multibanco",
  "multibanco": { "entity": "99999", "reference": "123456789" }
}

Termin ważności referencji​

Referencja jest ważna 72 godziny od rejestracji. Dokładny termin zwraca pole multibanco.expires_at - opieraj się na nim, a nie na stałej wartości. Najpóźniej kilka minut po tym terminie dpay.pl unieważnia referencję, anuluje transakcję i wysyła webhook payment.failed z kodem expired.

Płatność może przyjść z opóźnieniem

Nie anuluj zamówienia przed expires_at tylko dlatego, że płatnik nie zapłacił od razu. Jeśli rezerwujesz towar, trzymaj rezerwację do terminu ważności referencji.

Testowanie​

W trybie testowym referencja jest symulowana. Wynik płatności wywołujesz sam - endpointem symulacji albo przyciskami na bramce. Bez tego transakcja czeka na zapłatę, a po upływie terminu ważności wygasa tak jak na produkcji.

Endpoint symulacji​

POST https://api-payments.dpay.pl/api/v1_0/payments/transaction/{transactionId}/multibanco/simulate
Content-Type: application/json
Accept: application/json

W miejsce {transactionId} wstaw transactionId z odpowiedzi rejestracji. Endpoint nie wymaga sumy kontrolnej i działa wyłącznie dla usług w trybie testowym.

PoleTypWymaganeOpis
actionstringTak"pay" - symuluje opłacenie referencji, "expire" - symuluje jej wygaśnięcie
AkcjaEfekt
payTransakcja zostaje opłacona: IPN na url_ipn i webhook payment.succeeded
expireTransakcja zostaje anulowana: webhook payment.failed z kodem expired, bez IPN

Przykład: opłacenie referencji​

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/transaction/42191111-A7AE-392E-8C09-7965C1DC6B0B/multibanco/simulate \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"action": "pay"}'

Przykład: wygaśnięcie referencji​

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/transaction/42191111-A7AE-392E-8C09-7965C1DC6B0B/multibanco/simulate \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"action": "expire"}'

Odpowiedź (HTTP 200)​

{
  "success": true,
  "changed": true,
  "status": "paid",
  "transactionStatus": 1
}
PoleOpis
successtrue - akcja została przyjęta
changedtrue, gdy wywołanie zmieniło stan referencji; false, gdy referencja była już opłacona albo wygasła
statusStan referencji: pending, paid albo expired
transactionStatusStatus transakcji jako liczba: 0 - oczekuje na zapłatę, 1 - opłacona, -1 - anulowana

Endpoint jest idempotentny. Ponowne wywołanie dla referencji, która jest już opłacona albo wygasła, nic nie zmienia i zwraca changed: false z bieżącym stanem - np. expire po pay zwróci "status": "paid".

Kody odpowiedzi​

HTTPKiedy
200Akcja przyjęta - także wtedy, gdy nic nie zmieniła (patrz changed)
404Transakcja nie jest płatnością Multibanco albo usługa nie jest w trybie testowym
422Nieznana wartość action - dozwolone są pay i expire

Przyciski symulacji na bramce​

W trybie testowym bramka pokazuje baner trybu testowego i dwa przyciski: opłacenia i wygaśnięcia referencji. Działają tak samo jak endpoint symulacji, a bramka od razu odświeża stan i przekierowuje płatnika na url_success albo url_fail. To wygodny sposób, żeby ręcznie przejść całą ścieżkę płatnika.

Co sprawdzić przed produkcją​

  1. Rejestracja zwraca obiekt multibanco, a Twoja aplikacja przekierowuje płatnika na adres z msg.
  2. Po akcji pay zamówienie zmienia się na opłacone na podstawie IPN albo webhooka payment.succeeded - nie na podstawie powrotu na url_success.
  3. Po akcji expire zamówienie zostaje anulowane na podstawie webhooka payment.failed z kodem expired (IPN nie przychodzi).
  4. Ponowne powiadomienie o tej samej płatności nie zmienia stanu zamówienia drugi raz.

Najczęstsze błędy​

KomunikatGdzie występujePrzyczynaRozwiązanie
Multibanco is not enabled for this service.message (HTTP 400)Kanał Multibanco nie jest aktywny dla usługiPoproś opiekuna w dpay.pl o aktywację kanału Multibanco dla usługi
Multibanco supports only currency_code "EUR".message (HTTP 400)Brak currency_code albo waluta inna niż EURPrzekaż currency_code: "EUR"
Multibanco requires transactionType "transfers".message (HTTP 400)Kanał Multibanco podany przy innym typie transakcjiUżyj transactionType: "transfers"
Currency code "EUR" does not match the service currency code "PLN".message (HTTP 400)Usługa nie ma włączonej waluty EURPoproś opiekuna w dpay.pl o włączenie EUR dla usługi
Błąd walidacji pólHTTP 422Brak email, client_name, client_surname lub accept_tos przy podanym channelUzupełnij brakujące pola
Odpowiedź 404Endpoint symulacjiPłatność nie jest płatnością Multibanco albo usługa nie jest w trybie testowymSprawdź transactionId i tryb testowy usługi
informacja

Referencję Multibanco opłaci płatnik z kontem w banku działającym w Portugalii - w bankomacie Multibanco albo w bankowości internetowej lub mobilnej.

Ostatnia aktualizacja dnia