MB WAY

DocsBeta

Last updated: Sept 19th, 3:20am

MB WAY is a local payment method that a customer can use to place an order and then complete the payment with their MB WAY mobile digital wallet app.

Countries Payment type Payment flow Currencies Maximum amount Refunds
Portugal (PT) wallet redirect EUR N/A Within 395 days

How it works

Alternative,payment,methods,diagram
  1. Your checkout page offers alternative payment methods.
  2. Buyer provides their personal details and selects an alternative payment method from your checkout page.
  3. Buyer is transferred from your checkout page to the third-party bank to confirm the purchase.
  4. Buyer authorizes and confirms payment.
  5. Buyer returns to your site to see confirmation of purchase.
  6. Merchant initiates completion of payment. PayPal moves the funds to the merchant. Transaction shows in your PayPal account with the payment method the buyer used.

Eligibility

  • Available to merchants globally, except in Russia, Japan, and Brazil.
  • Billing agreements, multiple seller payments, and shipping callback aren't supported.
  • Support for order capture only (order authorize is not supported). See authorized and captured payments.
  • Chargebacks aren't supported.
  • Transaction must be an online purchase (buy online, pay in store is not supported).

Know before you code

  • The steps to implementing all alternative payment methods using the Orders V2 REST API are similar. If you've implemented an alternative payment method previously, you can likely use that code and adjust it for the specific differences for MB WAY.
  • Make sure you're subscribed to the following webhook events:
    • The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.
    • The PAYMENT.CAPTURE.DENIED webhook event indicate a failed order capture.

Upon receiving each webhook, fetch the latest order details using Show order details. The up HATEOAS link in the webhook payload indicates the order associated with the capture.

  • When processing MB WAY payments, capture payment for order is not required.

1. Offer MB WAY on your checkout page

You'll need to create the user interface to offer MB WAY and collect the buyer's full name and phone number. Then you'll use the API calls described in the remainder of this topic to:

  • Create the order with MB WAY as the payment method and the buyer's full name, country_code, and phone.
  • The buyer receives a notification in the MB WAY mobile app to fulfill the payment.
  • (Optional) brand_name is supported in create order.

Refer to Payment method icons for icons you can use and download locations.

2. Create an order with MB WAY as the payment source

Use the buyer information you captured from your user interface to create an order with MB WAY as the payment source.

Sample request

API endpoint used: Create order

    1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
    2--header 'Content-Type: application/json' \
    3--header 'Authorization: Bearer <Access-Token>' \
    4--header 'PayPal-Request-Id: <PayPal-RequestId>' \
    5--data-raw '{
    6    "intent": "CAPTURE",
    7    "payment_source": {
    8        "mbway": {
    9            "country_code": "PT",
    10            "name": "Firstname Lastname",
    11            "phone": {
    12              "national_number": "1234567890",
    13              "country_code": "351",
    14            },
    15            "experience_context": {
    16              "brand_name": "brand name override"
    17            }
    18        }
    19    },
    20    "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
    21    "purchase_units": [
    22        {
    23            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
    24            "amount": {
    25                "currency_code": "EUR",
    26                "value": "100.00"
    27            }
    28        }
    29    ]
    30}'

    Modify the code

    After you copy the code in the sample request, modify the following:

    • Access-Token - Your access token.
    • PayPal-Request-Id - Replace the sample ID with a unique ID you generate. This ID helps prevent duplicate authorizations in the event that the API call is disrupted. See also: API idempotency.
    • intent - This parameter must be set to CAPTURE as it is in this sample code.
    • payment_source - Specify the following:
      • mbway as the payment_source and include the country_code.
      • buyer's full name in the name field.
      • buyer's phone number associated with MB WAY in the national_number field and country code in the country_code field.
      • experience_context - Specify the brand name in the brand_name field.
    • processing_instruction - Set this value to ORDER_COMPLETE_ON_PAYMENT_APPROVAL as it is in this sample code.
    • purchase_units: amount - Pass the amount of the order and the currency code.
    • reference_id - Provide the ID for the purchase unit.

    Step result

    A successful request results in the following:

    • A return status code of HTTP 200 OK.
    • A JSON response body that contains the order ID. You'll use the order ID and payer-action HATEOAS URL in the next step. See also: HATEOAS links.

    Sample response

      1{
      2    "id": "5V159329PV571861D",
      3    "status": "PAYER_ACTION_REQUIRED",
      4    "payment_source": {
      5        "mbway": {
      6            "name": "Firstname Lastname",
      7            "country_code": "PT"
      8        }
      9    },
      10    "links": [
      11        {
      12            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
      13            "rel": "self",
      14            "method": "GET"
      15        }
      16    ]
      17}

      3. No redirection of buyer to approve purchase

      MB Way sends a push notification directly to the buyer's mobile app. The buyer stays on your website while approving the transaction in the mobile app, and no redirection action is required. After the buyer approves the purchase, the payment is automatically captured.

      4. Listen to webhooks to get the result of payment status

      Listen to the following webhooks to get the result of order capture:

      • The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.
      • The PAYMENT.CAPTURE.DENIED and CHECKOUT.PAYMENT-APPROVAL.REVERSED webhook events indicate a failed order capture.
      • Optional: Use the Show order details endpoint to determine the status of an order.
        • The up HATEOAS link indicates the order associated with this capture.

      See Subscribe to checkout webhooks for more information.

      Here are some additional resources as you create webhook handler code:

      Sample PAYMENT.CAPTURE.COMPLETED webhook

        1{
        2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
        3  "event_version": "1.0",
        4  "create_time": "2022-05-10T06:04:12.533Z",
        5  "resource_type": "capture",
        6  "resource_version": "2.0",
        7  "event_type": "PAYMENT.CAPTURE.COMPLETED",
        8  "summary": "Payment completed for EUR 100.0 EUR",
        9  "resource": {
        10    "amount": {
        11      "value": "100.00",
        12      "currency_code": "EUR"
        13    },
        14    "supplementary_data": {
        15      "related_ids": {
        16        "order_id": "5V159329PV571861D"
        17      }
        18    },
        19    "update_time": "2022-01-19T06:04:08Z",
        20    "create_time": "2022-01-19T06:04:08Z",
        21    "final_capture": true,
        22    "seller_receivable_breakdown": {
        23      "paypal_fee": {
        24        "value": "3.80",
        25        "currency_code": "EUR"
        26      },
        27      "gross_amount": {
        28        "value": "100.00",
        29        "currency_code": "EUR"
        30      },
        31      "net_amount": {
        32        "value": "96.20",
        33        "currency_code": "EUR"
        34      }
        35    },
        36    "custom_id": "Custom-1234",
        37    "invoice_id": "Invoice-12345",
        38    "links": [
        39      {
        40        "method": "GET",
        41        "rel": "self",
        42        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
        43      },
        44      {
        45        "method": "POST",
        46        "rel": "refund",
        47        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
        48      },
        49      {
        50        "method": "GET",
        51        "rel": "up",
        52        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
        53      }
        54    ],
        55    "id": "5R102774VL663561J",
        56    "status": "COMPLETED"
        57  },
        58  "links": [
        59    {
        60      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
        61      "rel": "self",
        62      "method": "GET"
        63    },
        64    {
        65      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
        66      "rel": "resend",
        67      "method": "POST"
        68    }
        69  ]
        70}

        Sample PAYMENT.CAPTURE.DENIED webhook

          1{
          2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
          3  "event_version": "1.0",
          4  "create_time": "2022-05-10T06:04:12.533Z",
          5  "resource_type": "capture",
          6  "resource_version": "2.0",
          7  "event_type": "PAYMENT.CAPTURE.DENIED",
          8  "summary": "Payment denied for EUR 100.0 EUR",
          9  "resource": {
          10    "amount": {
          11      "value": "100.00",
          12      "currency_code": "EUR"
          13    },
          14    "supplementary_data": {
          15      "related_ids": {
          16        "order_id": "5V159329PV571861D"
          17      }
          18    },
          19    "update_time": "2022-05-10T06:04:08Z",
          20    "create_time": "2022-05-10T06:04:08Z",
          21    "final_capture": true,
          22    "seller_receivable_breakdown": {
          23      "paypal_fee": {
          24        "value": "3.80",
          25        "currency_code": "EUR"
          26      },
          27      "gross_amount": {
          28        "value": "100.00",
          29        "currency_code": "EUR"
          30      },
          31      "net_amount": {
          32        "value": "96.20",
          33        "currency_code": "EUR"
          34      }
          35    },
          36    "links": [
          37      {
          38        "method": "GET",
          39        "rel": "self",
          40        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
          41      },
          42      {
          43        "method": "POST",
          44        "rel": "refund",
          45        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
          46      },
          47      {
          48        "method": "GET",
          49        "rel": "up",
          50        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
          51      }
          52    ],
          53    "id": "5R102774VL663561J",
          54    "status": "DECLINED"
          55  },
          56  "links": [
          57    {
          58      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
          59      "rel": "self",
          60      "method": "GET"
          61    },
          62    {
          63      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
          64      "rel": "resend",
          65      "method": "POST"
          66    }
          67  ]
          68}

          Alternatively, you can get the order capture result from the Show order details endpoint.

          Sample request

            1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D \
            2 -H "Content-Type: application/json" \
            3 -H "Authorization: Bearer <Access-Token>"

            Sample response

              1{
              2  "id": "5V159329PV571861D",
              3  "intent": "CAPTURE",
              4  "status": "COMPLETED",
              5  "payment_source": {
              6    "mbway": {
              7      "name": "Firstname Lastname",
              8      "country_code": "PT"
              9    }
              10  },
              11  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
              12  "purchase_units": [
              13    {
              14      "reference_id": "default",
              15      "amount": {
              16        "currency_code": "EUR",
              17        "value": "100.00"
              18      },
              19      "payments": {
              20        "captures": [
              21          {
              22            "id": "5R102774VL663561J",
              23            "status": "COMPLETED",
              24            "amount": {
              25              "currency_code": "EUR",
              26              "value": "100.00"
              27            },
              28            "final_capture": true,
              29            "seller_receivable_breakdown": {
              30              "gross_amount": {
              31                "currency_code": "EUR",
              32                "value": "100.00"
              33              },
              34              "paypal_fee": {
              35                "currency_code": "EUR",
              36                "value": "3.80"
              37              },
              38              "net_amount": {
              39                "currency_code": "EUR",
              40                "value": "96.20"
              41              }
              42            },
              43            "links": [
              44              {
              45                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J",
              46                "rel": "self",
              47                "method": "GET"
              48              },
              49              {
              50                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund",
              51                "rel": "refund",
              52                "method": "POST"
              53              },
              54              {
              55                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
              56                "rel": "up",
              57                "method": "GET"
              58              }
              59            ]
              60          }
              61        ]
              62      }
              63    }
              64  ],
              65  "links": [
              66    {
              67      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
              68      "rel": "self",
              69      "method": "GET"
              70    }
              71  ]
              72}

              Step result

              A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.

              A successfully captured order has the following:

              • The order status as COMPLETED, which means the order was captured successfully.
              • A capture with COMPLETED status is present in the response parameter purchase_units[0].payments.captures[0].
              • The up HATEOAS link indicates the order associated with this capture.

              4. Notify buyer of success

              After a successful payment, notify the buyer of a successful transaction. You can do this by sending a confirmation email.

              Next steps

              Use these buyer phone numbers to simulate the failure scenarios in the PayPal sandbox environment.

              Scenario Buyer phone national_number
              The phone number provided is not associated with MB WAY 111111111
              The buyer has canceled/denied the payment 222222222

              Any buyer phone number not listed in the table will simulate a successful scenario in the PayPal sandbox environment.

              ReferencePayPal.comPrivacyCookiesSupportLegalContact

              We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies