MBWay is the leading e-wallet product in Portugal. In May 2021 there were over 3.5 million MB Way users, with the amount steadily growing each quarter. 50% of Portuguese bank customers have MB Way.

Payment Method Properties


Markets	`PT`
Processing currencies	`EUR`
Consumer currencies	`EUR`
Settlement currencies	`EUR`
Minimum payment amount	0.01€
Maximum payment amount	5000€
Recurring payments	To be checked
Separate captures	To be checked
Refund	Full - Partial - Multiple Partial
Refund validity	120 days
Chargeback	Yes
Sandbox availability	Amazon Pay sandbox

Make an MB Way payment

To make an MB Way payment, you'll need to provide the following data when calling our /v1/payment-charges API:

Data Field	Required	Description
paymentMethod	Y	MBWAY
amount.value	Y	The amount to be paid in the smallest units of the currency used.
amount.currency	Y	EUR The currency used for the payment
consumer.name	Y	Full name of the consumer
consumer.country	Y	The country where the consumer is shopping
consumer.email	O	Email of the consumer
authenticationSettings: REDIRECT settings.returnUrl	Y	Specify the URL to which the consumer should be redirected after completing the payment

Request

POST /v1/payment-charges

{
    "id": "charge_sh7T8Q5E2eeuQFCQG0vA9",
    "paymentMethod": "MBWAY",
    "paymentMedium": "ECOMMERCE",
    "scheduleType": "UNSCHEDULED",
    "instrumentId": "instr_DJaPC86NWwMGuly1iXs7o",
    "currency": "EUR",
    "country": "PT",
    "paymentDescriptor": "Payment Descriptor",
    "status": "AUTHENTICATION_PENDING",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "country": "PT",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "01522113356",
            "street": "Hellersbergstraße 14",
            "postalCode": "41460",
            "city": "Berlin",
            "region": "Berlin",
            "country": "DE"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "Product Name 1",
                "quantity": 1,
                "amount": 100
            }
        ],
        "industryData": []
    },
    "authenticationMethods": [
        {
            "details": {
                "requestUrl": "https://authman.qa.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2Vfc2g3VDhRNUUyZWV1UUZDUUcwdkE5In19.Y6fx_XEi9ypvXzlReKzejIjsXPea5QT-jpjadODSZdsbHdpZ4U8aVvP1Sv31fmtmV7a1CVA4YOoui8_kyphOXA",
                "requestMethod": "GET"
            },
            "type": "REDIRECT"
        }
    ],
    "authorizations": [
        {
            "id": "authz_MIqrxBS0Zzrh4dbJnhkMd",
            "amount": 1,
            "status": "AUTHENTICATION_PENDING",
            "merchantPaymentChargeReference": "zZQDQPiFwSJdN1g",
            "createdAt": "2025-01-08T13:09:25.676Z",
            "updatedAt": "2025-01-08T13:09:25.676Z"
        }
    ],
    "captures": [],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-01-08T13:09:24.883Z",
    "updatedAt": "2025-01-08T13:09:25.676Z",
    "internalData": {
        "processorAuthorizationContext": {
            ".multibancoPaymentReference": "",
            ".formContext_2": "xsaW5nQWRkcmVzcyI6eyJDb3VudHJ5IjoiIiwiQ2l0eSI6IiIsIlBvc3RDb2RlIjoiIiwiU3RyZWV0MSI6IiIsIlN0cmVldDIiOiIifX0sIkFwaVZlcnNpb24iOiJ2MSIsIk1PVE8iOmZhbHNlfQ==",
            "providerTxId": "s2rTJ0U4gzjuQaMDdya2",
            ".numFormContext": "3",
            ".formContext_0": "eyJQYXltZW50TWV0aG9kIjpbIk1CV0FZIiwiUkVGRVJFTkNFIl0sIlRyYW5zYWN0aW9uU2lnbmF0dXJlIjoiZXlKMGVFbGtJam9pY3pKeVZFb3dWVFJuZW1wMVVXRk5SR1I1WVRJaUxDSnRZeUk2TkRrMk1qVXdMQ0owWXlJNk56SXlNalY5LmZwRVN3RGpHMndlbjlwdHh1TXBiNm1GNVRLT0FZUE5YMTcvZG51MFR5Kzg9LmV3L3hjWXFlU2l",
            "paymentPurpose": "zZQDQPiFwSJdN1g Payment Descriptor",
            ".formContext_1": "wdXJpQU9sbjJpY3RrRStjQWROUy9iWjdmWXZ5eEoxbXRkRlJSL2lWd29WSDFDVzlaYTNSZnkiLCJBbW91bnQiOnsiQW1vdW50IjowLjAxLCJDdXJyZW5jeSI6IkVVUiJ9LCJNYW5kYXRlIjp7Ik1hbmRhdGVBdmFpbGFibGUiOmZhbHNlfSwiQ3VzdG9tZXJJbmZvIjp7IkN1c3RvbWVyTmFtZSI6IiIsIkN1c3RvbWVyRW1haWwiOiIiLCJCaW",
            "forwardUrl": "https://www.ppro.com/",
            "returnUrl": "https://www.ppro.com/",
            "instrument.id": "instr_DJaPC86NWwMGuly1iXs7o",
            "failureUrl": "https://www.ppro.com/?isFailure=true"
        },
        "paymentOperationNumber": 160000454828,
        "paymentOperationShortCode": "700AI9G",
        "merchantId": "merchant-id",
        "autoCapture": false
    },
    "simpleApiPassthrough": {
        "specout": {
            ".numFormContext": "3",
            ".formContext_0": "eyJQYXltZW50TWV0aG9kIjpbIk1CV0FZIiwiUkVGRVJFTkNFIl0sIlRyYW5zYWN0aW9uU2lnbmF0dXJlIjoiZXlKMGVFbGtJam9pY3pKeVZFb3dWVFJuZW1wMVVXRk5SR1I1WVRJaUxDSnRZeUk2TkRrMk1qVXdMQ0owWXlJNk56SXlNalY5LmZwRVN3RGpHMndlbjlwdHh1TXBiNm1GNVRLT0FZUE5YMTcvZG51MFR5Kzg9LmV3L3hjWXFlU2l",
            "paymentPurpose": "zZQDQPiFwSJdN1g Payment Descriptor",
            ".formContext_1": "wdXJpQU9sbjJpY3RrRStjQWROUy9iWjdmWXZ5eEoxbXRkRlJSL2lWd29WSDFDVzlaYTNSZnkiLCJBbW91bnQiOnsiQW1vdW50IjowLjAxLCJDdXJyZW5jeSI6IkVVUiJ9LCJNYW5kYXRlIjp7Ik1hbmRhdGVBdmFpbGFibGUiOmZhbHNlfSwiQ3VzdG9tZXJJbmZvIjp7IkN1c3RvbWVyTmFtZSI6IiIsIkN1c3RvbWVyRW1haWwiOiIiLCJCaW",
            ".multibancoPaymentReference": "",
            ".formContext_2": "xsaW5nQWRkcmVzcyI6eyJDb3VudHJ5IjoiIiwiQ2l0eSI6IiIsIlBvc3RDb2RlIjoiIiwiU3RyZWV0MSI6IiIsIlN0cmVldDIiOiIifX0sIkFwaVZlcnNpb24iOiJ2MSIsIk1PVE8iOmZhbHNlfQ=="
        },
        "transientout": {}
    },
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_sh7T8Q5E2eeuQFCQG0vA9/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_sh7T8Q5E2eeuQFCQG0vA9/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_sh7T8Q5E2eeuQFCQG0vA9/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_sh7T8Q5E2eeuQFCQG0vA9/voids"
        }
    }
}

