Meo Wallet

API Resources

In this section you find the reference for the MEO Wallet resources and actions you can use to manipulate them. The resource structure generally follow the /collection, /collection/itemid pattern.

There are four resources you can manipulate: Checkouts, API Payments, Operations and Authorizations. Checkouts represent the handover of the payment process from your web site to MEO Wallet, while API Payment requests are meant to reduce the number of steps needed to complete a payment online with no Checkout involved.

Operations represent financial transaction on wallets.

Authorizations allow you to allocate a given amount to be captured later. Currently, only credit card transactions can be used with this concept.

There are two ways you can make API Payment Requests:

MB reference via the API: This is an extension only available to partner merchants. The API KEY must have specific permissions. Please request your merchant partner permission here.
MB WAY via the API: /api/v2/payment

/api/v2/checkout

Create payment

Creates a new payment checkout.

Request	POST /api/v2/checkout
Query params	none
Data params	Checkout
Returns	Checkout

Click here for an example

curl -X POST https://services.wallet.pt/api/v2/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{
    "payment": {
        "amount": 10,
        "client": {
            "address": {
                "address": "some street",
                "city": "lisboa",
                "country": "pt",
                "postalcode": "1100-000"
            },
            "email": "foo@bar.com",
            "name": "some name"
        },
        "currency": "EUR",
        "items": [
            {
                "descr": "Um livro",
                "name": "Livro",
                "qt": 1,
                "ref": 123
            }
        ]
    },
    "url_cancel": "https://example.com/shop/cancel",
    "url_confirm": "https://example.com/shop/confirm"
}'

Returns

{
    "id": "bc9b5078-3cc1-447b-bbb6-43815aeb8006",
    "url_confirm": "https://example.com/shop/confirm?checkoutid=bc9b5078-3cc1-447b-bbb6-43815aeb8006",
    "url_cancel": "https://example.com/shop/cancel?checkoutid=bc9b5078-3cc1-447b-bbb6-43815aeb8006",
    "exclude": [],
    "payment": {
        "currency": "EUR",
        "ipaddress": "127.0.0.1",
        "type": "PAYMENT",
        "channel": "WEBSITE",
        "items": [
            {
                "descr": "Um livro",
                "ref": 123,
                "name": "Livro",
                "qt": 1
            }
        ],
        "refundable": false,
        "fee": 0,
        "amount": 10,
        "amount_net": 10,
        "client": {
            "name": "some name",
            "email": "foo@bar.com",
            "address": {
                "address": "some street",
                "city": "lisboa",
                "postalcode": "1100-000",
                "country": "pt"
            }
        },
        "merchant": {
            "id": 73,
            "name": "Produção de Electrónica e Software",
            "email": ""
        },
        "date": "2025-07-13T20:06:08+0000",
        "date": "2025-07-13T20:07:04+0000",
        "status": "NEW"
    },
    "url_redirect": "https://www.wallet.pt/checkout/bc9b5078-3cc1-447b-bbb6-43815aeb8006"
}

If your checkout has the MB payment method available and you need a very limited duration (less than a day) for your payment, you can pass a special flag named instant in the “payment” object. The expires field is mandatory and has to be a date in the future.

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

Create authorization

Creates a new authorization checkout.

This request is similar to the described above. The main difference is the usage of a structure called “authorization” instead of “payment”. This object inherits all properties from the “payment” object.

Note: The optional field “expires” defines the date until the authorization is valid to be accepted. All subsequent requests (captures and releases) have the “expires” modified to the authorization date plus 1 month.

Redirect your customer to the redirect_url to accept the authorization. Then, you can capture the amount using the authorization id (inside the structure «authorization» of the checkout response).

Request	POST /api/v2/checkout
Query params	none
Data params	Authorization
Returns	Authorization

Click here for an example

