[THK] E.1.2 Webhook Payload Variants by Payment Method

Overview

All webhook notifications follow the generic structure defined in E.1.1 Generic Webhook Structure.

In addition to this generic structure, webhook payloads may include method-specific extension blocks depending on:

the payment method
the operation type
the transaction lifecycle stage

This page defines those method-specific payload extensions.

The generic structure is not repeated here and should always be considered the baseline for webhook processing.

Structure Principles

Webhook payloads are composed of:

the generic core structure (see E.1.1 Generic Webhook Structure)
one or more method-specific extension blocks

These extension blocks:

are included only when relevant
do not alter the generic structure
provide contextual information for the specific payment method
are additive and never replace or redefine generic fields
may be omitted entirely when not applicable to the transaction context

Processing should therefore:

Parse the generic structure
Identify paymentMethod and paymentType
Process relevant extension blocks
Ignore non-relevant or unknown blocks and fields
Treat unknown fields as forward-compatible extensions

MB WAY – One-Off Payments

1. Overview

MB WAY one-off payment webhooks represent customer-initiated payments using a mobile phone number (alias).

These correspond to standard purchase flows where the customer authorizes the payment on their device.

These notifications use:

paymentMethod = MBWAY
paymentType = PURS

The webhook payload does not include a dedicated method-specific object, but includes a token object representing the MB WAY alias used in the transaction.

2. Extension Block: token

{
    "token": {
        "tokenType": "string",
        "value": "string"
    }
}

3. Field Description

Field	Description
`tokenType`	Type of token used for the payment (e.g. MobilePhone)
`value`	MB WAY alias (MSISDN in format `countryCode#number`)

In addition to the token block, MB WAY webhook payloads may also include:

Field	Description
`internalTransactionId`	Internal SIBS transaction identifier
`merchant.inApp`	Indicates whether the payment was initiated in-app

4. Status Semantics

The result of the payment is primarily represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → payment successfully completed
paymentStatus = Declined → payment rejected by the customer

In declined scenarios, additional information may be present:

returnStatus.statusDescription → description of the failure reason

5.1 Complete Payload Example – Payment Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2C5q32r830X8pGKNKN2",
    "transactionDateTime": "2026-03-28T12:34:43Z",
    "amount": {
        "currency": "EUR",
        "value": 16.9
    },
    "merchant": {
        "transactionId": "0a3cdbb2fedb5576a1ba89db8db3499d",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM",
        "inApp": "false"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "MobilePhone",
        "value": "351#912345678"
    },
    "internalTransactionId": "S13155210809785S",
    "notificationID": "8ad5fc9f-6753-56c3-a7f6-7aa280f8584e"
}

5.2 Complete Payload Example – Payment Declined

{
    "returnStatus": {
        "statusDescription": "After the operation was successful, was refused by the cardholder.",
        "statusMsg": "Declined",
        "statusCode": "01.106.0001"
    },
    "paymentStatus": "Declined",
    "paymentMethod": "MBWAY",
    "transactionID": "s2akpNZQvhtIdgVtqpje",
    "transactionDateTime": "2026-03-28T09:00:02Z",
    "amount": {
        "currency": "EUR",
        "value": 208.0
    },
    "merchant": {
        "transactionId": "2690636b51bb5deh0f262355638ed6d4",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM",
        "inApp": "false"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "MobilePhone",
        "value": "351#912345678"
    },
    "internalTransactionId": "s2akpNZQzgdHchVtqpje",
    "notificationID": "4b8bc1a7-eb72-5046-964a-2426dfa5d5d4"
}

Credit Card – One-Off Payments

1. Overview

CARD one-off payment webhooks represent customer-initiated card payments executed as standard purchase transactions.

These correspond to one-off purchase flows where the payment is completed using card details, without mandate management or recurring payment semantics.

These notifications use:

paymentMethod = CARD
paymentType = PURS

For this operation type, the webhook payload may not include any additional method-specific block beyond the generic structure.

2. Extension Block

No additional extension block is required for the standard one-off CARD payment webhook payload.

3. Field Description

No method-specific fields are required beyond the generic webhook structure.

In addition to the generic fields, CARD one-off payment webhooks may include:

Field	Description
`internalTransactionId`	Internal SIBS transaction identifier

Other card-related extension blocks may exist in different card contexts, such as tokenization or recurring flows, but they are outside the scope of the standard one-off payment webhook.

4. Status Semantics

The result of the payment is primarily represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → payment successfully completed
paymentStatus = Declined → payment rejected

The sample below represents a successful one-off card payment.

5. Complete Payload Example – Payment Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2JTpgAXeco8R8SNaC6W",
    "transactionDateTime": "2026-03-30T20:22:13.503+01:00",
    "amount": {
        "currency": "EUR",
        "value": 5.1
    },
    "merchant": {
        "transactionId": "18c7aab95106515d8deff162ea21aae2",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PURS",
    "internalTransactionId": "S14090511002034S",
    "notificationID": "d7f74ecb-04f4-535d-b836-343bd4c1140c"
}

Referencia Multibanco – One-Off Payments

1. Overview

REFERENCE webhooks relate to Multibanco payment references and cover the main lifecycle events associated with this payment method.

In the webhook flow, the most relevant events are:

reference generation
payment completion

These notifications use:

paymentMethod = REFERENCE
paymentType = PREF

The webhook payload extends the generic structure with a paymentReference block that contains the reference-specific data.

2. Extension Block: paymentReference

{
    "paymentReference": {
        "reference": "string",
        "entity": "string",
        "paymentEntity": "string",
        "amount": {
            "currency": "string",
            "value": "number"
        },
        "scheme": "string",
        "status": "string",
        "expireDate": "datetime"
    }
}

3. Field Description

Field	Description
`reference`	Multibanco payment reference assigned to the transaction
`entity`	Multibanco entity code
`paymentEntity`	Payment entity associated with the reference
`amount`	Amount associated with the reference
`scheme`	Reference scheme
`status`	Current state of the reference
`expireDate`	Expiration date and time of the reference

In addition to the paymentReference block, REFERENCE webhook payloads may also include:

Field	Description
`internalTransactionId`	Internal SIBS reference associated with the transaction

4. Status Semantics

The paymentReference.status field represents the lifecycle of the Multibanco reference.

Typical values include:

UNPAID → the reference has been generated and is awaiting payment
PAID → the reference has been paid successfully

This lifecycle is reflected in the top-level transaction status:

reference generation typically results in paymentStatus = Pending
payment completion typically results in paymentStatus = Success

Accordingly:

paymentStatus = Pending + paymentReference.status = UNPAID identifies a generated but unpaid reference
paymentStatus = Success + paymentReference.status = PAID identifies a completed payment

5.1 Complete Payload Example – Reference Generated

{
    "returnStatus": {
        "statusMsg": "Pending",
        "statusCode": "00.110.1601"
    },
    "paymentStatus": "Pending",
    "paymentMethod": "REFERENCE",
    "transactionID": "s2EO2howaCzvc2SmT6Ds",
    "transactionDateTime": "2026-03-29T00:01:14.606Z",
    "amount": {
        "currency": "EUR",
        "value": 34.67
    },
    "merchant": {
        "transactionId": "721c192a76105c4dcb29ff6fa360ab95",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PREF",
    "paymentReference": {
        "reference": "036427626",
        "entity": "75767",
        "paymentEntity": "75767",
        "amount": {
            "currency": "EUR",
            "value": 34.67
        },
        "scheme": "MB",
        "status": "UNPAID",
        "expireDate": "2026-04-25T02:01:13+01:00"
    },
    "internalTransactionId": "022052964340",
    "notificationID": "7d037d37-4588-4422-bbd9-52f930c02fa2"
}

5.2 Complete Payload Example – Reference Paid

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "REFERENCE",
    "transactionID": "s2EN1gnwzDaxd3SmT6Ds",
    "transactionDateTime": "2026-03-28T22:20:00.001Z",
    "amount": {
        "currency": "EUR",
        "value": 34.67
    },
    "merchant": {
        "transactionId": "721c192a76205c4dca29ff6fa360ab95",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PREF",
    "paymentReference": {
        "reference": "036527626",
        "entity": "75837",
        "paymentEntity": "75837",
        "amount": {
            "currency": "EUR",
            "value": 34.67
        },
        "scheme": "MB",
        "status": "PAID",
        "expireDate": "2026-04-22T13:14:23+01:00"
    },
    "internalTransactionId": "CZ000229055427",
    "notificationID": "bc74ea43-fa1d-4f11-94cf-41c3f65bda3c"
}

MB WAY Authorised Payments – Recurring Payments

1. Overview

MB WAY mandate lifecycle webhooks represent the creation and management of mandates used in recurring payment flows.

These notifications are associated with mandate lifecycle operations and not with the actual collection of funds over an existing mandate.

These notifications use:

paymentMethod = MBWAY
paymentType = AUTH for most lifecycle operations
paymentType = CAUT for mandate cancellation

The webhook payload extends the generic structure with an mbwayMandate block containing mandate-specific data.

Typical lifecycle events include:

mandate creation
mandate reactivation
mandate renewal
mandate suspension
mandate cancellation

2. Extension Block: mbwayMandate

{
    "mbwayMandate": {
        "mandateIdentification": "string",
        "mandateAction": "string",
        "mandateActionStatus": "string",
        "mandateType": "string",
        "mandateAmountLimit": {
            "value": "number"
        },
        "mandateExpirationDate": "date",
        "clientName": "string",
        "aliasMBWAY": "string"
    }
}

3. Field Description

Field	Description
`mandateIdentification`	Unique identifier of the mandate
`mandateAction`	Lifecycle action represented by the webhook
`mandateActionStatus`	Result of the lifecycle action
`mandateType`	Type of mandate
`mandateAmountLimit`	Maximum allowed amount for the mandate, when applicable
`mandateExpirationDate`	Mandate expiration date, when applicable
`clientName`	Name associated with the mandate
`aliasMBWAY`	MB WAY alias associated with the mandate

The presence of some fields depends on the lifecycle event:

creation and renewal typically include mandateAmountLimit and mandateExpirationDate
reactivation and suspension may include fewer fields
cancellation may include expiration updates

4. Status Semantics

The result of the lifecycle operation is represented by:

paymentStatus
returnStatus
mbwayMandate.mandateActionStatus

Typical action values include:

CRTN → mandate creation
RCTV → mandate reactivation
RNVT → mandate renewal
SSPN → mandate suspension
CNCL → mandate cancellation

Typical action status values include:

SCCS → action completed successfully
RFSD → action refused

Typical combinations:

paymentStatus = Success + mandateActionStatus = SCCS → lifecycle action completed
paymentStatus = Declined + mandateActionStatus = RFSD → lifecycle action refused

5.1 Complete Payload Example – Mandate Creation Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s20KTG3U6MfngKPdT0d7",
    "transactionDateTime": "2026-03-30T19:04:50.818+01:00",
    "amount": {
        "currency": "EUR",
        "value": 0.0
    },
    "merchant": {
        "transactionId": "043dffb68ad35d4490b65baec49a7df0",
        "terminalId": 45546
    },
    "paymentType": "AUTH",
    "mbwayMandate": {
        "mandateIdentification": "20586744994883877072",
        "mandateAction": "CRTN",
        "mandateActionStatus": "SCCS",
        "mandateType": "SBSC",
        "mandateAmountLimit": {
            "value": 70.0
        },
        "mandateExpirationDate": "2029-03-31",
        "clientName": "Cliente Name",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "3beb99d8-f53a-5124-b297-996331e543cb"
}

5.2 Complete Payload Example – Mandate Creation Refused

{
    "returnStatus": {
        "statusMsg": "Declined",
        "statusCode": "10.110.1150"
    },
    "paymentStatus": "Declined",
    "paymentMethod": "MBWAY",
    "transactionID": "s2A3772uGlNCCkuBJvHg",
    "transactionDateTime": "2026-03-30T18:59:33.281+01:00",
    "amount": {
        "currency": "EUR",
        "value": 0.0
    },
    "merchant": {
        "transactionId": "fba3087ab9bd514fbb1d389e666ec81b",
        "terminalId": 45546
    },
    "paymentType": "AUTH",
    "mbwayMandate": {
        "mandateIdentification": "20476744924842202962",
        "mandateAction": "CRTN",
        "mandateActionStatus": "RFSD",
        "mandateType": "SBSC",
        "mandateAmountLimit": {
            "value": 70.0
        },
        "mandateExpirationDate": "2029-03-31",
        "clientName": "Cliente Name",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "1620c4db-9a73-5094-95c1-d353ba2ccea5"
}

5.3 Complete Payload Example – Mandate Reactivation

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2e7Qz815ZIbCbeuynWh",
    "transactionDateTime": "2026-03-30T19:37:50.582+01:00",
    "amount": {
        "currency": "EUR",
        "value": 0.0
    },
    "merchant": {
        "transactionId": "feecebc6286f5feac41a10c81eae2242",
        "terminalId": 45546
    },
    "paymentType": "AUTH",
    "mbwayMandate": {
        "mandateIdentification": "15555289899302459792",
        "mandateAction": "RCTV",
        "mandateActionStatus": "SCCS",
        "mandateType": "SBSC",
        "clientName": "Cliente Name",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "de5f268f-1d23-548e-b8b4-b47b2f50ae8d"
}

5.4 Complete Payload Example – Mandate Renewal

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2e7Qa815ZIbBcfvynWh",
    "transactionDateTime": "2026-03-30T19:49:56.113+01:00",
    "amount": {
        "currency": "EUR",
        "value": 0.0
    },
    "merchant": {
        "transactionId": "feecebc5175e5feac52b21d91eae2242",
        "terminalId": 45546
    },
    "paymentType": "AUTH",
    "mbwayMandate": {
        "mandateIdentification": "15555278788202450801",
        "mandateAction": "RNVT",
        "mandateActionStatus": "SCCS",
        "mandateType": "SBSC",
        "mandateAmountLimit": {
            "value": 70.0
        },
        "mandateExpirationDate": "2029-01-31",
        "clientName": "Cliente Name",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "4fa8a1c3-e25b-4606-08d6-1f5a6e9ec191"
}

5.5 Complete Payload Example – Mandate Suspension

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2e8Ra804YHaBbevzoXi",
    "transactionDateTime": "2026-03-30T19:53:38.235+01:00",
    "amount": {
        "currency": "EUR",
        "value": 0.0
    },
    "merchant": {
        "transactionId": "feecebc5186f5feac41a10c81eae2242",
        "terminalId": 45546
    },
    "paymentType": "AUTH",
    "mbwayMandate": {
        "mandateIdentification": "15555278788202450801",
        "mandateAction": "SSPN",
        "mandateActionStatus": "SCCS",
        "mandateType": "SBSC",
        "clientName": "Cliente Name",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "23f749b5-ee4b-49c5-4606-f010c2bdaefa"
}

5.6 Complete Payload Example – Mandate Cancellation

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2hvcSzoznjqs5XWUCXb",
    "transactionDateTime": "2026-03-30T00:05:32.218+01:00",
    "amount": {
        "currency": "EUR",
        "value": 0.0
    },
    "merchant": {
        "transactionId": "2cd5d308cda95739b17b7c626ddd3aa0",
        "terminalId": 45546
    },
    "paymentType": "CAUT",
    "mbwayMandate": {
        "mandateIdentification": "15555278788202450801",
        "mandateAction": "CNCL",
        "mandateActionStatus": "SCCS",
        "mandateType": "SBSC",
        "mandateExpirationDate": "2026-03-31",
        "clientName": "Cliente Name",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "e6619f76-ee4b-4246-ee4b-55d3e6b3f8d9"
}

MB WAY Authorised Payments – Collection

1. Overview

MANDATE webhook notifications represent the collection of funds using a previously created MB WAY mandate.

These correspond to recurring payment executions performed after the customer has authorized a mandate.

These notifications are not part of the mandate lifecycle, but rather the execution of a payment over an existing mandate.

These notifications use:

paymentMethod = MANDATE
paymentType = PURS

The webhook payload extends the generic structure with an mbwayMandate block containing the mandate identification associated with the payment.

2. Extension Block: mbwayMandate

{
    "mbwayMandate": {
        "mandateIdentification": "string",
        "aliasMBWAY": "string"
    }
}

3. Field Description

Field	Description
`mandateIdentification`	Identifier of the mandate used for the payment
`aliasMBWAY`	MB WAY alias (MSISDN) associated with the mandate

In addition to the mbwayMandate block, MANDATE webhook payloads may also include:

Field	Description
`internalTransactionId`	Internal SIBS transaction identifier

4. Status Semantics

The result of the payment execution is represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → payment successfully collected
paymentStatus = Declined → payment execution failed

For successful collections:

the mandate is valid and active
the payment has been executed using the previously authorized mandate

5. Complete Payload Example – Payment Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MANDATE",
    "transactionID": "s211gQddC4KUT4NX65Ap",
    "transactionDateTime": "2026-03-30T19:07:09.127+01:00",
    "amount": {
        "currency": "EUR",
        "value": 3.99
    },
    "merchant": {
        "transactionId": "32b267069be858e29ec00eda1e012481",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PURS",
    "internalTransactionId": "S14055012281264S",
    "mbwayMandate": {
        "mandateIdentification": "15555278788202450801",
        "aliasMBWAY": "351#912345678"
    },
    "notificationID": "aa9e5b04-ee4b-47ff-ee4b-bf01f7c97127"
}

Credit Card – Recurring Payments (CIT)

1. Overview

CARD recurring payment webhooks for Cardholder Initiated Transactions (CIT) represent transactions where the customer is present and actively involved in the payment.

These transactions are used to:

establish consent for recurring payments
execute customer-initiated recurring transactions

These transactions require active customer interaction and should not be confused with Merchant Initiated Transactions (MIT), which are processed without customer presence.

These notifications use:

paymentMethod = CARD
paymentType = AUTH (initial setup) or PURS (customer-initiated recurring payment)

The webhook payload extends the generic structure with a merchantInitiatedTransaction block that defines the recurring payment context.

2. Extension Block: merchantInitiatedTransaction

{
    "merchantInitiatedTransaction": {
        "type": "string",
        "validityDate": "datetime",
        "amountQualifier": "string",
        "schedule": {
            "initialDate": "datetime",
            "finalDate": "datetime",
            "interval": "string"
        }
    }
}

3. Field Description

Field	Description
`type`	Type of recurring model (e.g. UCOF, RCRR)
`validityDate`	Validity limit for the recurring agreement
`amountQualifier`	Indicates whether the amount is estimated or actual
`schedule.initialDate`	Start date of the recurring schedule
`schedule.finalDate`	End date of the recurring schedule
`schedule.interval`	Frequency of execution

Field presence depends on the recurring model:

UCOF typically includes validityDate and amountQualifier
Recurring (RCRR) may include a schedule block

The schedule object is only applicable to recurring (RCRR) transactions and is not present in UCOF flows.

4. Status Semantics

The result of the transaction is represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → transaction successfully processed
paymentStatus = Declined → transaction rejected

Recurring context is determined by:

merchantInitiatedTransaction.type
paymentType

Typical combinations include:

paymentType = AUTH → initial CIT setup (consent establishment)
paymentType = PURS → customer-initiated recurring execution

5.1 Complete Payload Example – CIT (UCOF) Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2bDX8mjiFZU5ZwfvSvR",
    "transactionDateTime": "2023-01-06T16:57:11.2Z",
    "amount": {
        "currency": "EUR",
        "value": 102.38
    },
    "merchant": {
        "transactionId": "3064371",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "AUTH",
    "notificationID": "45d108d3-2cef-41a6-90af-a3bdb4af244a",
    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "validityDate": "2023-01-31T00:00:00Z",
        "amountQualifier": "ESTIMATED"
    }
}

5.2 Complete Payload Example – CIT (Recurring / RCRR) Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s24nZiFtu15SCiW9vpDm",
    "transactionDateTime": "2022-12-27T16:05:27.585Z",
    "amount": {
        "currency": "EUR",
        "value": 11.2
    },
    "merchant": {
        "transactionId": "6637262",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PURS",
    "notificationID": "a433453e-6e40-4f53-a80d-4985cffa36f6",
    "merchantInitiatedTransaction": {
        "type": "RCRR",
        "validityDate": "2023-06-30T01:00:00+01:00",
        "amountQualifier": "ACTUAL",
        "schedule": {
            "initialDate": "2022-12-27T00:00:00Z",
            "finalDate": "2023-01-06T00:00:00Z",
            "interval": "DAILY"
        }
    }
}

5.3 Complete Payload Example – CIT (Recurring / RCRR) Declined

{
    "returnStatus": {
        "statusMsg": "Declined",
        "statusCode": "10.106.0001"
    },
    "paymentStatus": "Declined",
    "paymentMethod": "CARD",
    "transactionID": "s2CITRCRRDECL001",
    "transactionDateTime": "2026-03-30T21:00:00Z",
    "amount": {
        "currency": "EUR",
        "value": 11.2
    },
    "merchant": {
        "transactionId": "3064581",
        "terminalId": 45546
    },
    "paymentType": "PURS",
    "notificationID": "a433453e-6e40-4f53-6e40-4985cffa36f6",
    "merchantInitiatedTransaction": {
        "type": "RCRR",
        "amountQualifier": "ACTUAL"
    }
}

Credit Card – Recurring Payments (MIT)

1. Overview

CARD recurring payment webhooks for Merchant Initiated Transactions (MIT) represent transactions executed by the merchant without customer interaction, based on previously established consent.

These transactions are used to:

perform recurring collections
execute subsequent payments using stored credentials

These transactions are executed without customer interaction and rely on a previously established CIT authorization.

These notifications use:

paymentMethod = CARD
paymentType = MITR

The webhook payload extends the generic structure with a merchantInitiatedTransaction block that defines the recurring payment context.

2. Extension Block: merchantInitiatedTransaction

{
    "merchantInitiatedTransaction": {
        "type": "string",
        "amountQualifier": "string"
    }
}

3. Field Description

Field	Description
`type`	Type of recurring model (e.g. UCOF, RCRR)
`amountQualifier`	Indicates whether the amount is estimated or actual

In MIT flows:

validityDate is not present
schedule is not present

These elements are only applicable to CIT recurring setups.

4. Status Semantics

The result of the transaction is represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → transaction successfully processed
paymentStatus = Declined → transaction rejected

Recurring context is determined by:

merchantInitiatedTransaction.type

Typical values include:

UCOF → unscheduled credential-on-file transaction
RCRR → recurring transaction

5.1 Complete Payload Example – MIT (UCOF) Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2nYaNUC3hFpqd0HGq4Z",
    "transactionDateTime": "2022-12-23T10:48:39.153Z",
    "amount": {
        "currency": "EUR",
        "value": 5.16
    },
    "merchant": {
        "transactionId": "6540474",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "MITR",
    "notificationID": "c9786e7e-dc2a-4611-8a31-4b8197f41138",
    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "amountQualifier": "ESTIMATED"
    }
}

