Guides

Card Transactions

Suggest Edits

This page describes different flows that would occur as part of a card transaction made by one of your customers, as well as the transactions created and the webhooks generated by the Shaype platform.


Card Transaction Scenarios

1. Hold Authorisation Request + Settlement

This is the most common scenario.

Authorisation is the stage in a transaction life-cycle where a merchant requests approval for a card payment amount. If the authorisation is approved, the amount is ring-fenced on the card. Typically the merchant then has up 28 days to request the transfer of the authorised funds.

Settlement (also known as presentment or clearing request) is a financial transaction where Shaype receives a request to settle an amount that was previously authorised on a card. A settlement is typically linked to a previous authorisation transaction. The majority of presentment transactions are requests for settlement of transactions authorised the previous day. However, for a normal authorisation, under current card scheme rules, merchants have up to 7-10 days to request settlement of an authorisation.

  • As Shaype partners with Visa for card services, the Shaype platform receives transaction authorisation requests from VISA.
  • The platform perform two actions internally
    • Performs internal checks, including account balance verification, limit assessments, rule enforcement, and fraud detection. Based on these checks, the platform determines the transaction outcome.
    • If all checks passed, platform will block the requested amount by increasing held balance on an account and reduce the available balance.
  • Acknowledges the transaction outcome to VISA
  • Then the platform sends transaction details, along with the outcome, transaction type CARD_TRANSACTION, to the client via webhook notifications.
  • Shaype receives a request from VISA to settle an amount that was previously authorised.
  • Upon receiving the settlement request from VISA, Shaype platform internally lifts the block on account and deducts the transaction amount from balance
  • After successfully processing the settlement, Shaype platform sends a webhook notification to the Client to confirm/inform that the transaction has been settled.

📘

Authorisation Hold Key Points

  • Hold and settlement will have a different transactionHayId however, there is a field called relatedHoldHayId that will reference the ID of the original hold.
  • Hold webhook will have
    "transactionType": "CARD_TRANSACTION"
    "isPending": true
  • Settlement webhook will have
    "transactionType": "CARD_TRANSACTION_SETTLED"
    "isPending": false
Authorisation Hold Webhook Sample 
{
  "customerHayId": "1111a53d-d8e0-45af-9977-6309879cedd7",
  "idempotencyKey": "22228600-489b-4dc9-8177-d712024c3c5d",
  "type": "TRANSACTION",
  "productId": "33338e33-77ce-fdfa-0188-cfa462650060",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "44449ce6-3251-4a18-ac77-439e370e6bb4",
    "accountHayId": "555507d1-10f8-41f9-ba77-d71542ba4e4c",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -8.40
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 2.73
    },
    "isPending": true,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2025,
      1,
      31,
      5,
      40,
      49,
      695961000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": true,
      "isMobileWalletPayment": false,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 11.13
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 8.4
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 2.73
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 2.73
      }
    },
    "cardHayId": "66660ee3-f26d-47f9-8d77-a475170043b8",
    "customerHayId": "1111a53d-d8e0-45af-9977-6309879cedd7",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "IGA (Mt Cotton)",
    "merchantName": null,
    "category": null,
    "merchantId": "000009493578577",
    "relatedHoldHayId": null,
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}
Settlement Webhook Sample 
{
  "customerHayId": "1111a53d-d8e0-45af-9977-6309879cedd7",
  "idempotencyKey": "777797a5-9b88-49a6-aa77-6918ee8dfc1e",
  "type": "TRANSACTION",
  "productId": "33338e33-77ce-fdfa-0188-cfa462650060",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": 888858f5-12bc-4e06-a577-21776b900a12",
    "accountHayId": "555507d1-10f8-41f9-ba77-d71542ba4e4c",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -8.40
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 2.73
    },
    "isPending": false,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2025,
      1,
      31,
      5,
      40,
      49,
      695961000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION_SETTLED",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": true,
      "isMobileWalletPayment": false,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 2.73
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 2.73
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 2.73
      }
    },
    "cardHayId": "66660ee3-f26d-47f9-8d77-a475170043b8",
    "customerHayId": "1111a53d-d8e0-45af-9977-6309879cedd7",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "IGA (Mt Cotton)",
    "merchantName": null,
    "category": null,
    "merchantId": "000009493578598",
    "relatedHoldHayId": "44449ce6-3251-4a18-ac77-439e370e6bb4",
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}

2. Incremental Authorisation

An incremental authorisation is an additional authorisation, following a previous transaction authorisation, which is used to request an additional amount for the same product or service purchased by the cardholder.

It is commonly used by merchants in the hospitality and tourism industry, for items such as hotel bills and car rentals, where the final amount is not known at the time the original authorisation is requested.

It follows the same process as the first authorisation, where the platform performs all necessary checks for the incremental amount.

📘

Incremental Authorisation Key points

  • Initial hold and hold Increase will have same transactionHayId
  • Hold Increase will have the amount of the updated hold (original hold + increase)
  • The settlement will have a different transactionHayId however, there is a field called relatedHoldHayId that will reference the ID of the original hold.
  • Hold and Hold Increase webhook will have
    "transactionType": "CARD_TRANSACTION"
    "isPending": true
  • Settlement webhook will have
    "transactionType": "CARD_TRANSACTION_SETTLED"
    "isPending": false
Initial Hold Webhook Sample 
{
  "customerHayId": "111c046d-32f4-4920-af32-7df893f85b5b",
  "idempotencyKey": "22272762-37a1-4911-b432-b51fd032cc0d",
  "type": "TRANSACTION",
  "productId": "33368fda-8047-2f19-0132-477797f6016e",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "4441ae58-1f2b-417d-98d3-08c8b12504e0",
    "accountHayId": "5554720e-33ed-4bfe-9832-9f87de9e8fff",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -9.00
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 5066
    },
    "isPending": true,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2025,
      1,
      9,
      12,
      12,
      34,
      786545000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": false,
      "isMobileWalletPayment": false,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 232.64
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 166.64
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 66.00
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 5066
      }
    },
    "cardHayId": "6666eb76-a0cb-4c1c-a9c3-4e89b40b70ff",
    "customerHayId": "111c046d-32f4-4920-af32-7df893f85b5b",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "PayPal",
    "merchantName": null,
    "category": null,
    "merchantId": "000980200061932",
    "relatedHoldHayId": null,
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}
Incremental Hold Webhook Sample 
{
  "customerHayId": "111c046d-32f4-4920-af32-7df893f85b5b",
  "idempotencyKey": "123e32c2-5b6c-4575-ad32-2f25a68d27e2",
  "type": "TRANSACTION",
  "productId": "33368fda-8047-2f19-0132-477797f6016e",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "4441ae58-1f2b-417d-98d3-08c8b12504e0",
    "accountHayId": "5554720e-33ed-4bfe-9832-9f87de9e8fff",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -19.00
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 5065
    },
    "isPending": true,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2025,
      1,
      9,
      12,
      12,
      34,
      786545000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": true,
      "isMobileWalletPayment": false,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 241.64
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 176.64
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 65.00
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 5065
      }
    },
    "cardHayId": "6666eb76-a0cb-4c1c-a9c3-4e89b40b70ff",
    "customerHayId": "111c046d-32f4-4920-af32-7df893f85b5b",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "PayPal",
    "merchantName": null,
    "category": null,
    "merchantId": "000980200061932",
    "relatedHoldHayId": null,
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}
Settlement Webhook Sample 
{
  "customerHayId": "111c046d-32f4-4920-af32-7df893f85b5b",
  "idempotencyKey": "4560ac1d-fd93-442b-ab32-db57a64e3412",
  "type": "TRANSACTION",
  "productId": "33368fda-8047-2f19-0132-477797f6016e",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "7890c496-ff68-40d6-9932-af154202924b",
    "accountHayId": "5554720e-33ed-4bfe-9832-9f87de9e8fff",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -19.00
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 5075
    },
    "isPending": false,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2025,
      1,
      9,
      12,
      12,
      34,
      786545000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION_SETTLED",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": false,
      "isMobileWalletPayment": false,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 75
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 75
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 5075
      }
    },
    "cardHayId": "6666eb76-a0cb-4c1c-a9c3-4e89b40b70ff",
    "customerHayId": "111c046d-32f4-4920-af32-7df893f85b5b",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "PayPal",
    "merchantName": null,
    "category": null,
    "merchantId": "000980200061995",
    "relatedHoldHayId": "4441ae58-1f2b-417d-98d3-08c8b12504e0",
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}

3. Authorisation Reversal / Hold Decrease (partial/full)

A reversal transaction occurs when some or all of the funds held by an earlier authorisation hold are released or canceled. This would occur before the transaction has been settled and can involve either a partial or full reversal of the previous hold.

📘

Reversal Authorisation Key Points

  • Initial hold and reversal will have same transactionHayId
  • The settlement will have a different transactionHayId however, there is a field called relatedHoldHayId that will reference the ID of the original hold.
  • Hold will have "transactionType": "CARD_TRANSACTION" and "isPending": true
  • Reversal will have
    "transactionType": "CARD_TRANSACTION_REFUND"
    "isPending": true (pre-settlement)
  • Settlement webhook will have
    "transactionType": "CARD_TRANSACTION_SETTLED"
    "isPending": false
Initial Hold Webhook Sample 
{
  "customerHayId": "d09010f7-62f8-4575-8544-836447fd701e",
  "idempotencyKey": "d80a2248-068d-4664-b944-94b4e6e8e149",
  "type": "TRANSACTION",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "fba1cf60-116d-4704-b744-2e937796e3fa",
    "accountHayId": "dae57032-4ad7-44e3-b8a4-c9f7dae4ea1b",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -5.00
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 1.37
    },
    "isPending": true,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2024,
      3,
      20,
      0,
      5,
      11,
      675362000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": true,
      "isMobileWalletPayment": true,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 10.87
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 9.5
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 1.37
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 1.37
      }
    },
    "cardHayId": "88d88c60-c894-432a-95b4-cf907aec8d66",
    "customerHayId": "d09010f7-62f8-4575-8544-836447fd701e",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "Coca-Cola Europacific Partners",
    "merchantName": null,
    "category": null,
    "merchantId": "26185344",
    "relatedHoldHayId": null,
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}
Reversal Transaction Webhook Sample 
{
  "customerHayId": "d09010f7-62f8-4575-8544-836447fd701e",
  "idempotencyKey": "67b5c1f1-d73e-4481-aa44-f597f6fd9e31",
  "type": "TRANSACTION",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "fba1cf60-116d-4704-b744-2e937796e3fa",
    "accountHayId": "dae57032-4ad7-44e3-b8a4-c9f7dae4ea1b",
    "currencyAmount": {
      "currency": "AUD",
      "amount": 0.5000
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 1.87
    },
    "isPending": true,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2024,
      3,
      20,
      0,
      5,
      11,
      675362000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION_REFUND",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": false,
      "isMobileWalletPayment": true,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 10.87
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 9
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 1.87
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 1.87
      }
    },
    "cardHayId": "88d88c60-c894-432a-95b4-cf907aec8d66",
    "customerHayId": "d09010f7-62f8-4575-8544-836447fd701e",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "Coca-Cola Europacific Partners",
    "merchantName": null,
    "category": null,
    "merchantId": "26185344",
    "relatedHoldHayId": null,
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}
Settlement Webhook Sample 
{
  "customerHayId": "d09010f7-62f8-4575-8544-836447fd701e ",
  "idempotencyKey": "99f35464-8d9d-40ff-a844-b0faa6d731ab",
  "type": "TRANSACTION",
  "firebaseDeviceToken": null,
  "actionOwner": null,
  "cardHayId": null,
  "accountStatusChangeEvent": null,
  "customerStatusUpdatedEvent": null,
  "transactionEvent": {
    "transactionHayId": "88614cd9-cedd-4595-a044-39ed95c05a12",
    "accountHayId": "dae57032-4ad7-44e3-b8a4-c9f7dae4ea1b",
    "currencyAmount": {
      "currency": "AUD",
      "amount": -4.50
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 1.87
    },
    "isPending": false,
    "outcome": "ACCEPTED",
    "transactionTimeUtc": [
      2024,
      3,
      20,
      0,
      5,
      11,
      675362000
    ],
    "cardPreferenceOutcome": null,
    "cardProcessorResponse": null,
    "transactionType": "CARD_TRANSACTION_SETTLED",
    "cardUsageDetails": {
      "isMagneticStripePayment": null,
      "isContactless": null,
      "isCardPresent": true,
      "isMobileWalletPayment": true,
      "isAtmWithdrawal": false
    },
    "isAtmTransaction": false,
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 1.87
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 1.87
      },
      "legacyAvailableBalance": {
        "currency": "AUD",
        "amount": 1.87
      }
    },
    "cardHayId": "88d88c60-c894-432a-95b4-cf907aec8d66",
    "customerHayId": "d09010f7-62f8-4575-8544-836447fd701e",
    "ruleDetails": null,
    "counterpartDetails": null,
    "originId": null,
    "originType": null,
    "counterpartName": "Coca-Cola Europacific Partners",
    "merchantName": null,
    "category": null,
    "merchantId": "26185330",
    "relatedHoldHayId": "fba1cf60-116d-4704-b744-2e937796e3fa",
    "description": null,
    "mandatePaymentDetails": null,
    "returnReason": null
  },
  "cardStatusChangeEvent": null,
  "customerDetailsChangeEvent": null,
  "cardAdditionToWalletEvent": null,
  "reminderType": null,
  "scheduledPaymentEvent": null,
  "onboardingFailedEvent": null,
  "directEntryEvent": null,
  "mandateDuePaymentEvent": null,
  "mandateEvent": null,
  "mandatePaymentEvent": null,
  "applePayRewardForCustomerEvent": null,
  "cardExpiryReminderEvent": null,
  "mandateActionExpirationEvent": null
}

4. Refund

A refund transaction occurs when a merchant refunds money to the cardholder, typically relating to a previously processed (settled) transaction. The merchant/acquirer submits a request for a partial or a full refund of a previously paid amount.

The refund transaction would be a separate transaction from the original purchase transaction.

📘

Refund Transaction Key Points

  • Refund transaction will have different transactionHayId as it occurs after the settlement.
  • Refund transaction will have
    "transactionType": "CARD_TRANSACTION_REFUND"
    "isPending": false (post-settlement)
Refund Transaction Webhook Sample 
{
  "customerHayId": "dc15c3fb-4feb-49d4-a278-b8d5d7d93dcd",
  "idempotencyKey": "fbec65cd-00cf-423e-9d78-da1c885dc911",
  "type": "TRANSACTION",
  "productId": "8aa68667-8009-b773-0178-09f41bf00124",
  "transactionEvent": {
    "transactionHayId": "63c86de3-9146-4377-a388-421d08697d19",
    "accountHayId": "98032560-0e21-475b-b876-e8672becb8d8",
    "currencyAmount": {
      "currency": "AUD",
      "amount": 5.99
    },
    "updatedBalance": {
      "currency": "AUD",
      "amount": 3305.99
    },
    "isPending": false,
    "counterpartName": "IGA (Piedimonte\u0027s Fitzroy North)",
    "outcome": "ACCEPTED",
    "transactionTimeUtc": "2024-09-16T08:17:18.947713Z",
    "isAtmTransaction": false,
    "transactionType": "CARD_TRANSACTION_REFUND",
    "cardUsageDetails": {
      "isCardPresent": false,
      "isMobileWalletPayment": false,
      "isAtmWithdrawal": false
    },
    "accountBalances": {
      "totalBalance": {
        "currency": "AUD",
        "amount": 5.99
      },
      "heldBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "lockedBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "stacksBalance": {
        "currency": "AUD",
        "amount": 0
      },
      "availableBalance": {
        "currency": "AUD",
        "amount": 5.99
      }
    },
    "cardHayId": "1ade4041-27f8-4e07-ab78-bbed3ae1e740",
    "customerHayId": "dc15c3fb-4feb-49d4-a278-b8d5d7d93dcd",
    "merchantId": "000009391315129"
  }
}

Balance Update

The platform manages multiple balances including held balance, available balance, total balance, and others. For detailed information, please refer to the Account Balance Documentation.

The platform updates these balances based on the behaviour of incoming transactions:

  • Authorization Hold Request and Hold with Increment Transaction:
    • The held balance increases.
    • The available balance decreases accordingly.
  • Hold with Reversal Transaction:
    • The held balance decreases.
    • The available balance increases accordingly.

Updated 7 days ago