curl -X POST https://services.wallet.pt/api/v2/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{"authorization": {
        "amount": 10,
        "client": {
            "address": {
                "address": "some street",
                "city": "lisboa",
                "country": "pt",
                "postalcode": "1100-000"
            },
            "email": "foo@bar.com",
            "name": "some name"
        },
        "currency": "EUR",
        "items": [
            {
                "descr": "Um livro",
                "name": "Livro",
                "qt": 1,
                "ref": 123
            }
        ]
    },
    "url_cancel": "https://example.com/shop/cancel",
    "url_confirm": "https://example.com/shop/confirm"
}'

Returns

{
    "id": "48e8e52b-3a71-41cc-802e-d3e3b4ec3c12",
    "url_confirm": "https://example.com/shop/confirm?checkoutid=48e8e52b-3a71-41cc-802e-d3e3b4ec3c12",
    "url_cancel": "https://example.com/shop/cancel?checkoutid=48e8e52b-3a71-41cc-802e-d3e3b4ec3c12",
    "exclude": [
        "MB",
        "WALLET"
    ],
    "shipping": false,
    "url_redirect": "https://wallet.pt/checkout/48e8e52b-3a71-41cc-802e-d3e3b4ec3c12",
    "authorization": {
        "currency": "EUR",
        "ipaddress": "10.188.160.1",
        "type": "AUTH",
        "channel": "WEBSITE",
        "modified_date": "2022-06-23T18:30:15+0000",
        "notes": "",
        "user_notes": "",
        "items": [
            {
                "descr": "Um livro",
                "ref": 123,
                "name": "Livro",
                "qt": 1
            }
        ],
        "refundable": false,
        "fee": 0,
        "amount": 10,
        "amount_net": 10,
        "client": {
            "name": "some name",
            "email": "foo@bar.com",
            "address": {
                "address": "some street",
                "city": "lisboa",
                "postalcode": "1100-000",
                "country": "pt"
            }
        },
        "date": "2022-06-23T18:30:15+0000",
        "id": "f7229128-ccca-4950-91fb-82971cb98ebb",
        "status": "NEW"
    }
}

A callback will be sent in case of failure or success with a reference to the created checkout (checkout_id) and type of operation. In this case is “AUTH”.

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

Get checkout

Gets the current status of a checkout process

Request	GET /api/v2/checkout/id
Query params	checkout id
Data params	none
Returns	Checkout

Click here for an example

  curl 	https://services.wallet.pt/api/v2/checkout/3899451d-0249-4745-bcd0-434177c76077 \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -H "Content-Type: application/json"

Returns after a successful payment:

{
    "id": "bc9b5078-3cc1-447b-bbb6-43815aeb8006",
    "url_confirm": "https://example.com/shop/confirm?checkoutid=bc9b5078-3cc1-447b-bbb6-43815aeb8006",
    "url_cancel": "https://example.com/shop/cancel?checkoutid=bc9b5078-3cc1-447b-bbb6-43815aeb8006",
    "exclude": [],
    "allows_punch_card_stamp": false,
    "payment": {
        "card": {
            "token": "B9AD740A-0ACA-11E4-BFDA-4790417D17DF",
            "last4": "1111",
            "type": "visa",
            "valdate": "12/2025",
            "expired": false
        },
        "currency": "EUR",
        "id": "6c39dc2a-37eb-4ed1-8416-77e8044f7673",
        "ipaddress": "127.0.0.1",
        "type": "PAYMENT",
        "channel": "WEBSITE",
        "items": [
            {
                "descr": "Um livro",
                "ref": "123",
                "name": "Livro",
                "qt": 1
            }
        ],
        "refundable": false,
        "fee": 0,
        "amount": 10,
        "amount_net": 9.75,
        "client": {
            "name": "some name",
            "email": "foo@bar.com",
            "address": {
                "address": "some street",
                "city": "lisboa",
                "postalcode": "1100-000",
                "country": "pt"
            }
        },
        "merchant": {
            "id": 73,
            "name": "Produção de Electrónica e Software",
            "email": ""
        },
        "date": "2025-07-13T20:06:08+0000",
        "modified_date": "2025-07-13T20:06:08+0000",
        "method": "CC",
        "status": "COMPLETED"
    },
    "url_redirect": "https://www.wallet.pt/checkout/bc9b5078-3cc1-447b-bbb6-43815aeb8006"
}