5.2 Complete Payload Example – MIT (Recurring / RCRR) Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2K9YuqPQuC9NkdCvDA4",
    "transactionDateTime": "2023-01-06T00:00:03.378Z",
    "amount": {
        "currency": "EUR",
        "value": 11.2
    },
    "merchant": {
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "MITR",
    "notificationID": "3a9d8777-292d-48fb-971c-6e6558de0fd5",
    "merchantInitiatedTransaction": {
        "type": "RCRR",
        "amountQualifier": "ACTUAL"
    }
}

5.3 Complete Payload Example – MIT (UCOF) Declined

{
    "returnStatus": {
        "statusMsg": "Declined",
        "statusCode": "10.106.0001"
    },
    "paymentStatus": "Declined",
    "paymentMethod": "CARD",
    "transactionID": "s2nYaNUC3hFpqd0IHq5A",
    "transactionDateTime": "2022-12-23T10:48:39.153Z",
    "amount": {
        "currency": "EUR",
        "value": 5.16
    },
    "merchant": {
        "transactionId": "6540474",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "MITR",
    "notificationID": "c9786e7e-dc2a-4611-8a31-4b8197f41138",
    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "amountQualifier": "ESTIMATED"
    }
}

Credit Card – Token Generation

1. Overview

CARD token generation webhooks represent transactions where a card token is created for subsequent use in future payments.

