Meo Wallet

MB Way Authorizations Management

Authorizations allow you to allocate a given amount in a MB Way number to be captured later. You can create authorizations via the checkout API, Prows 2 API or the Payment API .

Capture

Request a capture of an authorization, that is a settlement of the payment transaction. The authorization must be accepted first.

You can do a partial capture. The total captured amount must not exceed the total authorized amount and no release has been called upon the specified authorization.

If the amount parameter is omitted in the CaptureRequest, all the authorized amount is captured.

Request	POST /api/v2/authorizations/id/capture
URL params	authorization id
Data params	CaptureRequest
Returns	Operation

Click here for an example

  curl -X POST https://services.wallet.pt/api/v2/authorizations/de4ebaf1-05a2-4fdf-affb-4c49ee5bf75f/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{"amount": 0.5}'

Returns

{
    "currency": "EUR",
    "instant": false,
    "id": "e2bb3c36-a1b1-11ef-95b4-8c05a5eb70ad",
    "ipaddress": "10.0.3.1",
    "type": "CAPTURE",
    "channel": "WEBSITE",
    "modified_date": "2024-11-13T11:24:46+0000",
    "notes": "",
    "items": [],
    "refundable": true,
    "fee": -0.06,
    "amount": 0.5,
    "amount_net": 0.44,
    "merchant": {
        "id": "73",
        "name": "Produção de Electrónica e Software",
        "email": ""
    },
    "date": "2024-11-13T11:24:45+0000",
    "parent": "de4ebaf1-05a2-4fdf-affb-4c49ee5bf75f",
    "method": "MBWAY",
    "status": "COMPLETED"
}

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

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

Release

Request a release of an authorization. The authorization must be accepted first. You can only release the full amount of an authorization. If you perform a partial capture, the remaining amount will be released automatically after 7 days.

Request	POST /api/v2/authorizations/id/release
URL params	authorization id
Data params	ReleaseRequest
Returns	Operation

Click here for an example

  curl -X POST https://services.wallet.pt/api/v2/authorizations/5dd80ada-cc44-410f-8366-7f1b7eb9d540/release \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{}'

Returns

{
    "currency": "EUR",
    "instant": false,
    "id": "634288dc-a1c6-11ef-898d-8933a5eb70ad",
    "ipaddress": "10.0.3.1",
    "type": "RELEASE",
    "channel": "WEBSITE",
    "modified_date": "2024-11-13T13:51:32+0000",
    "notes": "",
    "items": [],
    "refundable": false,
    "fee": 0,
    "amount": 5.5,
    "amount_net": 5.5,
    "date": "2024-11-13T13:51:31+0000",
    "parent": "5dd80ada-cc44-410f-8366-7f1b7eb9d540",
    "method": "MBWAY",
    "status": "COMPLETED"
}

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

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

Get authorizations

Gets all authorizations with optional date range and pagination.

Parameter	When to use
id	Authorization id to search
startdate	Search operations since date (yyy-mm-dd format)
enddate	Search operations until date (yyyy-mm-dd format)
method	Return only MB Way authorizations. By default, all are returned. Value=MBWAY
phone	MB Way number
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/authorizations
Query params	startdate=[string], enddate=[string], limit=[int], offset=[int], ext_invoiceid=[string], phone=[int]
Data params	none
Returns	Operation Array

Click here for an example

  curl https://services.wallet.pt/api/v2/authorizations/?limit=2&method=MBWAY \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34"

Returns

{
    "total": 6,
    "elements": [
        {
            "currency": "EUR",
            "instant": false,
            "id": "5dd80ada-cc44-410f-8366-7f1b7eb9d540",
            "ipaddress": "10.0.3.1",
            "type": "AUTH",
            "channel": "WEBSITE",
            "modified_date": "2024-11-13T13:50:36+0000",
            "notes": "",
            "items": [
                {
                    "amount": 99990.99,
                    "descr": "Um livro",
                    "ref": "123",
                    "name": "Livro",
                    "qt": 1
                }
            ],
            "refundable": false,
            "fee": 0,
            "amount": 5.5,
            "amount_net": 5.5,
            "captures": [],
            "releases": [
                {
                    "currency": "EUR",
                    "instant": false,
                    "id": "634288dc-a1c6-11ef-898d-8933a5eb70ad",
                    "ipaddress": "10.0.3.1",
                    "type": "RELEASE",
                    "channel": "WEBSITE",
                    "modified_date": "2024-11-13T13:51:32+0000",
                    "notes": "",
                    "items": [],
                    "refundable": false,
                    "fee": 0,
                    "amount": 5.5,
                    "amount_net": 5.5,
                    "date": "2024-11-13T13:51:31+0000",
                    "parent": "5dd80ada-cc44-410f-8366-7f1b7eb9d540",
                    "method": "MBWAY",
                    "status": "COMPLETED"
                }
            ],
            "date": "2024-11-13T13:50:11+0000",
            "method": "MBWAY",
            "status": "COMPLETED"
        },
        {
            "currency": "EUR",
            "instant": false,
            "id": "de4ebaf1-05a2-4fdf-affb-4c49ee5bf75f",
            "ipaddress": "10.0.3.1",
            "type": "AUTH",
            "channel": "WEBSITE",
            "modified_date": "2024-11-13T11:22:56+0000",
            "notes": "",
            "items": [
                {
                    "amount": 99990.99,
                    "descr": "Um livro",
                    "ref": "123",
                    "name": "Livro",
                    "qt": 1
                }
            ],
            "refundable": false,
            "fee": 0,
            "amount": 5.5,
            "amount_net": 5.5,
            "captures": [
                {
                    "currency": "EUR",
                    "instant": false,
                    "id": "e2bb3c36-a1b1-11ef-95b4-8c05a5eb70ad",
                    "ipaddress": "10.0.3.1",
                    "type": "CAPTURE",
                    "channel": "WEBSITE",
                    "modified_date": "2024-11-13T11:24:46+0000",
                    "notes": "",
                    "items": [],
                    "refundable": true,
                    "fee": -0.06,
                    "amount": 0.5,
                    "amount_net": 0.44,
                     "merchant": {
                        "id": "73",
                        "name": "Produção de Electrónica e Software",
                        "email": ""
                    },
                    "date": "2024-11-13T11:24:45+0000",
                    "parent": "de4ebaf1-05a2-4fdf-affb-4c49ee5bf75f",
                    "method": "MBWAY",
                    "status": "COMPLETED"
                }
            ],
            "releases": [],
            "date": "2024-11-13T11:21:58+0000",
            "method": "MBWAY",
            "status": "COMPLETED"
        }
    ]
}

Get authorization

Gets the current status of a single authorization with “captures” and “releases” details.

Request	GET /api/v2/authorizations/id
URL params	authorization id
Data params	none
Returns	Operation

Click here for an example

  curl https://services.wallet.pt/api/v2/authorizations/5dd80ada-cc44-410f-8366-7f1b7eb9d540 \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34"

Returns

{
    "currency": "EUR",
    "instant": false,
    "id": "5dd80ada-cc44-410f-8366-7f1b7eb9d540",
    "ipaddress": "10.0.3.1",
    "type": "AUTH",
    "channel": "WEBSITE",
    "modified_date": "2024-11-13T13:50:36+0000",
    "notes": "",
    "items": [
        {
            "amount": 99990.99,
            "descr": "Um livro",
            "ref": "123",
            "name": "Livro",
            "qt": 1
        }
    ],
    "refundable": false,
    "fee": 0,
    "amount": 5.5,
    "amount_net": 5.5,
    "captures": [],
    "releases": [
        {
            "currency": "EUR",
            "instant": false,
            "id": "634288dc-a1c6-11ef-898d-8933a5eb70ad",
            "ipaddress": "10.0.3.1",
            "type": "RELEASE",
            "channel": "WEBSITE",
            "modified_date": "2024-11-13T13:51:32+0000",
            "notes": "",
            "items": [],
            "refundable": false,
            "fee": 0,
            "amount": 5.5,
            "amount_net": 5.5,
            "date": "2024-11-13T13:51:31+0000",
            "parent": "5dd80ada-cc44-410f-8366-7f1b7eb9d540",
            "method": "MBWAY",
            "status": "COMPLETED"
        }
    ],
    "date": "2024-11-13T13:50:11+0000",
    "method": "MBWAY",
    "status": "COMPLETED"
}

CaptureRequest

Field	Type	In/Out	Mandatory	Description	Validations
amount	float	I	N	amount to capture	min=0.2
ext_customerid	string	I	N	Merchant customer ID (for reference	maxlen=45
ext_email	string	I	N	Customer email (for reference)	maxlen=100
ext_invoiceid	string	I	N	Merchant transaction reference	maxlen=45
ext_employee	string	I	N	employee name (max 45 chars)	maxlen=45
notes	string	I	N	Merchant notes	maxlen=255

ReleaseRequest

Field	Type	In/Out	Mandatory	Description
amount	float	I	N	amount to capture	min=0.2
ext_customerid	string	I	N	Merchant customer ID (for reference)	maxlen=45
ext_email	string	I	N	Customer email (for reference)	maxlen=100
ext_invoiceid	string	I	N	Merchant transaction reference	maxlen=45
ext_employee	string	I	N	employee name (max 45 chars)	maxlen=45
notes	string	I	N	Merchant notes	maxlen=255