Response

You'll receive a standard payment agreement response (see potential responses in the API Reference)

{
    "merchantPaymentChargeReference": "{{$randomPassword}}",
    "paymentMethod": "MBWAY",
    "amount": {
        "value": 1,
        "currency": "EUR"
    },
    "paymentDescriptor": "Payment Descriptor",
    "consumer": {
        "name": "John Smith",
        "country": "PT",
        "email": "[email protected]",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "01522113356",
            "street": "Hellersbergstraße 14",
            "postalCode": "41460",
            "city": "Berlin",
            "region": "Berlin",
            "country": "DE"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "Product Name 1",
                "quantity": 1,
                "amount": 100
            }
        ]
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.ppro.com/"
            }
        }
    ]
}

Consumer Authentication

MBWay requires authentication by the consumer, which they do via their bank's online environment. You will need to redirect their browser to MBWay's payment page using the link provided in the requestUrl field of the REDIRECT authentication method response. On MBWay's payment page to choose their bank

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer logs into their bank and approves the payment. After this, the charge will transition to the CAPTURED state.

Handling the Payment Result

The consumer will be redirected to the authenticationMethods.settings.returnUrl provided in the initial payment charge creation request, depending on whether the authorization is a success, a failure, or if the user cancelled/aborted the flow.

If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED state.

You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED.