/api/v2/operations

With this API, you can manage operations created through the existing API’s. You can list, search and refund 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

The method field may be one of the following

Method Description
CC Credit Card
MB Multibanco
MBWAY MB WAY
PAYPAL PayPal
WALLET MEO Wallet balance
GPAY Google Pay - used only as input flag to exclude or define Google Pay as default method in the checkout
APAY Apple Pay - used only as input flag to exclude or define Apple Pay as default method in the checkout
SEPA Direct Debit or Funds Withdrawal - use with type to identify it accordingly. Direct Debit => type=PAYMENT, Funds Withdrawal => WALLETFUNDS
BANK Wallet top-up via bank transfer
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.