These transactions are typically associated with an authorization flow in which the card details are captured and a reusable token is returned.

These notifications use:

paymentMethod = CARD
paymentType = AUTH

The webhook payload extends the generic structure with a token block containing the generated token data.

2. Extension Block: token

{
    "token": {
        "tokenType": "string",
        "value": "string"
    }
}

3. Field Description

Field	Description
`tokenType`	Type of generated token
`value`	Token value generated for subsequent use

In addition to the token block, token generation webhook payloads may also include:

Field	Description
`internalTransactionId`	Internal SIBS transaction identifier

4. Status Semantics

The result of the token generation operation is represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → token successfully generated
paymentStatus = Declined → token generation failed

In this context, the generated token becomes available in the token block of the webhook payload.

5. Complete Payload Example – Token Generation Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "sandboxfghwTKNGEN000",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": 19.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008dsw212",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "AUTH",
    "token": {
        "tokenType": "Card",
        "value": "fjklvnrtinrt435356jv"
    },
    "internalTransactionId": "S13074000501340S",
    "notificationID": "462ec85b-5e1a-4a00-a4d7-97ddfe321567"
}

Credit Card – Token Purchase

1. Overview

TOKEN purchase webhooks represent payments executed using a previously generated token.

These transactions use the stored token as the payment instrument, avoiding the need to collect card details again. In this context, the paymentMethod is TOKEN, indicating that the transaction is executed using a stored credential rather than raw card data.

