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.


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.

Request POST /api/v2/mb/pay
Query params none
Data params Operation
Returns Operation

Time limited references

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

Click here for an example
  "currency": "EUR",
  "expires": "2025-11-13T15:59:58+0000",
  "ext_invoiceid" : "i00001232"
which returns
   "ext_invoiceid" : "i00001232",

      "name":"Wallet Default",

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.

Request POST /api/v2/mb/pay
Query params none
Data params Operation
Returns Operation


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.

Request POST /api/v2/mb/reference
Query params none
Data params Request
Returns Reference

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

Click here for an example
   "max_amount": 100,
   "min_amount": 1,
   "currency": "EUR",
   "op_type": "PAYMENT",
   "expires": "2025-01-13T12:00:00+0000",
   "ext_invoiceid": "PT123456",
   "ext_email": "",
   "ext_customerid": "LX123456"
The following fields are optional: ext_invoiceid, ext_customerid or ext_email. Which returns:
    "mb": {
        "entity": "21423",
        "ref": "112353656"
When a client pays several times one of these MB references, you will receive a callback for each payment.

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.

Request DELETE /api/v2/mb/reference
Query params none
Data params DeleteReferenceRequest
Returns string

You will get a response like this:

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.


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

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


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

Field Type In/Out Mandatory Description
amount float I Y payment amount
amount_net float O Y amount after fees
client Client Data IO N inputs the client and shipping data known by the merchant and outputs it augmented with the data collected from user
currency string I Y amount currency in ISO 4217
date date O Y transaction create date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
ext_customerid string I N merchant customer reference
ext_employee string I N employee name (max 45 chars)
ext_invoiceid string I N merchant reference for this payment
ext_email string I N Customer email (max 100 chars)
fee float O Y transaction fee
id string O Y operation identifier
items PaymentItem Array I N items related with the payment
mb MB O N Multibanco reference used in this transaction
merchant Merchant O N transaction recipient
method string IO Y payment method - MB
modified_date date O Y transaction modified date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
notes string O N notes
refundable boolean O Y is this operation refundable?
status string O Y transaction status - PENDING
store integer I N store ID (from the merchant backoffice)
type string IO Y transaction type - PAYMENT
starts date IO N start date for the MB reference (used for instant MB references: mb/pay)
expires date IO N expiration date of the payment in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format. If this field is not provided for non instant MB references (instant = false), your payment will be valid for 1000 minutes
instant boolean IO N Set this field to true to create an instant reference