Multibanco References on demand

This is an extension only available to partner merchants. The API KEY must have specific permissions.

You can ask MEO Wallet for a MB reference via the API.

/api/v2/mb/pay

There are 3 types of references you can ask for: A regular reference associated with an amount, a time limited reference which is only payable during a defined period and a finer grained time limited reference (instant reference).

Create a new MB ref

Creates a new “MB” method PAYMENT operation. The new operation is created in PENDING state. You will receive regular callbacks for this operation. No Checkout is involved.

Time limited references

MEO Wallet can generate time limited MB references. You can specify the payment limit using the expires property on the Operation.

{
  "amount":10,
  "currency": "EUR",
  "expires": "2025-11-13T15:59:58+0000",
  "ext_invoiceid" : "i00001232"
}

{
   "currency":"EUR",
   "id":"5adb0659-c616-4619-ab19-2c588842020c",
   "type":"PAYMENT",
   "channel":"WEBSITE",
   "ext_invoiceid" : "i00001232",
   "notes":"",
   "user_notes":"",
   "mb":{
      "ref":"005901658",
      "entity":"21426"
   },
   "items":[

   ],
   "refundable":false,
   "fee":-0.5,
   "amount":10,
   "amount_net":9.5,
       "merchant":{
      "id":"838626403",
      "name":"Wallet Default",
      "email":""
   },
   "date":"2025-11-06T09:52:09+0000",
   "method":"MB",
   "status":"PENDING",
   "expires":"2025-11-13T23:59:59+0000"
}

PLEASE NOTE Multibanco references always expire at the end of the day, Portugal time. On the response operation object we adjust the expires property to the actual payment limit.

The expiry date must be at least 2 days in the future.

Create a new MB instant reference

Similar to the time limited reference above, but the reference is instantly provisioned at SIBS which permits a finer time granularity, typically hours. This feature is useful for use cases associated to short lived events where payments must be restricted to a precise time period.

To create an instant MB reference, you must pass the instant property in the payload set to true (“instant”:true). The field expires is mandatory and has to be a date in the future.

You can optionally pass the starts property which also must have a value in the future. If ommited it defaults to the current time. This parameter specifies the date from which the reference will be payable. As you might expect, starts must be earlier than expires. Please note that if the timezones are ommitted in date representation UTC values are assumed.

The rest of the field are like the time limited references in the previous section.

The new operation is created in PENDING state. You will receive regular callbacks for this operation. No Checkout is involved.

Once created, if your customer tries to pay a different amount than the defined, before than “starts” or after “expires” the payment is rejected.

The use of this kind of references has a special fee. Contact your account manager for further information.

/api/v2/mb/reference

Generating a MB reference for recurring payments

This feature allows merchants to generate a MB reference that can be paid multiple times, simply by parameterizing a maximum and minimum amount.

You can ask MEO Wallet for a recurring MB reference via the API: /api/v2/mb/reference

Creating a new recurrent MB reference

You will receive regular regular callbacks for this operation everytime the reference gets paid from the client. No Checkout is involved.

You have to specify the maximum and minimum amounts for every reference that you need to create.

{
   "max_amount": 100,
   "min_amount": 1,
   "currency": "EUR",
   "op_type": "PAYMENT",
   "expires": "2025-01-13T12:00:00+0000",
   "ext_invoiceid": "PT123456",
   "ext_email": "jsantos@email.com",
   "ext_customerid": "LX123456"
}

{
    "mb": {
        "entity": "21423",
        "ref": "112353656"
    }
}

{
    "mb_entity":"21423",
    "ext_invoiceid":"PT123456",
    "ext_email":"jsantos@email.com",
    "modified_date":"2025-01-12T15:34:15+0000",
    "create_date":"2025-01-12T15:34:15+0000",
    "mb_ref":"112353656",
    "event":"COMPLETED",
    "operation_id":"0bee30be-f7ae-11e7-bec7-96b0f5920df6",
    "currency":"EUR",
    "ext_customerid":"LX123456",
    "amount":"50",
    "operation_status":"COMPLETED",
    "user":"16622",
    "method":"MB"
}

PLEASE NOTE: although a MB reference is immediately available for payments, it takes at least 1 day to parameterize it (“max_amount”;”min_amount”;”expires”).

Deleting a MB reference

This service deletes a MB reference. Instant MB references cannot be cancelled.

You will get a response like this:

[
    "OK"
]

Handling user errors

Due to the MB reference provisioning flow of time limited references during the first day a user may pay an incorrect amount. In that case you will receive a callback for a new operation with USERERROR event with a user_error property that tells you what went wrong. This is an example of such callback.

{
   "mb_entity":"21426",
   "ext_invoiceid":"i00001232",
   "ext_email":"teste@wallet.pt",
   "modified_date":"2025-08-03T18:02:00+0000",
   "user_error":"badamount",
   "create_date":"2025-08-03T18:01:00+0000",
   "mb_ref":"010290082",
   "operation_id":"943dbe3a-2fa7-11e4-adc1-e5b9ed6dd021",
   "event":"USERERROR",
   "ext_customerid":"u21423423",
   "currency":"EUR",
   "amount":5,
   "operation_status":"COMPLETED",
   "user":"1234",
   "method":"MB"
}

Note: “user_error” field can contain “badamount” or “duplicatepayment” messages.

In CRM flows you may search by ext_ properties to find linked payments.

Operation

The table describes the possible fields for the MB payment APIs. For a full description of the remaining operation types, check the Structures documentation.