MBWay

MB WAY is an asynchronous mobile wallet widely used in Portugal and managed by SIBS. Customers authorize payments in the MB WAY app with the phone number registered at their bank. They never enter or expose card details during checkout.

After you create the payment, MB WAY sends a push notification to the customer's mobile device. The customer opens the MB WAY app to approve or decline the payment.

This guide shows you how to integrate MB WAY payments. It covers one-time payments, expiration handling, Recurring and One Click Buy payments, refunds, cancellations, webhooks, and status checks.

Important: MB WAY is asynchronous. The initial API response returns WAITING, which means Getnet created the payment request and it awaits customer authorization. The MB WAY notification expires 4 minutes and 30 seconds after the payment intent is created. You get the final payment status through a webhook or by polling the Get Transaction endpoint.

Requirements

Before you integrate MB WAY, complete the following:

• Generate an access token through the Authentication endpoint.
• Make sure your seller account is enabled for MB WAY.
• Collect the customer's MB WAY-enabled phone number during checkout.
• For Recurring and One Click Buy payments, also collect the customer's name.
• Implement webhook event handling or payment status polling.
• Make sure your integration doesn't fulfill the order while the payment status is WAITING.

To enable MB WAY, contact your Account Manager. They validate eligibility and activate the payment method for your seller account.

Check Market Requirements

Review the resources below for Portugal before you go live:

• Currency codes
• Document types
• Local taxes and regulations

Characteristics

The table below summarizes the shared behavior and requirements for MB WAY payments.

After you create the payment request, MB WAY sends a push notification to the customer's device. The customer opens the MB WAY app to approve or decline the payment. You receive status updates through webhooks, or you can retrieve them with the Get Transaction endpoint.

Available Features

Use the matrix below to confirm the scenarios currently supported for MB WAY.

Payment Flow

This section walks you through a one-time MB WAY payment. It starts with collecting the customer's phone number and ends with handling the response, expiration, and final status.

The diagram below provides an overview of an MB WAY payment and its possible outcomes:

1. Create the Payment Request

MB WAY uses an asynchronous wallet flow. First, add a payment form to your frontend that collects the customer's MB WAY-enabled phone number.

After you collect it, call the Create – Authorize endpoint with the attributes below.

The table outlines the minimum fields required for an MB WAY payment.

Phone number format: Use countryCode#phoneNumber, for example 351#912345678. Don't include the + symbol, spaces, parentheses, or hyphens. The country code must contain 1 to 4 digits. The phone number must contain 6 to 15 digits.

Valid example:

Invalid examples:

The following sample request creates an MB WAY payment with only the minimum required customer information.

You can also include customer, billing, and shipping information when risk, compliance, fraud prevention, or local configuration requires it.

2. Review the Response

The table below describes the main response fields.

Use the status field to track the payment lifecycle. Don't use reason_code alone to decide whether to fulfill the order.

3. Wait for Customer Approval

After the API call, the following sequence occurs:

1. Payment request: Getnet creates the payment and returns the initial WAITING status.
2. Push notification: MB WAY sends a notification to the customer's registered mobile device.
3. MB WAY app: The customer opens the MB WAY app and reviews the merchant and payment information.
4. Customer action:
   • Approves payment → Status becomes APPROVED, and Getnet sends an APPROVED_TRANSACTIONS webhook event.
   • Declines or rejects payment → Status becomes DECLINED, and Getnet sends a REJECTED_TRANSACTIONS webhook event.
   • Doesn't respond within 4 minutes and 30 seconds → The notification expires, and Getnet can send a REJECTED_TRANSACTIONS webhook event.
5. Payment confirmation: Getnet receives the result and updates the payment status asynchronously.
6. Order fulfillment: You fulfill the order only after you confirm the final APPROVED status.

The customer has 4 minutes and 30 seconds from the creation of the payment intent to authorize the payment. The countdown starts when the payment intent is created, not when the customer opens the MB WAY app.

4. Handle Payment Expiration

The customer must approve the payment in the MB WAY app within the authorization period. After the notification expires, the customer can't use that payment request anymore.

If the customer doesn't complete the payment within the authorization period:

1. Don't fulfill the order.
2. Wait for the final payment status through a webhook, or query the Get Transaction endpoint.
3. Create a new payment request if the customer wants to try again.

Important: Don't assume the payment failed only because the checkout countdown ended. Always confirm the final transaction status through a webhook or the Get Transaction endpoint.

5. Verify the Payment Status

When the customer approves, declines, or doesn't complete the payment, Getnet sends a webhook with the updated status.

Use status polling as a fallback when:

• Webhook delivery is delayed.
• You don't receive a webhook.
• The customer returns to the checkout before the final webhook is processed.
• You need to reconcile an uncertain payment result.

Avoid excessive polling. Use a reasonable interval and stop polling after you receive a final payment status.

Recurring and One Click Buy Payments

MB WAY supports two types of stored payment: Recurring Transactions and One Click Buy Transactions. Both follow the same flow. The customer approves an initial authorization once in the MB WAY app and sets a maximum monthly limit. You then charge subsequent payments within that limit, without asking the customer to approve each one.

Choose a Transaction Type

