Multibanco voor Webservices API

Multibanco is een Portugese betaalmethode voor online bankieren. Wanneer u Multibanco selecteert, krijgt u twee opties. Met de eerste kan de klant betalen via online bankieren, door in te loggen op zijn Multibanco rekening. Na het bekijken van de vooraf ingevulde betalingsgegevens, kunnen ze akkoord gaan met de betaling, voordat ze terug worden geleid naar uw website. Met de tweede optie kan de klant het bedrag contant betalen bij een bank of geldautomaat. Eenmaal voltooid, ontvangt u een bevestiging via een URL-kennisgeving.

Ondersteunde landen	PT
Ondersteunde munteenheden	EUR
Terugbetalingen	Restituties worden niet ondersteund.
Terugboekingen	Betalingen zijn niet onderhevig aan terugboekingen.
Zero-authorisation	Niet ondersteund.
Terugkerende betalingen	Niet ondersteund.

Configuratie

Om Multibanco op uw account in te schakelen, neemt u contact op met uw accountmanager.
Er wordt een testzandbakaccount verstrekt, die u nodig hebt om uw implementatie te testen.

Procesoverzicht

Initieer de klant
- De klant gaat akkoord met een betaling via Multibanco op de website van de handelaar.
- Merchant dient AUTH verzoek in om de sessie te starten, inclusief de successfulurlredirect en errorurlredirect.
- Merchant ontvangt AUTH antwoord, inclusief redirecturl.
Doorverwijzen naar Multibanco
- Merchant stuurt de browser van de klant door naar de redirecturl.
- De klant volgt de instructies op Multibanco om de betaling te autoriseren.
- Indien succesvol, wordt de browser doorgestuurd naar de successfulurlredirect, een door de handelaar gehoste pagina die de bevestiging van de betaling weergeeft.
- Als er een probleem is geweest met de betaling, wordt de browser doorgestuurd naar de errorurlredirect, een door de handelaar gehoste pagina die de klant een foutmelding geeft.
Voltooiing van de betaling
- Op een later tijdstip zal Multibanco contact opnemen met Trust Payments met de bevestiging dat de fondsen zijn vereffend.
- Trust Payments zal een URL-kennisgeving naar het systeem van de handelaar sturen om te bevestigen dat het geld is betaald.
- De handelaar ontvangt de kennisgeving en antwoordt om Trust Payments te informeren dat de kennisgeving met succes is ontvangen.

1. Initieer de klant

Wanneer de klant ervoor kiest om te betalen met Multibanco, moet uw systeem een AUTH verzoek uitvoeren en, indien succesvol, de browser van de klant omleiden naar de URL die in het antwoord wordt geretourneerd.

AUTH verzoek

Het onderstaande voorbeeld betreft een verzoek op Multibanco AUTH :

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "currencyiso3a": "EUR",
  "requesttypedescription": "AUTH",
  "accounttypedescription": "ECOM",
  "sitereference": "test_site12345",
  "baseamount": "1050",
  "paymenttypedescription": "MULTIBANCO",
  "successfulurlredirect": "https://yourwebsite.com",
  "errorurlredirect": "https://yourwebsite.com",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "billingcountryiso2a": "PT"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^'
);

