HomeGuidesAPI ReferenceChangelog
Log InChangelog
Guides
Changelog

Merchant callback request examples

After a Wallet initiated payment (WIP) has completed (either successfully authorized or failed/rejected), a callback is sent to the merchant on the URL provided in the initial payment request (Wallet sale or Wallet Hybrid sale). The API specifications for this callback can be found here.


Setup

All examples on this page share the same transaction parameters and wallet setup.

Transaction amounts:

  • Food category: 7 Euro
  • Uncategorised: 3.5 Euro
  • Total amount: 10.5 Euro

Consumer wallet:

  • One MONIZZE voucher card — covers the FOOD category
  • One XTRA/CG-SDD payment instrument — covers the uncategorized amount

Customer payment method priority

  1. MONIZZE voucher card.
  2. XTRA/CG-SDD

Base request body

The basis for all the merchant callback examples below is a wallet with two payment instruments (one XTRA/CG-SDD and one MONIZZE voucher card). The request body below is for a hybrid partial payment, we will use an identical request body for the hybrid full payment examples, only switching the fullPayment parameter from false to true:

{
    "merchantReference": "merchant-ref-000089",
    "dpaId": "0223ef08-d1b1-4756-b3e5-49fd9c06e01a",
    "callbackUrl": "https://my.merchant.url.test.com",
    "amountDetails": {
        "currency": "EUR",
        "amount": 1050
    },
    "categories": [
        {
            "amount": 700,
            "types": [
                "FOOD"
            ]
        }
    ],
    "claimedUserIds": [
        {
            "cuid": "b4114e31-b7c4-4ea0-9b0f-89b7ddcb80e4",
            "cuidType": "DYNAMIC_SDKID"
        }
    ],
  "fullPayment": "false"
}

Hybrid payment scenarios

Scenario 1 — All amounts fully covered

MONIZZE successfully authorizes the full FOOD amount (700 cents) and XTRA successfully authorizes the full uncategorized amount (350 cents).

The root-level responseCode: 0 indicates the transaction completed successfully, and amountDetails reflects the total authorized amount. The transactionDetails array contains one entry per instrument: the MONIZZE sub-transaction carries a category of FOOD, while the XTRA sub-transaction covers the uncategorized remainder. Both entries include amountDetails, debitCredit, and a transactionId confirming successful authorization.

In this scenario, both Full and Partial flows produce the same callback.

{
  "amountDetails": {
    "amount": 1050,
    "currency": "EUR"
  },
  "externalResponseCode": "68617",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "bc0c25b8-4730-4d6f-acf2-9210e7686a85",
  "responseCode": "0",
  "transactionDetails": [
    {
      "amountDetails": {
        "amount": 700,
        "currency": "EUR"
      },
      "category": "FOOD",
      "debitCredit": "DEBIT",
      "paymentMethod": "MONIZZE",
      "responseCode": "68611",
      "transactionId": "01KTRF8Q7SE77TN4WJYCPYXQJ6"
    },
    {
      "amountDetails": {
        "amount": 350,
        "currency": "EUR"
      },
      "debitCredit": "DEBIT",
      "paymentMethod": "XTRA",
      "responseCode": "68611",
      "transactionId": "01KTRF8QW8VB6WVZAXBJG9ZG9X"
    }
  ]
}

Scenario 2 — FOOD covered, uncategorized amount not covered (XTRA balance = 0)

MONIZZE successfully authorizes the full FOOD amount (700 cents). XTRA fails to authorize the uncategorized amount (350 cents) due to insufficient funds.

Full hybrid (fullPayment =true)

The transaction fails entirely — no funds are deducted. The pre-authorization balance check determined the basket cannot be fully covered. The responseCode on root level indicates that it is a failed tranasction. As a consequence, amountDetails on root level is not populated because nothing has been authorised. Moreover, transactionDetails array is not populated for the same reason.

{
  "externalResponseCode": "68600",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "bece0e08-07ed-4a44-8b32-a07e140e8e02",
  "responseCode": "1012"
}

Partial hybrid (fullPayment =false)

MONIZZE covers the full FOOD amount (EUR 7.00). The uncategorized remainder (EUR 3.50) could not be covered by XTRA and is returned in remainingAmount for the ECR to collect by another payment method. Because the uncovered amount carries no voucher category constraint, remainingCategories is not populated.

The root-level responseCode: 0 indicates that the transaction completed successfully for the covered portion. Within transactionDetails, the outcome of each instrument is reflected in its responseCode: 68611 for the successful MONIZZE authorization and XTRA was not attempted since balance was 0.

{
  "amountDetails": {
    "amount": 700,
    "currency": "EUR"
  },
  "externalResponseCode": "68617",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "c3ceaa72-9c2f-4c66-8637-496657322980",
  "remainingAmount": {
    "amount": 350,
    "currency": "EUR"
  },
  "responseCode": "0",
  "transactionDetails": [
    {
      "amountDetails": {
        "amount": 700,
        "currency": "EUR"
      },
      "category": "FOOD",
      "debitCredit": "DEBIT",
      "paymentMethod": "MONIZZE",
      "responseCode": "68611",
      "transactionId": "01KTRFXCAX25G3D0922ZCTZEYZ"
    }
  ]
}

Scenario 3 — MONIZZE authorization for the FOOD amount fails, XTRA covers the full amount

If the authorization of 700 cents of FOOD fails on MONIZEE.

Full hybrid (fullPayment =true)

When Full hybrid is enabled, the wallet will run internal logics to redistribute the funds in case certain categories cannot be covered by the corresponding payment method.

In this case, ´amountDetails´ on root level indicates that the full amount of 10.5 EUR is authorized. respnseCode = 0 indicates the successful transaction outcome. In addition, the ´transactionDetails´ arrary provides more details about what has actually happend:

  • MONIZZE cannot cover the FOOD category that was originally distributed to it, hence status code 68612.
  • The full amount, both the FOOD category (7EUR), and the uncategorized amount (3.5 EUR) are covered by Xtra.
{
  "amountDetails": {
    "amount": 1050,
    "currency": "EUR"
  },
  "externalResponseCode": "68617",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "bc0c25b8-4730-4d6f-acf2-9210e7686a85",
  "responseCode": "0",
  "transactionDetails": [
    {
      "amountDetails": {
        "amount": 700,
        "currency": "EUR"
      },
      "category": "FOOD",
      "debitCredit": "DEBIT",
      "paymentMethod": "MONIZZE",
      "responseCode": "68612"
    },
    {
      "amountDetails": {
        "amount": 1050,
        "currency": "EUR"
      },
      "debitCredit": "DEBIT",
      "paymentMethod": "XTRA",
      "responseCode": "68611",
      "transactionId": "01KTRF8QW8VB6WVZAXBJG9ZG9X"
    }
  ]
}

Partial hybrid (fullPayment =false)

{
  "amountDetails": {
    "amount": 350,
    "currency": "EUR"
  },
  "externalResponseCode": "68617",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "c3ceaa72-9c2f-4c66-8637-496657322980",
  "remainingAmount": {
    "amount": 700,
    "currency": "EUR"
  },
  "remainingCategories": [
    {
      "amount": 700,
      "types": [
        "FOOD"
      ]
    }
  ],
  "responseCode": "0",
  "transactionDetails": [
    {
      "amountDetails": {
        "amount": 700,
        "currency": "EUR"
      },
      "category": "FOOD",
      "debitCredit": "DEBIT",
      "paymentMethod": "MONIZZE",
      "responseCode": "68612"
    },
    {
      "amountDetails": {
        "amount": 350,
        "currency": "EUR"
      },
      "debitCredit": "DEBIT",
      "paymentMethod": "XTRA",
      "responseCode": "68611",
      "transactionId": "01KTRF8QW8VB6WVZAXBJG9ZG9X"
    }
  ]
}

Scenario 4 — MONIZZE authorization success, XTRA authorization fail

Full hybrid (fullPayment =true)

The transaction fails entirely — no funds are deducted. A non-zero responseCode indicates the failure of the full hybrid transaction.

{
  "amountDetails": {
    "amount": 0,
    "currency": "EUR"
  },
  "externalResponseCode": "68600",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "c3ceaa72-9c2f-4c66-8637-496657322980",
  "responseCode": "1012",
  "transactionDetails": [
    {
      "amountDetails": {
        "amount": 700,
        "currency": "EUR"
      },
      "category": "FOOD",
      "debitCredit": "DEBIT",
      "paymentMethod": "MONIZZE",
      "responseCode": "68614",
      "transactionId": "01KTRFXCAX25G3D0922ZCTZEYZ"
    },
    {
      "amountDetails": {
        "amount": 350,
        "currency": "EUR"
      },
      "debitCredit": "DEBIT",
      "paymentMethod": "XTRA",
      "responseCode": "68612"
    }
  ]
}

Partial hybrid (fullPayment =false)

In this example the authorization for the MONIZZE payment instrument failed.

{
  "amountDetails": {
    "amount": 700,
    "currency": "EUR"
  },
  "externalResponseCode": "68617",
  "merchantReference": "merchant-ref-000089",
  "pspReference": "c3ceaa72-9c2f-4c66-8637-496657322980",
  "remainingAmount": {
    "amount": 350,
    "currency": "EUR"
  },
  "responseCode": "0",
  "transactionDetails": [
    {
      "amountDetails": {
        "amount": 700,
        "currency": "EUR"
      },
      "category": "FOOD",
      "debitCredit": "DEBIT",
      "paymentMethod": "MONIZZE",
      "responseCode": "68611",
      "transactionId": "01KTRFXCAX25G3D0922ZCTZEYZ"
    },
    {
      "amountDetails": {
        "amount": 350,
        "currency": "EUR"
      },
      "debitCredit": "DEBIT",
      "paymentMethod": "XTRA",
      "responseCode": "68612"
    }
  ]
}