These notifications use:

paymentMethod = TOKEN
paymentType = PURS

The webhook payload extends the generic structure with a token block containing the token used in the payment.

2. Extension Block: token

{
    "token": {
        "tokenType": "string",
        "value": "string"
    }
}

3. Field Description

Field	Description
`tokenType`	Type of token used for the payment
`value`	Token value used in the transaction

The token block identifies the stored credential used to execute the payment.

4. Status Semantics

The result of the token-based payment is represented by:

paymentStatus
returnStatus

Typical outcomes include:

paymentStatus = Success → payment successfully completed using the token
paymentStatus = Declined → payment using the token was rejected

In this context, the token is not being created, but consumed as the payment instrument.

5. Complete Payload Example – Token Purchase Success

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "TOKEN",
    "transactionID": "s2grnvtruigbitu845hhtn",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": 19.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008mvn432kop",
        "terminalId": 45546,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "Card",
        "value": "gbtyhyujyuikuier45646ger4"
    },
    "notificationID": "462ec85b-5e1a-4a00-a4d7-97d345fds234"
}

Extension Matrix

paymentMethod	paymentType	Extension Block	Description
MBWAY	PURS	token	MB WAY one-off payment (alias / MSISDN)
REFERENCE	PREF	paymentReference	Multibanco reference lifecycle (generation and payment)
MBWAY	AUTH / CAUT	mbwayMandate (full)	MB WAY mandate lifecycle (creation, renewal, suspension, cancellation)
MANDATE	PURS	mbwayMandate (reduced)	Payment over existing MB WAY mandate
CARD	PURS	—	One-off card payment (no extension block)
CARD	AUTH / PURS	merchantInitiatedTransaction	Cardholder Initiated Transactions (CIT – UCOF / RCRR)
CARD	MITR	merchantInitiatedTransaction	Merchant Initiated Transactions (MIT – UCOF / RCRR)
CARD	AUTH	token	Token generation (card tokenization)
TOKEN	PURS	token	Payment using previously generated token