Note: If your checkout is of the type “authorization”, a structure named “authorization” will be returned instead.

Delete checkout

Destroys an ongoing checkout. This will only succeed if the customer hasn’t chosen any payment method yet. If you want to refund an existing payment see operations/refund.

Request	DELETE /api/v2/checkout/id
Query params	checkout id
Data params	none
Returns	Checkout

Click here for an example

  curl -X DELETE https://services.wallet.pt/api/v2/checkout/7abe0916-4253-46c0-977d-35c19686107c \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34"

Returns

  {
	"id":"7abe0916-4253-46c0-977d-35c19686107c",
	"url_confirm":"https://example.com/shop/confirm?checkoutid=7abe0916-4253-46c0-977d-35c19686107c",
	"url_cancel":"https://example.com/shop/cancel?checkoutid=7abe0916-4253-46c0-977d-35c19686107c",
	"exclude":[],
	"payment":{
		"currency":"EUR",
		"type":"PAYMENT",
		"status":"VOIDED",
		"notes":"",
		"items":[{
			"descr":"Um livro",
			"ref":"123",
			"name":"Livro",
			"qt":1
		}],
		"fee":0,
		"amount":10,
		"amount_net":10,
		"merchant":{
			"id":237,
			"name":"My shop",
			"email":""
		},
		"date":"2025-06-06T16:36:40+0000",
                "modified_date":"2025-06-06T16:36:40+0000"

	},
	"url_redirect":"http://wallet.pt/checkout/7abe0916-4253-46c0-977d-35c19686107c"
  }

/api/v2/operations

Get operations

Gets all operations with optional date range and pagination.

Parameter	When to use
id	Operation id to search
method	Operation method (e.g. CC)
type	Check valid values here
startdate	Search operations since date (yyy-mm-dd format)
enddate	Search operations until date (yyyy-mm-dd format)
number4	Last 4 digits from credit card
mb_ref	Full MB reference (9 digits)
phone	Mobile phone number used in a MBWAY payment. Used with «method=MBWAY» parameter
offset	Page number
limit	How many records per page to return (the maximum accepted value is “30”)
ext_invoiceid	merchant reference for this payment

Request	GET /api/v2/operations
Query params	startdate=[string], enddate=[string], limit=[int], offset=[int], ext_invoiceid=[string], number4=[int], phone=[int], mb_ref=[int]
Data params	none
Returns	Operation Array

Click here for an example

  curl https://services.wallet.pt/api/v2/operations/?limit=3 \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34"

Returns

