MB Way Pagamentos Autorizados

PRESENTATION

MB Way provides a seamless and secure mobile payment experience. For mandates, customers authorize future payments by approving a request in their MB Way app, linking their phone number to the mandate creation.

ESSENTIAL INFORMATION

POPULARITY AND AVAILABILITY

MB Way is the leading mobile payment solution in Portugal, widely adopted and trusted by Portuguese consumers for both one-off and recurring payments.

PROCESS

The mandate creation process is initiated by the customer entering their phone number. They then receive a notification in the MB Way app to approve the mandate, which authorizes the merchant to initiate future payments. The mandate creation is done regardless of a transaction.

SECURITY

Transactions are highly secure, as the approval happens within the customer's personal MB Way app using their PIN or biometric authentication. The merchant only handles the phone number, not sensitive bank details.

COMPATIBILITY

MB Way is compatible with all major browsers. The customer must have the MB Way app installed on their smartphone.

CONFIGURATION AND COMPLIANCE

Before integration, ensure your HiPay account is configured for Portugal. This method only supports transactions in EUR. The customer's phone number is a mandatory field for this payment method.

USE CASES

Ideal for subscription models, recurring billing, and one-click services targeting a Portuguese customer base.

INTEGRATION

INTEGRATION METHODS

USER EXPERIENCE (Mandate Creation)

1. The customer selects MB Way on the merchant site.
2. The customer enters their phone number associated with their MB Way account.
3. The customer receives a push notification on their smartphone.
4. The customer opens the MB Way app, reviews the mandate details, and authorizes it with their PIN or biometrics.
5. The mandate is successfully created. The merchant receives a confirmation via an asynchronous notification (webhook) (see section "Mandate Status Notifications (Webhooks)" below).
6. The customer is redirected to the merchant's confirmation page.
7. Once the mandate is activated, for all subsequent transactions using this mandate, the customer will not need to confirm the transaction on their app.

ORDER API INTEGRATION

MANDATORY PARAMETERS

ENDPOINTS

NOTE: Ensure that your HiPay account and redirection URLs are correctly configured to guarantee proper integration.

MB Way Mandates Sample request

curl --location 'https://stage-api-gateway.hipay.com/v3/debit-agreement/mbway' \
--header 'Content-Type: application/x-www-form-urlencode' \
--header 'Authorization:******' \
--form 'currency="EUR"' \
--form 'firstname="Sofia"' \
--form 'lastname="COSTA"' \
--form 'phone="33#612345678"' \
--form 'cof_type="RECURRING"' \

Mandate Status Notifications (Webhooks)

To monitor the status of your Debit Agreements (mandates) in real-time, you must configure your system to receive asynchronous notifications (webhooks). These are essential to know when a mandate is successfully created, suspended, or deleted.

1. Configuration

You must provide a callback URL in your HiPay back-office in the svnotif.url field. Our system will send an HTTP POST request to this URL for each event.

Your server must reply with an HTTP 200 OK status code to acknowledge receipt of the notification. Any other response (4xx, 5xx, or a timeout of 3 seconds) will be considered a failure, and HiPay will attempt to send the notification again.

Note: In case of doubt, or to reconcile the status of a mandate after receiving a notification, you can consult its information at any time using the GET /v3/debit-agreement/{debit_agreement_id} endpoint

2. Notification Format

You will receive a JSON payload in the body of the POST request.

Structure:

{
  "key": "string",
  "data": { ... Debit Agreement object ... },
  "sent_date": "timestamp:1761734585891"
}

• key (string): The event identifier (object.status).
• data (json): The full Debit Agreement object, identical to a GET API call.
• sent_date (timestamp): The timestamp (UTC) of when the notification was sent.

data Object structure

3. Events to Listen For (key)

These are the key values your system should monitor. Events are triggered by a status change, except for debit_agreement.updated.

• debit_agreement.pending: Sent when the mandate has been authorized by the customer, but is awaiting final processing or bank confirmation before becoming active.
• debit_agreement.available: Sent when the mandate becomes fully active and ready to be used for payments. This can occur directly at creation or after a pending status.
• debit_agreement.suspended: Sent if the mandate is suspended (e.g., by the customer from their bank app).
• debit_agreement.terminated: Sent if the mandate is permanently terminated or deleted.
• debit_agreement.updated: Sent only if a mandate's properties (like phone number) are modified without a change in its status (e.g., status remains available).

4. Notification Examples

Example 1: Mandate created as Pending (debit_agreement.pending)

This is sent just after the customer approves the mandate. The mandate exists but is not yet active.

{
  "key": "debit_agreement.pending",
  "data": {
    "id": 12182120,
    "status": "pending",
    "properties": {
      "currency": "EUR",
      "firstname": "Sofia",
      "lastname": "COSTA",
      "phone": "351#919008994"
    },
    "cof_type": "RECURRING",
    "date_created": "2025-10-27T11:05:50+01:00"
  },
  "sent_date": "1761734585891"
}

Example 2: Mandate created or becomes Available (debit_agreement.available)

This is sent when the mandate status changes from pending to available. (Note: For some flows, a mandate might be created directly as available, triggering this notification immediately).

{
  "key": "debit_agreement.available",
  "data": {
    "id": 12182120,
    "status": "available",
    "properties": {
      "currency": "EUR",
      "firstname": "Sofia",
      "lastname": "COSTA",
      "phone": "351#919008994"
    },
    "cof_type": "RECURRING",
    "date_created": "2025-10-27T11:05:50+01:00"
  },
  "sent_date": "1761734585891"
}

Example 3: Mandate Suspended (debit_agreement.suspended)

Sent if the customer revokes the mandate from their app. You should stop initiating payments for this mandate

{
  "key": "debit_agreement.suspended",
  "data": {
    "id": 12182120,
    "status": "suspended",
    "properties": {
      "currency": "EUR",
      "firstname": "Sofia",
      "lastname": "COSTA",
      "phone": "351#919008994"
    },
    "cof_type": "RECURRING",
    "date_created": "2025-10-27T11:05:50+01:00"
  },
  "sent_date": "1761734585891"
}

Example 4: Mandate Terminated (debit_agreement.terminated)

Sent when the mandate is permanently deactivated.

{
  "key": "debit_agreement.terminated",
  "data": {
    "id": 12182120,
    "status": "terminated",
    "properties": {
      "currency": "EUR",
      "firstname": "Sofia",
      "lastname": "COSTA",
      "phone": "351#919008999"
    },
    "cof_type": "RECURRING",
    "date_created": "2025-10-27T11:05:50+01:00"
  },
  "sent_date": "1761734585891"
}

Example 5: Mandate Updates - Property Change (debit_agreement.updated)

This event is sent only if properties change, but the status does not. Here, the phone number is updated while the status remains available.

{
  "key": "debit_agreement.updated",
  "data": {
    "id": 12182120,
    "status": "available",
    "properties": {
      "currency": "EUR",
      "firstname": "Sofia",
      "lastname": "COSTA",
      "phone": "351#919008111"
    },
    "cof_type": "RECURRING",
    "date_created": "2025-10-27T11:05:50+01:00"
  },
  "sent_date": "1761734585891"
}

5. Retry Mechanism

If our system does not receive an HTTP 200 OK from your server:

1. Initial Retries: We will automatically retry 3 times (at 1 minute, 3 minutes, and 5 minutes).
2. Delayed Retries: If all 3 attempts fail, a robust delayed-retry mechanism (using a 15-minute Time-To-Live) will re-queue the message for several additional attempts over the next hour before flagging the notification as undeliverable.