1. Interpretation Guidelines

The generic structure (E.1.1 Generic Webhook Structure) is always present
Extension blocks are context-dependent
Multiple extension blocks may appear in the same payload
Absence of extension blocks is valid
Extension blocks are additive and do not modify the generic structure
Unknown fields or blocks should be safely ignored to ensure forward compatibility
The transactionID should be used as the primary identifier to correlate webhook notifications with previously initiated transactions.
Webhook notifications may be delivered multiple times and should be processed in an idempotent manner.

Summary

Webhook payloads extend the generic structure with method-specific data blocks.

These extensions:

provide contextual information for each payment method
vary depending on operation and lifecycle stage
do not alter the generic contract

The combination of:

E.1.1 Generic Webhook Structure (generic structure)
E.1.2 Webhook Payload Variants by Payment Method (method-specific extensions)

provides a complete and consistent model for webhook processing.

PAYMENT GATEWAY

[THK] E.1.2 Webhook Payload Variants by Payment Method

Overview

Structure Principles

MB WAY – One-Off Payments

Credit Card – One-Off Payments

Referencia Multibanco – One-Off Payments

MB WAY Authorised Payments – Recurring Payments

MB WAY Authorised Payments – Collection

Credit Card – Recurring Payments (CIT)

Credit Card – Recurring Payments (MIT)

Credit Card – Token Generation

Credit Card – Token Purchase

Extension Matrix

Summary

On this page: