Multibanco Deposit

Payment Method Multibanco is a popular payment method from Portugal.

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

Reversal State

114

MultibancoDeposit

DepositedByProvider (29)

Payment method interaction type: Interaction for offline execution (see Interaction Types).

Redirect Integration

❗️

Coming soon

Content for this section will be added shortly.

Backend2BackendIntegration

By executing getPaymentInputData the merchant requests a VAN (UserVirtualAccountNumber), that customer use when doing a deposit. When a customer deposits money, the provider notifies PXP Financial and a payment is created and the merchant is being notified.

The returned VAN can only be used for a single payment.

getPaymentInputData

Please note that for Multibanco deposit an amount and an eMail address is required.

The details CurrencyCode and CountryCode2 shown belong are optional.

getPaymentInputDataRequest sample:

<getPaymentInputDataRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <merchantID>XXXX</merchantID>
    <shopID>XXXX</shopID>
    <user>
      <id>86fd1ca7-6776-47bf-9184-f37331</id>
        <email>[email protected]</email>
        <address>
            <countryCode2>PT</countryCode2>
        </address>
    </user>
    <paymentMethodID>114</paymentMethodID>
    <amount currencyCode="EUR">12</amount>
    <details>
        <data xsi:type="keyStringValuePair">
            <key>CurrencyCode</key>
            <value>EUR</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>CountryCode2</key>
            <value>PT</value>
        </data>
    </details>
</getPaymentInputDataRequest>

Alternatively use this shorter getPaymentInputDataRequest sample:

<getPaymentInputDataRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <merchantID>XXXX</merchantID>
    <shopID>XXXX</shopID>
    <user>
      <id>86fd1ca7-6776-47bf-9184-f37331</id>
        <email>[email protected]</email>
    </user>
    <paymentMethodID>114</paymentMethodID>
    <amount currencyCode="EUR">12</amount>
</getPaymentInputDataRequest>

getPaymentInputDataResponse sample:

<getPaymentInputDataResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <paymentInputData>
        <data xsi:type="keyStringValuePair">
            <key>UserVirtualAccountNumber</key>
            <value>355 349 995</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ExternalProviderReferenceID</key>
            <value>10241</value>
        </data>
        <data xsi:type="keyDecimalValuePair">
            <key>Amount</key>
            <value>12</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>CurrencyCode</key>
            <value>EUR</value>
        </data>
    </paymentInputData>
</getPaymentInputDataResponse>

Possible paymentInputData key in getPaymentInputDataResponse. All data has to be shown to the customer (user) on the merchant`s cashier/checkout site:

Detail Key

Description

UserVirtualAccountNumber

The virtual account number of the user. It represents the Account number entered in the Multibanco form.

ExternalProviderReferenceID

The provider reference ID. It represents the Multibanco Entity (Entidade).

Amount

The amount of the payment

CurrencyCode

The currency of the payment

Please note that after calling getPaymentInputData, a payment is created in state PendingOnProvider.

Upon deposit by the user, PXP will receive a notification from provider and the payment state will change to DepositedByProvider.

Notifications

The payment on the merchant site should be created based on the userID received in the notification.

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Possible payment states in asychronous handlePaymentStateChangedNotificationRequest:

Payment States

Description

DepositedByProvider (29)

Success state; deliver goods/services

Sample DepositedByProvider state notification request:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>XZXXXX</merchantID>
        <shopID>XXXX</shopID>
        <paymentMethod>
            <key>114</key>
            <value>MultibancoDeposit</value>
        </paymentMethod>
        <merchantTransactionID>bb168d79-da4f-4a64-a366-24fb5efecddd</merchantTransactionID>
        <paymentID>3eb8ad2f-a2c9-4256-a139-72f6edba6211</paymentID>
        <userID>00d38765-fb45-4303-81e1-6dd7a7</userID>
        <paymentProvider>
            <key>82</key>
            <value>Multibanco</value>
        </paymentProvider>
        <amount currencyCode="EUR">23.5000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>b4f62e9b-b6d9-4dc2-ad02-1b7d2fd4ec93</id>
            <definition>
                <key>29</key>
                <value>DepositedByProvider</value>
            </definition>
            <createdOn>2021-10-05T15:47:22.06</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>authorized</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">23.5000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>38218743</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>800097509476</value>
            </detail>
        </paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>