Both types accept variable amounts in subsequent payments. Subscriptions often charge the same amount every time, but Getnet doesn't require it. Getnet processes any amount within the monthly limit the customer set in the MB WAY app.

How It Works

The flow has two stages: one authorization that the customer approves, then any number of subsequent payments.

1. You create the initial authorization through the Create – Authorize endpoint with RECURRING or ONE_CLICK.
2. Getnet returns the WAITING status and a transaction_id. Store the transaction_id securely.
3. MB WAY sends a push notification to the customer's mobile device.
4. The customer opens the MB WAY app, sets the maximum monthly limit, and approves the authorization.
5. You create subsequent payments with the stored transaction_id and RECURRING_PAYMENT or ONE_CLICK_PAYMENT. Each payment must stay within the customer's limit.

Important: The customer must approve the initial authorization within 10 minutes of its creation. After that, you can't use the authorization and must create a new one.

1. Create the Initial Authorization

The following sample request creates the initial authorization for a Recurring Transaction.

Important: The initial authorization doesn't charge the customer, so amount is optional. If you don't send it, the response returns amount as 0.

Important: Don't treat the initial authorization as a completed payment. It sets up the monthly limit and doesn't represent a charge.

2. Wait for the Customer to Set the Limit

The customer interacts with MB WAY only during this setup step. In the MB WAY app, the customer:

• Receives a push notification.
• Reviews the authorization.
• Sets the maximum monthly limit for future payments.
• Approves the authorization.

Getnet doesn't charge the customer during this step. After approval, you charge subsequent payments without asking the customer to approve each one. Each amount must stay within the limit.

Keep the following in mind after setup:

• The authorization may expire, the customer may revoke it, or it may become unavailable for operational reasons.
• Each subsequent payment is an independent transaction, with its own lifecycle and status.

3. Create a Subsequent Payment

To charge the customer, send a new request with the fields below. Each payment must stay within the limit the customer set.

The following sample request charges €10.00 against the Recurring Transaction authorization created above.

A successful subsequent payment returns its own transaction response and status. The response below is for the Recurring Transaction request. A One Click Buy subsequent payment returns the same fields.

Webhooks

Use webhooks to receive asynchronous status updates for MB WAY payments. Use webhooks in production, and use status polling only as a fallback.

To learn how to configure and receive webhook notifications, see the Webhooks guide.

Getnet may deliver a webhook event more than once. Process each notification idempotently, and use the payment_id to match the event to the original payment request.

Your webhook implementation should:

• Validate the webhook according to the security mechanism described in the Webhooks guide.
• Return a successful HTTP response after processing the event.
• Support repeated delivery of the same event.
• Process notifications idempotently.
• Use payment_id or order_id to match the notification to the original payment.
• Retrieve the transaction through the Get Transaction endpoint when the result is uncertain.

Status Reference

The table below describes the MB WAY payment statuses and their webhook events.

Treat only APPROVED as confirmation that a payment is complete.

Refunds and Cancellations

MB WAY payments support both cancellations and refunds:

• Cancellations: Available for eligible same-day transactions before the daily cutoff time. MB WAY supports only full cancellations.
• Refunds: Available for eligible transactions after settlement. MB WAY supports full, partial, and multiple refunds.
• Refund period: You can request refunds for up to 15 months from the original payment date.

The total refunded amount can't exceed the original payment amount.

To process a refund or cancellation, follow the instructions in the Refund a Payment guide.

For eligibility, settlement requirements, cutoff times, and country availability, see the payment method availability reference.

Best Practices

Follow these recommendations when you implement MB WAY:

• Collect the phone number in the countryCode#phoneNumber format.
• Validate the phone number format before you send the request.
• Tell the customer to open the MB WAY app after you create the payment.
• Keep the checkout page available while the payment awaits customer authorization.
• Display a countdown based on the 4-minute-and-30-second authorization period.
• Start the countdown when the payment intent is created, not when the customer opens the MB WAY app.
• Don't classify the payment as declined automatically when the checkout countdown ends.
• Confirm the final status through a webhook or the Get Transaction endpoint.
• Create a new payment request if the notification expires and the customer wants to retry.
• Don't fulfill the order while the status is WAITING.
• Use webhooks in production and status polling only as a fallback.
• Process webhook events idempotently, because Getnet may deliver the same notification more than once.
• Store payment_id, order_id, transaction_id, amount, and the final payment status for reconciliation.
• Use a unique idempotency_key for every payment attempt.
• Don't reuse an idempotency key with different request data.
• Make sure refund workflows enforce the maximum period of 15 months from the original payment date.
• Let the customer choose another payment method when the payment is declined or can't be completed.
• Use Recurring Transactions for subscriptions and payment plans, and One Click Buy Transactions for one-off purchases.
• For Recurring and One Click Buy payments, store the transaction_id from the initial authorization securely and send it in every subsequent payment.
• Keep each subsequent payment within the monthly limit the customer authorized.
• Monitor authorizations, because they may expire, the customer may revoke them, or they may become unavailable.

Next Steps

Use these resources to continue your MB WAY integration.

• Review Authentication for token management and security best practices.
• Review the Get Transaction endpoint to check the payment status.
• Review the Webhooks guide for asynchronous payment notifications.
• Review the Refund a Payment guide for refund and cancellation instructions.