Meo Wallet

Introduction

Marketplace support must be enabled by your account manager. You must set up a primary wallet which will receive the payments and a wallet for each merchant enrolled in your marketplace. Once in place it will allow you to, using the Checkout API, automatically split the payment to the merchant(s) selling the goods.

API extension for split payments

The sub structure split was added to the payment structure. Its format is as follows:

{
  split : [
    {
      "merchant_wallet": 99999,
      "fee_fixed": 9.99.
      "fee_variable": 9.9999
      "amount": 9999.99,
      "amount_fraction": "9/99",
      "descr": "an optional description"
    },
    ...

  ]
}

SplitRequest

split is an array of descriptors that gathers information about transaction splitting. Each descriptor contains the following fields:

Field	Type	Mandatory	Description
merchant_wallet	string	Y	the sub-merchant wallet public identification to be credited. It must be different from the marketplace owner’s wallet which is invoking the API. This is a mandatory field.
fee_fixed	float	N	fixed fee to be charged to the sub-merchant wallet for the current transaction. It is a fixed point number with 2 decimal places. This is an optional field which defaults to the value configured in your backoffice or 0 if none is defined.
fee_variable	float	N	fee rate to be charged to the sub-merchant wallet for the current transaction. It is a fixed point number not greater than 1 with 4 decimal places. It is an optional field which which defaults to the value configured in your backoffice or 0 if none is defined.
amount	float	Y unless `amount_fraction` is defined	gross amount to be credited to the sub-merchant wallet. This is the amount before deduction of the gateway fee and the marketplace owner’s specific fees computed with `fee_fixed` and `fee_variable` fields. The computation of the net amount actually credited into the sub-merchant’s wallet is as follows: `fraction = amount/payment_amount net_amount = (1 - fee_variable)fraction(payment_amount - gateway_fee) - fee_fixed`
amount_fraction	string	Y unless `amount` is defined	amount fraction to be allocated to the sub-merchant wallet. It is mutually exclusive with the `amount` field. It is a string representation of a rational number (e.g.. 0.6 or 2/3). The value is computed based on the number of destination wallets in the split array. For instance, if there are 3 wallets and `amount_fraction = 0.5` in one of them, but it’s unspecified in the remaining ones, then those will have 1/4 computed automatically.
descr	string(255)	N	free text describing this particular split. It is an optional field with a maximum length of 255 characters.

Click here for an example

"payment":{ 
  "method":"CC",
  "client": {
    "name": "Clark Kent",
    "email": "Clark.Kent@daily-planet.com",
    "address": {
      "country": "US",
      "address": "344 Clinton Street",
      "city": "Metropolis",
      "postalcode": "13905"
    }
  },
  "amount":56.54
  "currency": "EUR",
  "items":[{
    "ref":"XL 123",
    "name":"Krypton 2.0",
    "descr":"Red cape",
    "qt":1
  }.
  {
    "ref":"tie abc",
    "name":"tie",
    "descr":"Clark Kent's tie",
    "qt":1
  },
  ],
  "ext_invoiceid": "abcd1234",
  "expires": "2026-03-30T00:00:00+0000",
  "split": [ 
    { "merchant_wallet":993769349674, "fee_variable":0.04, "amount":1.0 }, // amount fraction will be automatically computed
    { "merchant_wallet":385725957501, "amount_fraction":"1/3" },
    { "merchant_wallet":514459420330, "amount_fraction":0.2},
    { "merchant_wallet":6353403803 } // amount fraction will be automatically computed
  ]},
  "url_confirm":"https://example.com/shop/confirm",
  "url_cancel":"https://example.com/shop/cancel
}<br />

Refunds

The API for doing refunds will also optionally take a split parameter.

In case you’re refunding a previously split operation there are 3 cases you want to consider:

the refund amount will be withdrawn from the participating merchants in the same proportions as the original payment . This is accomplished by issuing an API call with no split parameter like you would do in normal refunds.
the refund amount will be withdrawn from a specified subset of the participating merchants in the original payment. In this scenario you must specify a split array with the merchant wallets and optionally the amount fraction pertaining to each one. E.g:
```
 "split": [
  {"merchant_wallet":385725957501, "amount_fraction":"1/3" },
  { "merchant_wallet":6353403803 } // amount fraction will be automatically computed as 2/3
] 
```
the refund amount will be withdrawn from the marketplace owner’s account . In this case you must pass an empty split array to the refund API call:
```
"split": [ ]
```

Manual split

Request a split for an operation if you didn’t define the split rules when it was created. Trying to split a non splittable operation yelds an error.

Request	POST /api/v2/operations/id/split
URL params	operation id
Data params	SplitRequest
Returns	Operation

Click here for an example

  curl -X POST https://services.wallet.pt/api/v2/operations/d331d697-487b-4066-9f03-7748cc92ea98/split \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{ "split": [{"merchant_wallet":122822733437, "amount_fraction":"1/3" },{ "merchant_wallet":7668874328, "amount":  "1"}]}'

Returns

   {
    "card": {
        "token": "C22DDC02-DCC2-11EF-BBF5-811A69D28967",
        "last4": "0015",
        "type": "mastercard",
        "valdate": "12/2030",
        "expired": false
    },
    "cardsecure_url_confirm": "https://wallet.pt/checkout/f811e906-11fd-4bea-b918-980b4665ae89/end",
    "cardsecure_url_cancel": "https://wallet.pt/checkout/f811e906-11fd-4bea-b918-980b4665ae89/fail",
    "currency": "EUR",
    "instant": false,
    "id": "d331d697-487b-4066-9f03-7748cc92ea98",
    "ipaddress": "10.0.3.1",
    "type": "PAYMENT",
    "channel": "WEBSITE",
    "modified_date": "2025-01-27T15:24:21+0000",
    "notes": "",
    "user_notes": "testes",
    "items": [
        {
            "amount": 99990.99,
            "descr": "Um livro",
            "ref": "123",
            "name": "Livro",
            "qt": 1
        }
    ],
    "refundable": true,
    "fee": -3.21,
    "amount": 9.9,
    "amount_net": 6.69,
      "merchant": {
        "id": 298,
        "name": "Test shop",
        "email": ""
    },
    "splits": {
        "total": 2,
        "elements": [
            {
                "merchant_wallet": {
                    "currency": "EUR",
                    "name": "merchant test 1",
                    "balance": 105.96,
                    "public_id": 385725957501
                },
                "amount": "2.23",
                "fee_variable": "0.0000",
                "fee_fixed": "0.00"
            },
            {
                "merchant_wallet": {
                    "currency": "EUR",
                    "name": "merchant test 2",
                    "balance": 105.13,
                    "public_id": 6353403803
                },
                "amount": "4.46",
                "fee_variable": "0.0000",
                "fee_fixed": "0.00"
            }
        ]
    },
    "date": "2025-01-27T15:23:35+0000",
    "method": "CC",
    "status": "COMPLETED",
    "expires": "2025-04-02T19:40:00+0000"
}

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

A note about rounding errors

All computations related with splitting payments are done with rational number arithmetic in order to have exact results. Nevertheless, because amounts are fixed point numbers with 2 decimal places, rounding errors will inevitably occur during conversions. It was made a provision that rounding errors will always favour the marketplace owner. For instance if the total of split amounts after rounding exceeds the net amount available, then one of the split amounts will be rounded down resulting in a one cent loss to that specific recipient wallet.