{
    "total": "3",
    "elements": [
        {
            "card": {
                "token": "F8D4C75E-FDE2-11E3-BBD5-4790417D17DF",
                "last4": "1111",
                "type": "visa",
                "valdate": "12/2025",
                "expired": false
            },
            "currency": "EUR",
            "id": "dd3aebfc-ad6f-40ac-a57d-d30af3e0cee4",
            "ipaddress": "127.0.0.1",
            "ext_invoiceid": "olaola",
            "type": "PAYMENT",
            "channel": "WEBSITE",
            "notes": "",
            "user_notes": "",
            "items": [
                {
                    "descr": "Um livro",
                    "ref": "123",
                    "name": "Livro",
                    "qt": 1
                }
            ],
            "refundable": true,
            "fee": -0.25,
            "amount": 10,
            "amount_net": 9.75,
            "merchant": {
                "id": 16,
                "name": "CHBM",
                "email": "no_reply@sapo.pt"
            },
            "date": "2025-06-27T10:07:34+0000",
            "modified_date": "2025-06-27T10:07:34+0000",
            "method": "CC",
            "status": "COMPLETED"
        },
        {
            "card": {
                "token": "64F57A2A-FB84-11E3-8CB3-4990417D17DF",
                "last4": "0361",
                "type": "mastercard",
                "valdate": "12/2018",
                "expired": false
            },
            "currency": "EUR",
            "id": "b77e3dde-c92d-4699-ba84-53be34cb7abf",
            "ipaddress": "127.0.0.1",
            "type": "PAYMENT",
            "channel": "WEBSITE",
            "notes": "",
            "user_notes": "",
            "items": [
                {
                    "descr": "Um livro",
                    "ref": "123",
                    "name": "Livro",
                    "qt": 1
                }
            ],
            "refundable": true,
            "fee": -0.25,
            "amount": 10,
            "amount_net": 9.75,
            "client": {
                "name": "ze manel",
                "phone": "3519000",
                "email": "nada@nada.com",
                "address": {
                    "address": "picoas em lisboa",
                    "city": "na",
                    "postalcode": "1100"
                }
            },
            "merchant": {
                "id": 16,
                "name": "CHBM",
                "email": "no_reply@sapo.pt"
            },
            "date": "2025-06-24T09:45:36+0000",
            "modified_date": "2025-06-24T09:45:36+0000",
            "method": "CC",
            "status": "COMPLETED"
        },
        {
            "currency": "EUR",
            "id": "f454f651-8b5f-4249-9b22-ac8dd6aa6971",
            "ipaddress": "194.65.5.225",
            "type": "PAYMENT",
            "channel": "WEBSITE",
            "notes": "",
            "user_notes": "",
            "mb": {
                "ref": "140354182",
                "entity": "11708"
            },
            "items": [
                {
                    "descr": "Um livro",
                    "ref": "123",
                    "name": "Livro",
                    "qt": 1
                }
            ],
            "refundable": false,
            "fee": -0.62,
            "amount": 10,
            "amount_net": 9.38,
            "merchant": {
                "id": 16,
                "name": "CHBM",
                "email": "no_reply@sapo.pt"
            },
            "date": "2025-06-23T16:43:32+0000",
            "modified_date": "2025-06-23T16:43:32+0000",
            "method": "MB",
            "status": "PENDING"
        }
    ]
}

Get operation

Gets the current status of a single operation with PaymentItems details.

Request	GET /api/v2/operations/id
URL params	operation id
Data params	none
Returns	Operation

Click here for an example

  curl https://services.wallet.pt/api/v2/operations/45ff577f-3e40-5598-5eab-c235f9bb832d \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34"

Returns

  {
    "currency": "EUR",
    "id": "45ff577f-3e40-5598-5eab-c235f9bb832d",
    "ext_invoiceid": "6b690100e7b00000",
    "ext_email": "cliente@sapo.pt",
    "type": "PAYMENT",
    "status": "COMPLETED",
    "notes": "",
    "items": [
        {
            "amount": 25,
            "descr": "Tamanho 40/60",
            "ref": "701",
            "name": "SAPO Voucher",
            "qt": 1
        }
    ],
    "fee": -0.07,
    "amount": 25,
    "amount_net": 24.93,
    "client": {
        "name": "Hugo Fernandes",
    },
    "merchant": {
        "id": 237,
        "name": "Canf",
        "email": ""
    },
    "date": "2025-05-22T14:06:01+0000",
    "modified_date": "2025-05-22T14:06:01+0000",
    "method": "CC"
  }

Refund

Request a refund of an operation. The refundable property tells you if an operation is refundable or not. Trying to refund a non refundable operation yelds an error.

Request	POST /api/v2/operations/id/refund
URL params	operations id
Data params	RefundRequest
Returns	Operation

Click here for an example

  curl -X POST https://services.wallet.pt/api/v2/operations/45ff577f-3e40-5598-5eab-c235f9bb832d/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{"type": "full"}'

Returns

{
    "currency": "EUR",
    "id": "7ac180e9-4771-439d-b01b-37aaac03b03c",
    "ext_invoiceid": "",
    "ext_email": "",
    "ext_customerid": "",
    "type": "REFUND",
    "status": "COMPLETED",
    "merchant": {
        "id": 298,
        "name": "Test shop",
        "email": ""
    },
    "items": [],
    "refundable": false,
    "fee": 0,
    "amount": -10,
    "amount_net": -10,
    "date": "2025-10-23T15:47:01+0000",
    "parent": "45ff577f-3e40-5598-5eab-c235f9bb832d",
    "method": "WALLET"
}

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

