Payment Status Callback

Handle deposit notifications by receiving callbacks from MiFinity and verifying the payment status before moving funds to the user.

How It Works

The user completes a deposit through the iFrame.
MiFinity sends a notification callback to your configured URL:
- Success → sent to the returnUrl specified in your init-iframe request.
- Failure → sent to the errorUrl (if provided).
Call the Payment Status API to retrieve the final transaction status.
Move funds to the user only when the status is SUCCESSFUL.

⚠️
Configure both returnUrl and errorUrl to capture all notifications. These URLs can be identical — as long as you always call the Payment Status API after receiving a callback.

Callback Payload

The notification callback is a JSON object sent to your returnUrl or errorUrl. The structure varies depending on the outcome:

{
  "sourceMoney": {
    "amount": 150,
    "currency": "EUR",
    "presentationAmount": "EUR150.00"
  },
  "destinationMoney": {
    "amount": 150,
    "currency": "EUR",
    "presentationAmount": "EUR150.00"
  },
  "totalFees": {
    "amount": 0,
    "currency": "EUR",
    "presentationAmount": "EUR0.00"
  },
  "exchangeRate": null,
  "traceId": "traceIdKf9BRLbkAzKCO~ilV1Ga~",
  "money": {
    "amount": 150,
    "currency": "EUR",
    "presentationAmount": "EUR150.00"
  },
  "description": "Test",
  "clientReference": "Sherlock Holmes",
  "validationKey": "i3Kk40d5m0pP~L0BOrGPgSakPLBAV1BFc2QRWMp~Z2mz2ao~rCXuaBsQIfrX7~KdzBiucKQ0AVQkdKMil_Wy0_rM6V7KyvCalB0j8bpgzDTNYE_ix5eqdyYVdDw4",
  "cardToken": null,
  "responseCode": "dwcGXOe3OweA8E1X9g7N2BfYT6w77rLLg78PrLpqKHc=",
  "captureToken": null,
  "transactionReference": "879ff0d1-6a52-420e-9480-3c964ba633e3",
  "paymentType": "EWALLET",
  "sfaRequired": null,
  "siteReference": null,
  "customerAccountNumber": "5001000001213949",
  "customerAccountNumberType": null,
  "customerDob": [
    1993,
    10,
    31
  ],
  "customerPostCode": null,
  "customerFirstName": "anish",
  "customerLastName": "shah",
  "senderEmailAddress": "[email protected]",
  "paymentMethod": "giropay",
  "accountNumber": "500100XXXXXX3949",
  "customerCountryCode": "DE",
  "requestedMoney": {
    "amount": 150,
    "currency": "EUR",
    "presentationAmount": "EUR150.00"
  }
}

Sent when the user abandons the deposit before completing it.

{
  "errorMessage": "Deposit attempt abandoned",
  "traceId": "traceIdPjrLbtlaLw7uiUMqU5ryO",
  "validationKey": "a139XMP2SLEvngp_ICppyaRywP47_Q8_VK0eRKHdcuWPzqseaUrg98dKJnLjSdE8o6BwqF1bLUDkMRuEgkWYTc~udj4AQAV6WRxLaXzJ_y~zP~qlx8KEOOZlIakH",
  "detailedStatus": "ABANDONED_BY_USER"
}

Sent when the transaction is declined by the risk engine.

{
  "errorMessage": "Deposit attempt abandoned",
  "traceId": "traceIdcAD4kumMM0Pdhxj8NApx_",
  "validationKey": "JEYGrBqqswCWxvmyfvzOzh69d6SULU5odbf4c1AZR3isRCtoWj~w8WLVs7obeJ~NgUD1kvYbIRcMEMMDABi_csRfPaEVqLjS8_lbbxvs3GfoHGG0QHMwJP4t_ueJ",
  "detailedStatus": "REFUSED_BY_RISK"
}

Sent for all other transaction failures.

{
  "errorMessage": "Type: TRANSACTION_FAILED. Args: [null]",
  "traceId": "traceIdPAAqMhRpxrBqD59qJPRtZ",
  "validationKey": "_Gzwj3A1pn~f3TbX4AdIWCGiunIP3KzN_KF5C55XtyI_B25NoeK0WqE4PZ7aegwrqQqu9F8eCOtdLI2jycSmffG8AkXrSJI35doa7bBBeoTN4Ty4S741KJgOoB81",
  "detailedStatus": "FAILED"
}

📘
Ignore any additional fields returned in the callback response that are not documented above. These may change without notice.

How It Works

Callback Payload

What’s Next