$requestData = array(
  'currencyiso3a' => 'EUR',
  'requesttypedescription' => 'AUTH',
  'accounttypedescription' => 'ECOM',
  'sitereference' => 'test_site12345',
  'baseamount' => '1050',
  'paymenttypedescription' => 'MULTIBANCO',
  'successfulurlredirect' => 'https://yourwebsite.com',
  'errorurlredirect' => 'https://yourwebsite.com',
  'billingfirstname' => 'Joe',
  'billinglastname' => 'Bloggs',
  'billingcountryiso2a' => 'PT'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "currencyiso3a": "EUR",
    "requesttypedescription": "AUTH",
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "paymenttypedescription": "MULTIBANCO",
    "successfulurlredirect": "https://www.example.com/success",
    "errorurlredirect": "https://www.example.com/error",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "PT"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "currencyiso3a":"EUR",
    "requesttypedescription":"AUTH",
    "accounttypedescription":"ECOM",
    "sitereference":"test_site12345",
    "baseamount":"1050",
    "paymenttypedescription":"MULTIBANCO",
    "successfulurlredirect":"https://www.example.com/success",
    "errorurlredirect":"https://www.example.com/error",
    "billingfirstname":"Joe",
    "billinglastname":"Bloggs",
    "billingcountryiso2a":"PT"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <successfulurlredirect>https://www.example.com/success</successfulurlredirect>
      <errorurlredirect>https://www.example.com/error</errorurlredirect>
    </merchant>
    <billing>
      <name>
        <first>Joe</first>
        <last>Bloggs</last>
      </name>
      <country>PT</country>
      <amount currencycode="EUR">1050</amount>
      <payment type="MULTIBANCO"/>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.

Specificatie veld

Veld	Formaat	Beschrijving
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	Alleen "ECOM" (e-commerce) wordt ondersteund.
baseamount XPath: /billing/amount	Numeriek (13)	Het bedrag van de transactie in basiseenheden, zonder komma's of decimalen, dus €10 wordt ingediend als 1000. Deze waarde moet groter zijn dan nul. (De maximumlengte kan variëren, afhankelijk van uw wervende bank - Neem contact op met uw bank voor meer informatie)
billingcountryiso2a XPath: /billing/country	Alpha (2)	Het land voor het factuuradres van de klant. Dit moet in ISO2A-formaat zijn. Voor een lijst van door Multibanco ondersteunde landcodes, zie de lijst bovenaan deze pagina.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	De Munt waarin de transactie zal worden verwerkt (in ISO3A-formaat). Voor een lijst van Munt codes die worden ondersteund door Multibanco, zie de lijst bovenaan deze pagina.
errorurlredirect XPath: /merchant/errorurlredirect	URL (2048)	De URL waarnaar de klant wordt teruggestuurd na een fout op de Multibanco-gehoste pagina's.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	Deze waarde moet worden ingediend als "MULTIBANCO".
requesttypedescription XPath: /@type	Alpha (20)	De waarde in het verzoek moet "AUTH" zijn.
sitereference XPath: /operation/sitereference	Alfanumeriek & underscore (50)	De site referentie heeft betrekking op uw individuele account die u bij de installatie hebt ontvangen. Als u uw site referentie niet kent, neem dan contact op met ons Support Team.
successfulurlredirect XPath: /merchant/successfulurlredirect	URL (2048)	De URL waarnaar de klant wordt teruggestuurd na een succesvolle autorisatie door Multibanco.
billingprefixname XPath: /billing/name/prefix	Alfanumeriek, inclusief symbolen (25)	Het voorvoegsel van de factuurnaam van de klant (bv. De heer, Juffrouw, Dr.). Ten minste één van de velden met de factureringsnaam is verplicht.
billingfirstname XPath: /billing/name/first	Alfanumeriek, inclusief symbolen (127)	De klant Voornaam facturatie. Ten minste één van de velden met de factureringsnaam is verplicht.
billingmiddlename XPath: /billing/name/middle	Alfanumeriek, inclusief symbolen (127)	De middelste factureringsnaam of -namen van de klant. Ten minste één van de velden met de factureringsnaam is verplicht.
billinglastname XPath: /billing/name/last	Alfanumeriek, inclusief symbolen (127)	De klant Achternaam facturatie. Ten minste één van de velden met de factureringsnaam is verplicht.
billingsuffixname XPath: /billing/name/suffix	Alfanumeriek, inclusief symbolen (25)	Het achtervoegsel van de factureringsnaam van de klant (bv. Bsc). Ten minste één van de velden met de factureringsnaam is verplicht.
orderreference XPath: /merchant/orderreference	Alfanumeriek, inclusief symbolen (25) Aanbevolen lengte 25 tekens of minder (exacte lengte afhankelijk van de wervende bank). Niet-naleving van deze eis kan ertoe leiden dat de tekst in de transactie wordt ingekort.	Uw unieke bestelreferentie die in het Trust Payments systeem kan worden opgeslagen.

AUTH antwoord

{
u'requestreference': u'An3ug1kap',
u'version': u'1.00',
u'responses': [{
u'transactionreference': u'23-86-113',
u'merchantname': u'Test Merchant',
u'paymenttypedescription': u'MULTIBANCO',
u'settleduedate': u'2017-03-16',
u'baseamount': u'1050',
u'transactionstartedtimestamp': u'2017-03-16 16:25:08',
u'errormessage': u'Ok',
u'settlestatus': u'10',
u'accounttypedescription': u'ECOM',
u'errorcode': u'0',
u'redirecturl': u'https://example.com',
u'acquirertransactionreference': u'12',
u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww',
u'requesttypedescription': u'AUTH',
u'acquirerresponsemessage': u'PENDING',
u'operatorname': u'webservices@example.com',
u'livestatus': u'0',
u'currencyiso3a': u'EUR'
}]
}

array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(18) {
      ["transactionreference"] => string(9) "23-86-113"
      ["merchantname"] => string(4) "Test Merchant"
      ["paymenttypedescription"] => string(10) "MULTIBANCO"
      ["settleduedate"] => string(10) "2017-03-16"
      ["baseamount"] => string(4) "1050"
      ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08"
      ["errormessage"] => string(2) "Ok"
      ["settlestatus"] => string(2) "10"
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["redirecturl"] => string(107) "https://example.com"
      ["acquirertransactionreference"] => string(2) "12"
      ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww"
      ["requesttypedescription"] => string(4) "AUTH"
      ["acquirerresponsemessage"] => string(7) "PENDING"
      ["operatorname"] => string(11) "webservices@example.com"
      ["livestatus"] => string(1) "0"
      ["currencyiso3a"] => string(3) "EUR"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d9",
  "version":"1.00",
  "response":[{
    "transactionreference":"23-86-113",
    "merchantname":"Test Merchant",
    "paymenttypedescription":"MULTIBANCO",
    "settleduedate":"2017-03-16",
    "baseamount":"1050",
    "transactionstartedtimestamp":"2017-03-16 16:25:08",
    "errormessage":"Ok",
    "settlestatus":"10",
    "accounttypedescription":"ECOM",
    "errorcode":"0",
    "redirecturl":"https://example.com",
    "acquirertransactionreference":"12",
    "acquirersecret":"q9gy5ppgdyd5fh60kfe2j0f26peu2xww",
    "requesttypedescription":"AUTH",
    "acquirerresponsemessage":"PENDING",
    "operatorname":"webservices@example.com",
    "livestatus":"0",
    "currencyiso3a":"EUR"
  }]
}

<responseblock version="3.67">
  <requestreference>Xd4nk260v</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <transactionreference>44-86-102</transactionreference>
    <timestamp>2017-03-16 17:34:16</timestamp>
    <acquirersecret>gfc8mx0p2fx26f1n5tpy6mtk21naap8c</acquirersecret>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2017-03-16</settleduedate>
      <settlestatus>10</settlestatus>
    </settlement>
    <acquirerresponsemessage>PENDING</acquirerresponsemessage>
    <billing>
      <amount currencycode="EUR">1050</amount>
      <payment type="MULTIBANCO"/>
    </billing>
    <live>0</live>
    <other>
      <redirecturl>https://example.com</redirecturl>
    </other>
    <acquirertransactionreference>4</acquirertransactionreference>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
  </response>
  <secrand>Z1W</secrand>
</responseblock>

Specificatie veld

Veld	Formaat	Beschrijving
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	De geretourneerde waarde is "ECOM".
acquirersecret XPath: /acquirersecret	Alfanumeriek (64)	Gebruikt door Trust Payments om het antwoord van de verwerver te verifiëren. (Uw systeem hoeft dit niet te verifiëren)
acquirertransactionreference XPath: /acquirertransactionreference	Alfanumeriek, inclusief symbolen (127)	Unieke Transactiereferentie toegewezen door Multibanco.
baseamount XPath: /billing/amount	Numeriek (13)	Het bedrag van de transactie in basiseenheden, zonder komma's of decimalen, dus €10 wordt geretourneerd als 1000.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	De Munt waarin de transactie werd verwerkt (in ISO3A-formaat). Voor een lijst van Munt codes die worden ondersteund door Multibanco, zie de lijst bovenaan deze pagina.
errorcode XPath: /error/code	Numeriek (1-5)	De foutcode (errorcode) moet worden gebruikt om te bepalen of het verzoek succesvol was of niet. Als de foutcode "0" is, is de transactie geslaagd. Als de foutcode (errorcode) niet "0" is, was de transactie niet succesvol. Klik hier voor een volledige lijst van errorcode en berichtwaarden.
errormessage XPath: /error/message	Alfanumeriek (255)	Dit is het bericht dat overeenkomt met de bovenstaande code. Klik hier voor een volledige lijst van errorcode en berichtwaarden.
livestatus XPath: /live	Numeriek (1)	0 - Transactie verwerkt met een testrekening. 1 - Transactie verwerkt met een live rekening.
operatorname XPath: /merchant/operatorname	Alfanumeriek (255)	De waarde van dit veld bevat de naam van de gebruiker die het verzoek heeft verwerkt.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	De geretourneerde waarde is "MULTIBANCO".
redirecturl XPath: /other/redirecturl	URL (255)	Leid de browser van de klant om naar deze URL, zodat hij de betaling kan voltooien op Multibanco's gehoste pagina's.
requesttypedescription XPath: /@type	Alpha (20)	De geretourneerde waarde is "AUTH".
settleduedate XPath: /settlement/settleduedate	Datum JJJJ-MM-DD	De datum waarop de transactie zal worden afgewikkeld.
settlestatus XPath: /settlement/settlestatus	Numeriek (3)	Hiermee kunt u de status van de betaling bepalen. Raadpleeg het gedeelte " Omgaan met het antwoord " hieronder voor informatie over hoe u dit veld het best kunt interpreteren.
transactionreference XPath: /transactionreference	Alfanumeriek, inclusief koppeltekens (25)	Een unieke referentie voor de transactie, toegewezen door Trust Payments.
transactionstartedtimestamp XPath: /timestamp	Datum tijd JJJJ-MM-DD hh:mm:ss	Het tijdstip waarop de transactie werd verwerkt.
acquirerresponsemessage XPath: /acquirerresponsemessage	Alfanumeriek (255)	Gebruikt door uw verwerver om het resultaat van het verzoek aan te geven. Dit varieert afhankelijk van uw wervende bank. Neem contact op met uw bank voor meer informatie.
errordata XPath: /error/data	Alfanumeriek (255)	Aanvullende informatie om te helpen bij het oplossen van de fout. Wordt alleen geretourneerd als er een fout is opgetreden.
merchantname XPath: /merchant/merchantname	Alfanumeriek (255)	Dit zijn gegevens die verband houden met de rekening die is gebruikt om de transactie te verwerken. Om deze velden te wijzigen, gelieve neem contact op met ons Support Team. Hangt af van uw account configuratie.

Behandeling van het antwoord

De settlestatus teruggestuurd in het antwoord op AUTH wordt gebruikt om de status van de betaling op Multibanco te bepalen:

Als de settlestatus is "10", is de betaling in behandeling. afwikkeling

Het geld is nog niet op uw bankrekening gestort.
De volgende stap is het omleiden van de browser van de klant naar de redirecturl om de betaling te voltooien.

Het geld wordt pas op uw rekening gestort als de klant wordt doorgestuurd naar Multibanco om de betaling te voltooien. Lees verder voor meer informatie.

Wanneer er een update is van de Status betaling van de AUTH, ontvangt u een URL-kennisgeving om u te informeren dat de settlestatus is bijgewerkt tot "3" of "100".
Nadere informatie over de kennisgevingen is hieronder te vinden.

Als de settlestatus is "3", de betaling is geannuleerd.

De betaling is geweigerd, of er is een fout opgetreden.
Om meer te weten te komen over waarom de betaling niet is gelukt, moet u kijken naar de errorcode. bijv. "70000" geeft aan dat de betaling is geweigerd. Klik hier voor een volledige lijst met foutcodes.

Naast het bovenstaande bevelen wij ook aan na de betaling aanvullende controles te verrichten.

2. Doorverwijzen naar Multibanco

Uw systeem moet de browser van de klant omleiden naar de redirecturl, een pagina gehost door Multibanco, om de betaling te verwerken.

De redirecturl binnen een iframe. Hierdoor wordt de inhoud niet correct weergegeven en kan de betaling uiteindelijk niet succesvol worden afgerond.

Op een later tijdstip wordt de klant teruggestuurd naar de successfulurlredirect of de errorurlredirect verstrekt in het AUTH verzoek.

Als de klant wordt doorverwezen naar de successfulurlredirect:

De klant heeft de vereiste stappen op Multibanco met succes doorlopen.
Aanbevolen acties: Bevestiging weergeven dat de betaling succesvol was.

Als de klant wordt doorverwezen naar de errorurlredirect:

De klant heeft een probleem ondervonden waardoor hij de betaling niet heeft kunnen voltooien.
Aanbevolen acties: Informeer de klant dat er een probleem was met de betaling, waarbij voldoende transactiedetails worden weergegeven zodat de klant de betalingspoging kan navragen.

Bij het testen krijgt u de sandbox te zien die door Multibanco ter beschikking wordt gesteld. Om een testtransactie te voltooien, moet u de instructies op het scherm volgen. Neem contact op met uw accountmanager voor testgegevens die u in de zandbak kunt invoeren.

3. Voltooiing van de betaling

Zodra de klant terugkeert van de Multibanco gehoste pagina naar de successfulurlredirect of errorurlredirect gehost op uw site, moet u respectievelijk een bevestigings- of foutmelding weergeven.

Controleer of er regels voor URL-omleidingen zijn ingeschakeld in de Regelbeheer op uw site referentie(s), aangezien deze in strijd kunnen zijn met en voorrang kunnen hebben op de successfulurlredirect en errorurlredirect velden in het AUTH verzoek.

Zodra een betaling is goedgekeurd, worden de middelen op een later tijdstip verrekend, zoals bepaald door Multibanco.

Het proces afwikkeling voor Multibanco verschilt van het standaardproces dat wordt gevolgd bij betaalmethoden met een kaart.

De afwikkeling kennisgeving mag niet onmiddellijk na de verwerking van de AUTH

In het onwaarschijnlijke geval dat de betaling na 7 dagen nog in behandeling is bij afwikkeling (settlestatus "10"), zal dit worden ingepland voor onderzoek en zullen wij contact met u opnemen voor verdere informatie.

Voordat u begint met testen, raden wij u aan contact op te nemen met ons Support Team en te verzoeken dat regels worden ingeschakeld op uw account, die URL-kennisgevingen naar uw systeem sturen in de volgende scenario's:

Wanneer een betaling is goedgekeurd.
Als de fondsen vereffend zijn.

Configuratie van de autorisatie melding

Wij raden u aan ten minste de volgende velden op te nemen in uw autorisatie kennisgeving:

Antwoordbericht aankoper (acquirerresponsemessage)
Basisbedrag (baseamount) (bijv. 10,50 pond is "1050")*.
Hoofdbedrag (mainamount) (bijv. 10,50 pond is "10,50")*.
Land facturatie (billingcountryiso2a)
Munt (currencyiso3a)
Foutcode (errorcode)
Live Status (livestatus)
Bestelreferentie (orderreference)
Betalingstype (paymenttypedescription)
Verzoektype (requesttypedescription)
Status betaling (settlestatus)
Site referentie (sitereference)
Transactiereferentie (transactionreference)
Tijdstempel start transactie (transactionstartedtimestamp)

*Kies uw voorkeursformaat.

Configuratie van de afwikkeling melding

Wij raden u aan de volgende velden op te nemen in uw afwikkeling kennisgeving:

Status betaling (settlestatus)
Site referentie (sitereference)
Transactiereferentie (transactionreference)

Controleer de kennisgeving

U moet de inhoud van elke ontvangen kennisgeving controleren en dienovereenkomstig reageren door de in onze URL-kennisgevingen documentatie. In het bijzonder moet u kijken naar de bijgewerkte settlestatus waarde:

Op autorisatie: Als de settlestatus "0", "1" of "10" is, is de betaling geautoriseerd en hoeft u op dit moment geen verdere actie te ondernemen. Waarden van "2" of "3" geven echter aan dat de fondsen niet gepland voor afwikkeling (opgeschort en geannuleerd, respectievelijk).
Op afwikkeling: Als de settlestatus is bijgewerkt tot "100", betekent dit dat het geld is vereffend. Als dit echter is bijgewerkt tot "3", betekent dit dat er een probleem is geweest en dat de betaling vervolgens is geannuleerd.

Geannuleerde transacties (settlestatus "3") kan op een later tijdstip worden afgewikkeld. In situaties waarin de klant de voor de uitvoering van de betaling vereiste stappen heeft voltooid, wordt de settlestatus wordt bijgewerkt tot "100" om aan te geven dat het geld naar uw rekening is overgemaakt.

Als u contact hebt opgenomen met het Support Team om afwikkeling meldingen te configureren (zoals hierboven beschreven), wordt u op de hoogte gebracht wanneer dit gebeurt.

Test

U moet uw oplossing testen voordat u live betalingen kunt gaan verwerken. Testtransacties worden verwerkt via uw test site referentie.

Vereisten

U moet contact opnemen met ons Support Team en uw Multibanco testaccountgegevens doorgeven. Wij zullen dan uw test site referentie configureren om rechtstreeks verbinding te maken met de Multibanco testomgeving.

Bij het uitvoeren van testtransacties zal de redirect URL in het antwoord op AUTH uw browser omleiden naar de Multibanco testomgeving om een betaling te simuleren. Verder is het proces precies hetzelfde als bij live betalingen.

Meer lezen over dit onderwerp