/api/v2/payment

Create payment

Creates a new MB WAY payment.

Check valid mobile phones using this regular expression: ^9[1236]{1}[0-9]{7}$. If you try to send a valid number, but not registered at MB WAY service, you will get a 10002 error code. Check full list of errors here.

Request	POST /api/v2/payment
Query params	none
Data params	Payment
Returns	Payment

Click here for an example

curl -X POST https://services.wallet.pt/api/v2/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d ' {
        "method": "MBWAY",
        "amount": 10,
        "type": "PAYMENT",
        "mbway": {
            "phone":"960000000"
        },
        "client": {
            "name": "some name",
            "email": "foo@bar.com",
            "address": {
                "address": "some street",
                "city": "lisboa",
                "postalcode": "1100-000",
                "country": "pt"
            }
        },
        "currency": "EUR",
        "items": [
            {
                "ref": 123,
                "name": "Somny DX-200",
                "descr": "Photo Camera",
                "qt": 1
            }
        ]
  }
'

Returns

{
    "mbway": {
        "phone": "351#960000000"
    },
    "currency": "EUR",
    "id": "46cb7542-8f8d-11ea-8dd6-ae36e476a08e",
    "ipaddress": "127.0.0.1",
    "type": "PAYMENT",
    "channel": "WEBSITE",
    "modified_date": "2020-05-06T11:32:32+0000",
    "notes": "",
    "items": [
        {
            "descr": "Photo Camera",
            "ref": 123,
            "name": "Somny DX-200",
            "qt": 1
        }
    ],
    "refundable": false,
    "fee": -0.15,
    "amount": 10,
    "amount_net": 9.85,
    "client": {
        "name": "some name",
        "email": "foo@bar.com",
        "address": {
            "address": "some street",
            "city": "lisboa",
            "postalcode": "1100-000",
            "country": "pt"
        }
    },
    "merchant": {
        "id": 73,
        "name": "Produção de Electrónica e Software",
        "email": ""
    },
    "date": "2020-05-06T11:32:32+0000",
    "method": "MBWAY",
    "status": "PENDING"
}

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

/api/v2/wallets/methods

Lists the payment methods active for this wallet.

Request	GET /api/v2/wallets/methods
URL params	none
Data params	none
Returns	methods array in JSON object

Click here for an example

  curl https://services.wallet.pt/api/wallets/methods \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34"

Returns

{
    "methods": [
        "CC",
        "MB",
        "WALLET"
    ]
}

/api/v2/anon/images/button

Gives you a payment button ready to include in an img tag. Can be configured with payment methods retrieved with wallets/methods and various styling options.

Request	GET /api/v2/wallets/methods
URL params	methods, style, culture, type
Data params	none
Returns	image

Style	When to use
REGULAR	Default web page styles
WHITE	White button with transparency for dark backgrounds
LIGHT	Filled button with light transparency
DARK	Filled button with transparency for dark backgrounds

Culture	Result
PT	Button labels in portuguese
EN	Button labels in english

Type	Label
BUY	Buy / Comprar
CONFIRM	Confirm / Confirmar
CONTINUE	Continue / Continuar
PAYMENT	Payment / Pagamento
PURCHASE	Purchase / Pagar

Example https://services.wallet.pt/api/v2/anon/images/button?methods=CC,MB&style=light&culture=pt&type=purchase

/api/v2/anon/images/banner

Gives you a “secure payment banner” suitable for inclusion on your website footer. Provided in the form of an easy inclusion Javascript tag which generates a DIV container.

<script type="text/javascript"
	src="https://static.wallet.pt/assets/cache/js/MEOWalletBadges.js"
	data-meowallet-badge
	data-style="(regular|light|dark)"
	data-methods="(CC|MB|WALLET)"
	data-culture="(pt|en)"></script>

Example

<script type="text/javascript" src="https://static.wallet.pt/assets/cache/js/MEOWalletBadges.js" data-meowallet-badge data-style="regular" data-methods="CC,MB" data-culture="en"></script>

generates