Meo Wallet

Meo Wallet

MB WAY Mandates

The MB WAY service provides a special feature “Mandates” (the official name is “MB WAY Pagamentos Autorizados”) to complete payments without using the MB WAY PIN.

Below, you can find a list of API endpoints where you can create, search and delete mandates.

/api/v2/mandate/mbway

To be able to use this API, you must authenticate using your merchant API Key. Details here.

Create mandate

With this API, you can create ONECLICK and SUBSCRIPTION mandates. A notification will be sent to your customer mobile phone.

You specify the required kind in the type field of the payload data. After the user approval at the MB WAY app, the next purchases will be completed without the requirement of entering the MB WAY PIN for each transaction.

With SUBSCRIPTION mandates, merchants can initiate recurrent payments up to a pre determinate amount monthly (can be changed by the MB WAY user to a different amount between the configured interval at SIBS). Use the “subscription_id” of the response to charge the subscription. The amount you can charge depends on the mandate amount.

If you try to send a valid number, but not registered at the MB WAY service, you will get a 10002 error code. Check full list of errors here.

Request POST /api/v2/mandate/mbway
Query params none
Data params MBWayMandateRequest
Returns MBWayMandateResponse
Click here for an example of a ONECLICK mandate creation 
curl -X POST https://services.wallet.pt/api/v2/mandate/mbway \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d ' {
    "name": "Maria Francisca",
    "phone": "+351111111111",
    "type": "ONECLICK",
    "url_callback": "https://example.com/callback",
    "request_id": "123456789"
  }
'
Returns 
{
    "state":"REQUESTED",
    "mandate_id":"03170506383676259651"
}


Click here for an example of a SUBSCRIPTION mandate creation 
curl -X POST https://services.wallet.pt/api/v2/mandate/mbway \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d ' {
    "name": "Maria Francisca",
    "phone": "+351111111111",
    "type": "SUBSCRIPTION",
    "url_callback": "https://example.com/callback",
    "request_id": "1234567890"
  }
'
Returns 
{
    "state":"REQUESTED",
    "mandate_id": "03170569102864772482",
    "subscription_id": "dd6cc818-a622-11f1-a1f4-f2ecbea4cef4"
}


You can pass a request_id to track this request. Check the Idempotency page.

A callback will be sent with a reference to the mandate.


Get mandate status

Request GET /api/v2/mandate/mbway/mandate_id
Query params none
Data params none
Returns Mandate
Click here for an example of a get mandate 
curl -X GET https://services.wallet.pt/api/v2/mandate/mbway/03170506383676259651 \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
Returns 
{
    "amount_available":100,
    "amount_limit":100,
    "client_name":"Maria Francisca"
    "creation_date":"2026-09-02 14:31:10",
    "expiry_date":"2029-05-31",
    "mandate_id":"03170506383676259651",
    "phone":"+351 123456789",
    "state":"ACTIVE",
    "subscription_id":"f1593c5e-a6da-11f1-b800-f0ecbea4cef4",
    "type":"SUBSCRIPTION",
}


List mandates

Request GET /api/v2/mandate/mbway
Query params search query
Data params none
Returns a json list of Mandate

The query string consists of a list of key value pairs in which the value is url encoded, notably the phone number, which must start with “+”

Param Type Repeatable
end_creation_date ISO-8601 date N
end_expiry_date ISO-8601 date N
limit how many results in page N
offset result page N
phone phone number N
start_creation_date ISO-8601 date N
start_expiry_date ISO-8601 date N
status one of states Y
type ONECLICK or SUBSCRIPTION N
wallet_id wallet id retrieved from the MEO Wallet backoffice Y

Failure to specify a query string will result in all mandates being returned paginated.

Click here for an example of a list mandates query 
curl -X GET https://services.wallet.pt/api/v2/mandate/mbway/?state=ACTIVE&state=REQUESTED \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
Returns 
{
    {
        "amount_available":100,
        "amount_limit":100,
        "client_name":"Maria Francisca"
        "creation_date":"2026-09-02 14:31:10",
        "expiry_date":"2029-05-31",
        "mandate_id":"03170506383676259651",
        "phone":"+351 123456789",
        "state":"ACTIVE",
        "subscription_id":"f1593c5e-a6da-11f1-b800-f0ecbea4cef4",
        "type":"SUBSCRIPTION",
    },
    ...
}


Delete mandate

Request DELETE /api/v2/mandate/mbway/mandate_id
Query params none
Data params none
Returns none
Click here for an example of a mandate deletion 
curl -X DELETE https://services.wallet.pt/api/v2/mandate/mbway/03170506383676259651 \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \


A callback will be sent with a reference to the mandate.

Callbacks

There are the possible callbacks sent:

Status Description
APPROVED Mandate approved by the customer on the MB WAY app
UPDATED Mandate configuration changed by the customer (amount or expiration date) on the MB WAY app
EXPIRED Mandate expired
VOIDED Mandate deleted by the merchant
SUSPENDED Mandate suspended by the customer on the MB WAY app
Click here for payload examples 
{
    "max_amount": 20,
    "request_id": "request_134154",
    "method": "MBWAY",
    "mandate_type": "SUBSCRIPTION",
    "amount_available": 20,
    "event": "APPROVED",
    "end_date": "2029-09-30",
    "subscription_id": "d10249ee-a7bd-11f1-bda2-eeecbea4cef4",
    "type": "MANDATE",
    "mandate_id": "03170571441693777272"
}
{
    "subscription_id": "d10249ee-a7bd-11f1-bda2-eeecbea4cef4",
    "amount_available": 200,
    "end_date": "2029-09-30",
    "event": "UPDATED",
    "type": "MANDATE",
    "mandate_id": "03170571441693777272",
    "max_amount": 200,
    "request_id": "request_134154",
    "method": "MBWAY",
    "mandate_type": "SUBSCRIPTION"
}